From 190bd935f93c60f70a5f908314a8bb9a44d2e5c2 Mon Sep 17 00:00:00 2001 From: Thomas Dietrich Date: Sat, 16 Dec 2017 22:04:24 +0100 Subject: [PATCH] Add Home Builder and Android app articles from external repos (#594) * Add homebuilder to maven chain * Add android app docs to maven chain * Correct homebuilder URL * Introduce maven logging into process script * Fix linter warnings in update script * Add first copy of homebuilder article * Add Home Builder to menu and packages Signed-off-by: Thomas Dietrich --- _includes/user-menu.html | 1 + configuration/homebuilder.md | 116 +++++++++++++++++++++++++++++++++++ configuration/packages.md | 1 + pom.xml | 40 ++++++++++++ process_addons.groovy | 16 ++--- update-external-resources.sh | 14 +++-- 6 files changed, 175 insertions(+), 13 deletions(-) create mode 100644 configuration/homebuilder.md diff --git a/_includes/user-menu.html b/_includes/user-menu.html index fe20fb7f27..34e9a57f3c 100644 --- a/_includes/user-menu.html +++ b/_includes/user-menu.html @@ -54,6 +54,7 @@
  • Services
  • Initial Setup Packages
    • +
  • Home Builder
  • Paper UI
  • HABmin
  • HABPanel
    • diff --git a/configuration/homebuilder.md b/configuration/homebuilder.md new file mode 100644 index 0000000000..68168be5af --- /dev/null +++ b/configuration/homebuilder.md @@ -0,0 +1,116 @@ +--- +layout: documentation +title: Home Builder +source: https://github.com/openhab/openhab-core/blob/master/bundles/org.openhab.ui.homebuilder/USAGE.md +--- + +{% include base.html %} + + + +# Home Builder + +Boilerplate for the [Items](http://docs.openhab.org/configuration/items.html), [sitemap](http://docs.openhab.org/configuration/sitemaps.html) files and [HABPanel](http://docs.openhab.org/addons/uis/habpanel/readme.html) dashboard. + +## Features + +- Classifies the objects within each room and creates groups for them +- Optionally adds icons from [Classic Icon Set](http://docs.openhab.org/addons/iconsets/classic/readme.html) to the items +- Optionally adds Tags to the items - convenient for [HomeKit](http://docs.openhab.org/addons/io/homekit/readme.html)/[Hue Emulation](http://docs.openhab.org/addons/io/hueemulation/readme.html#device-tagging) add-ons users +- Automatically aligns the items vertically +- Generates a [Sitemap](http://docs.openhab.org/configuration/sitemaps.html) file +- Generates a set of HABPanel Dashboards corresponding with the Items + +## Usage + +### Localization + +Home Builder recognizes the locale by itself by simply checking your existing language configuration through openHAB's REST API. +All the Item's labels generated with Home Builder will be translated to the language of your choice. + +### Home Name + +Provide your Home Name. It'll be a label for the `Home` Item, as well as the name of your Sitemap. +The `Home` item is the root item of your entire home structure - it contains all the floors as well as groups of Objects. + +### Floors + +After that you can select the number of stories (floors) comprising the building. +Each floor will have its own `Group` Item - Ground Floor will be called `GF`, First Floor `FF` and so on. +If there's only one floor, no additional `Group` Items shall be created. + +### Rooms + +Choose the rooms by simply selecting them on the list. +They contain the icons that you can adjust later. +If there's a custom room you'd like to add (e.g. a Piano room), provide its **label** to the field and hit Enter. +It will be added to the list. +The custom Item's **name** will be generated - e.g. for the "Piano Room" label the name would be `PianoRoom` + +Note that the room doesn't appear on the Objects list right away - it's a known defect. +In order to add Objects to your custom room, simply remove the room from the list and re-add it again. + +### Objects + +Objects are the devices or sensors that physically exist in the room. +They are represented in Home Builder as singular Items (e.g. Light, Window, Motion Sensor, Temperature etc.) +Each Object is added to the Items list with its corresponding type, label, icon and list of Groups. +E.g. `Light` Object in the Bedroom will appear as: + +```java +Switch Bedroom_Light "Light" (Bedroom, gLight) {channel=""} +``` + +Note that the Objects have the `{channel=""}` prefilled for convenience. +You can turn it off with "Append channel to the non-Group items" option. + +#### Custom Objects + +You can use the existing Objects from the list, or create custom ones. +Simply typing the custom Object's label in the field will create it. +E.g. typing `Lamp` will result in: + +```java +Switch Bedroom_Lamp "Lamp" (Bedroom, gLamp) {channel=""} +``` + +Note that the default type for your custom Item is `Switch`. +You can, however, change it by typing `{type}:{label}`, e.g. `Number:Pressure` so it appears as: + +```java +Number Bedroom_Pressure "Pressure" (Bedroom, gPressure) {channel=""} +``` + +#### Grouping Objects + +All Objects of the same kind are being grouped within Home Builder. +If you add a `Light` Object in bedroom, you'll see that there's an additional Item on the bottom: + +```java +Group:Switch:OR(ON, OFF) gLight "Light" (Home) +``` + +It doesn't matter if there's just one Object or dozens - they will be grouped within this `Group` Item. + +## Items + +You can choose to generate textual `*.items` file content or construct a request directly to the REST API that'll create the items for you. + +## Sitemap + +You can generate a simple sitemap with Home Builder too. +Sitemap name will be generated from "Home Setup Name" parameter that you've provided before. +Don't forget to save your sitemap with the correct file name. + +Sitemaps generated with Home Builder contain a `Frame` for each floor. +Each one of those Frames contain corresponding rooms. + +Last Frame inside the Sitemap is a list of Object's groups. + +## HABPanel Dashboard + +Home Builder will help you with creating your set of dashboards for [HABPanel](http://docs.openhab.org/addons/uis/habpanel/readme.html) too. +It creates a separate dashboard for each group of Objects. +All you need to do is to copy the generated JSON structure and paste it in HABPanel settings page. +The page is located in the following URL: `http://{youropenHAB:8080}/habpanel/index.html#/settings/localconfig` +Note that it'll override the existing Panel configuration! \ No newline at end of file diff --git a/configuration/packages.md b/configuration/packages.md index 93ce3615d0..a07b73c88c 100644 --- a/configuration/packages.md +++ b/configuration/packages.md @@ -23,6 +23,7 @@ This is the recommended package for the normal user. It contains the most common This package thus installs: +- [Home Builder](homebuilder.html){:target="_blank"} as a getting-started generator for your home - [Paper UI](../addons/uis/paper/readme.html){:target="_blank"} for system administration, including item access - [Basic UI](../addons/uis/basic/readme.html){:target="_blank"} as the new modern web UI for mobile devices - [HABPanel](../addons/uis/habpanel/readme.html){:target="_blank"} as a dashboard UI for (e.g. wall-mounted) tablets diff --git a/pom.xml b/pom.xml index 3e2edac044..63e358611c 100644 --- a/pom.xml +++ b/pom.xml @@ -402,6 +402,24 @@ + + copy-android-images + process-resources + + copy-resources + + + ${basedir}/addons/uis/apps + + + ${basedir}/${basedir}/.external-resources/openhab.android/docs + + images/*.png + + + + + @@ -409,6 +427,28 @@ copy-rename-maven-plugin 1.0 + + copy-oh-homebuilder-docs + process-resources + + copy + + + ${basedir}/.external-resources/openhab-bundles/openhab-core/bundles/org.openhab.ui.homebuilder/USAGE.md + ${basedir}/configuration/homebuilder.md + + + + copy-oh-android-docs + process-resources + + copy + + + ${basedir}/.external-resources/openhab.android/docs/USAGE.md + ${basedir}/addons/uis/apps/android.md + + copy-oh-mycroft-docs process-resources diff --git a/process_addons.groovy b/process_addons.groovy index e55c1ae168..069dd9bf2b 100644 --- a/process_addons.groovy +++ b/process_addons.groovy @@ -27,9 +27,9 @@ def process_addon_type = { features, sources, type, collection, suffix, lblremov files.eachFile { def name = it.name println name - if (! name.contains(type)) println "[WARN] Addon package name doesn't contain '${type}'." + if (! name.contains(type)) log.warn("Addon package name doesn't contain '${type}'.") if (name.endsWith('.test')) { - println "[INFO] Skip." + log.info("Skip.") it.deleteDir() } else { def id = it.name @@ -41,13 +41,13 @@ def process_addon_type = { features, sources, type, collection, suffix, lblremov it.renameTo(simpleNameDir) def readme = new File(simpleNameDir.path, 'README.md') if (! readme.exists()) { - println "[WARNING] No README.md found." + log.warn("No README.md found.") } else { readme.renameTo(new File(simpleNameDir.path, 'readme.md')) //println readme def label = readme.readLines().find{it.startsWith('#')} if (label == null) { - println "[WARNING] No level 1 header found." + log.warn("No level 1 header found.") label = id } else { label = label.replace('#', '') @@ -57,7 +57,7 @@ def process_addon_type = { features, sources, type, collection, suffix, lblremov label = label.trim() } def logo = new File(project.basedir, 'images/addons/' + id + '.png').exists() - if (! logo) println "[INFO] No logo found." + if (! logo) log.info("No logo found.") def description = "" boolean firstHeadline = false for (def line : readme.readLines()) { @@ -100,7 +100,7 @@ def process_addon_type = { features, sources, type, collection, suffix, lblremov } def temp_folder = new File(project.basedir, "_${collection}/".concat(source)) if (temp_folder.list().length > 0) { - println "[WARNING] Folder not empty after processing." + log.warn("Folder not empty after processing.") } temp_folder.deleteDir() } @@ -119,7 +119,9 @@ def process_addon_files = { features -> } if (! new File(project.basedir, ".external-resources").exists()) { - println "\n\n[WARNING] Folder '.external-resources' missing. Please use the update script to run all steps in order. Exiting.\n\n" + println "\n" + log.warn("Folder '.external-resources' missing. Please use the update script to run all steps in order. Exiting.") + println "\n" return } def features = [:] diff --git a/update-external-resources.sh b/update-external-resources.sh index 05ac0cb478..a144e1d6ec 100755 --- a/update-external-resources.sh +++ b/update-external-resources.sh @@ -7,20 +7,20 @@ set -e # Helper functions timestamp() { date +"%F_%T_%Z"; } -echo_process() { echo -e "\e[1;94m$(timestamp)\e[0m $*"; } +echo_process() { echo -e "\\e[1;94m$(timestamp)\\e[0m $*"; } # Log everything to a file #exec &> >(tee -a "update-docs-$(date +%Y-%m-%d_%H%M%S).log") # Switch to the script folder -cd $(dirname $0) || exit 1 +cd "$(dirname $0)" || exit 1 if [ ! -f "$(dirname $0)/CNAME" ]; then echo "I'm confused and don't know where I am. Exiting." >&2 exit 1 fi -resourcefolder=$(dirname $0)/.external-resources +resourcefolder=$(dirname "$0")/.external-resources mkdir -p "$resourcefolder" -echo -e "# About\n\nUsed to temporarily store repository clones from related openHAB projects for 'update-external-resources.sh'." > "$resourcefolder/README.md" +echo -e "# About\\n\\nUsed to temporarily store repository clones from related openHAB projects for 'update-external-resources.sh'." > "$resourcefolder/README.md" # Prerequisites if ! command -v git &>/dev/null || ! command -v mvn &>/dev/null; then @@ -33,13 +33,14 @@ echo_process "Updating the base openhab-docs repo... (skipping)" # Parameters: $1=name, $2=GitHub project pull_or_clone_repo() { - echo_process "Updating or Cloning the '$1' repo... " if [ -d "$resourcefolder/$1" ]; then + echo_process "Updating the '$1' repo... " git -C "$resourcefolder/$1" checkout master git -C "$resourcefolder/$1" pull else + echo_process "Cloning the '$1' repo... " mkdir "$resourcefolder/$1" - git clone https://github.com/$2 "$resourcefolder/$1" + git clone "https://github.com/$2" "$resourcefolder/$1" fi } @@ -51,6 +52,7 @@ pull_or_clone_repo "openhab-bundles" "openhab/openhab-bundles.git" pull_or_clone_repo "openhabian" "openhab/openhabian.git" pull_or_clone_repo "openhab-alexa" "openhab/openhab-alexa.git" pull_or_clone_repo "openhab-mycroft" "openhab/openhab-mycroft.git" +pull_or_clone_repo "openhab.android" "openhab/openhab.android.git" echo_process "Updating submodules of the 'openhab-bundles' repo... " git -C "$resourcefolder/openhab-bundles" submodule update --recursive --remote --init