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 <Thomas.Dietrich@tu-ilmenau.de>
2017-12-16 22:04:24 +01:00 · 2017-12-16 22:04:24 +01:00 · 190bd935f9
parent a459e002c1
commit 190bd935f9
6 changed files with 175 additions and 13 deletions
--- a/_includes/user-menu.html
+++ b/_includes/user-menu.html
@ -54,6 +54,7 @@
      <li><a href="{{docu}}/configuration/services.html">Services</a></li>
      <hr />
      <li><a href="{{docu}}/configuration/packages.html">Initial Setup Packages</a></li>
+      <li><a href="{{docu}}/configuration/homebuilder.html">Home Builder</a></li>
      <li><a href="{{docu}}/configuration/paperui.html">Paper UI</a></li>
      <li><a href="{{docu}}/configuration/habmin.html">HABmin</a></li>
      <li><a href="{{docu}}/configuration/habpanel.html">HABPanel</a></li>
--- a/configuration/homebuilder.md
+++ 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 %}
+
+<!-- Attention authors: Do not edit directly. Please add your changes to the appropriate source repository -->
+
+# 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"    <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"    <none>    (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"    <none>    (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"    <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!
--- 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
--- a/pom.xml
+++ b/pom.xml
@ -402,6 +402,24 @@
              </resources>
            </configuration>
          </execution>
+          <execution>
+            <id>copy-android-images</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>copy-resources</goal>
+            </goals>
+            <configuration>
+              <outputDirectory>${basedir}/addons/uis/apps</outputDirectory>
+              <resources>
+                <resource>
+                  <directory>${basedir}/${basedir}/.external-resources/openhab.android/docs</directory>
+                  <includes>
+                    <include>images/*.png</include>
+                  </includes>
+                </resource>
+              </resources>
+            </configuration>
+          </execution>
        </executions>
      </plugin>
      <plugin>
@ -409,6 +427,28 @@
        <artifactId>copy-rename-maven-plugin</artifactId>
        <version>1.0</version>
        <executions>
+          <execution>
+            <id>copy-oh-homebuilder-docs</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>copy</goal>
+            </goals>
+            <configuration>
+              <sourceFile>${basedir}/.external-resources/openhab-bundles/openhab-core/bundles/org.openhab.ui.homebuilder/USAGE.md</sourceFile>
+              <destinationFile>${basedir}/configuration/homebuilder.md</destinationFile>
+            </configuration>
+          </execution>
+          <execution>
+            <id>copy-oh-android-docs</id>
+            <phase>process-resources</phase>
+            <goals>
+              <goal>copy</goal>
+            </goals>
+            <configuration>
+              <sourceFile>${basedir}/.external-resources/openhab.android/docs/USAGE.md</sourceFile>
+              <destinationFile>${basedir}/addons/uis/apps/android.md</destinationFile>
+            </configuration>
+          </execution>
          <execution>
            <id>copy-oh-mycroft-docs</id>
            <phase>process-resources</phase>
--- 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 = [:]
--- 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