HABDroid UI concept – OpenHAB for Android

Posted on Updated on

I’ve started automating some of my home using OpenHAB. As a Java programmer it fits into where my skills are and Kai has done an excellent job building an extendable platform. The community support is excellent with a passionate and helpful user base. I’ve managed to cobble together a serial binding for my Oppo bluray player, which I need to extend and then contribute back to the project. It currently just powers the device on and off, sets the verbosity mode to send updates and then listens for status updates for changes in state (playing, stopped, etc). There is a lot more in the Oppo API which I should add and test.

I’m also an Android user and have done some development. So I downloaded a recent debug HABDroid APK from cloudbees and am trying it out. Most of the commits appear to be the work of belovictor and he’s done an amazing job on this app. I especially like the Material updates applied in the recent cloudbees builds.

The HABDroid app does seem to focus on Items and their statuses rather than leading the user through Task based execution. This could be because that’s what most of the example Site map files show, or it could be factor of the target audience OpenHAB is currently aimed at. This audience appears to be developers or tinkerers, rather than their families or housemates.

This got me thinking. If I am to subject my family to the OpenHAB experience, I would like it to be simple, convenient and user friendly. The MythTV community talks a lot about WAF, or Wife Acceptance Factor. I believe UX plays a large part in this. To this end, I have been mulling over some UI concepts that I think could add a bit more “wow” and “WAF” to HABDroid, and which embrace the animations and transitions now available in Android’s material design.

 

HABDroid material UI concept
HABDroid material UI concept
Click to view at full size

The above animation is scaled down due the limitations of the theme on this blog. To view it properly, I suggest you click it and see it full size.

Credits and attributions

The following items were used in this mock up.

  • Climacons – Used for the weather icon
  • Jeremy from Sallee Design – The speaker icon is in the music set on this page
  • SAMURAY – The popcorn icon is a member of the Movie Icon Set
  • PSDgraphics – Have the retro TV icon
  • The XBMC logo is copyright to the XBMC project. Somehow I missed the name change to Kodi. I’m still running an old XBMC on my RaspberryPi.
  • Icons for YouTube, BBC iPlayer and Netflix are copyright to their respective companies. Used without seeking permission.

The HABDroid UI Concept

The UI shown in the animation above introduces a few new concepts:

  • A grid view and a lot more control over layout and colour
  • Changing colour schemes between fragments
  • Animation of the selected item and fragment transitions
  • Automatic execution of Item state changes
  • An “Intent” Item which allows starting another Android application via an Intent

A grid view and a lot more control over layout and colour

In my household, the interface to OpenHAB is the tablet. HABDroid currently supports a tablet experience by presenting the menus on the left and items on the right. I believe the introduction of a grid view and larger interaction icons suits the task focused, tablet experience well.

Introducing the Grid
Making the frame awesome

For the above layout to be successful, I believe there needs to be additional rendering specifics.
Much more control is needed on Frames. They should be able to consume less than 100% of their parent width, and have alignment capability. I believe the above could be configured like this:

sitemap home label="Welcome to OpenHAB" 
                   layout="vertical" 
                   darkPrimaryColor="#9e9e9e" 
                   primaryColor="#616161" 
                   accentColor="#b6b6b6" 
                   primaryTextColor="#b6b6b6" {

        Frame layout="grid" h-margin="3%" h-padding="20dp" {
                Group item=GF_Watch label="Watch" icon="popcorn" 
                   layout="grid" 
                   h-margin="3%" h-padding="20dp"
                   darkPrimaryColor="#b52d38" 
                   primaryColor="#e34143" 
                   accentColor="#b6b6b6" 
                   primaryTextColor="#b6b6b6" {

                        // more items in here
                }
                Group item=GF_Listen label="Listen" icon="speaker" {

                        // more items in here
                }
        }
        Frame layout="horizontal" h-align="right" h-margin="3%" {
                Text label="London" right-padding="10sp"
                Image label="" item=WeatherIcon
                Text label="[%s]" left-padding="10sp" item=WeatherTemp 
        }
        Frame layout="horizontal" h-margin="15%" color="#b6b6b6" 
              top-padding="1dp" bottom-padding="0px" 
              h-padding="0px" bottom-margin="20dp" {
                // Draws a 1dp line across the screen by colouring
                //  a Frame and making it thin and wide.
        }
}
Elements Property Values Notes
Sitemap, Frame, Group, List?? layout vertical, horizontal, grid Vertical is what HABDroid currently renders.
Horizontal is a single line horizontally.
Grid displays the items in a grid layout.
All Item types margin, v-margin, h-margin, left-margin, right-margin, top-margin, bottom-margin examples: 10%, 25dp, 15px, 11sp Percentage of parent framesize would be a good starting point, but it would also be useful to be able to specify a value that would not change between the four margins.
DP is obviously very Android specific. It stands for device pixels and is a scaled pixel count, so that pixels appear to be a similar size for different screen densities
PX is for precise amount should it be needed
SP is scaled pixels and is similar to DP but factors in the user’s font size settings on the device.
All Item types padding, v-padding, h-padding, left-padding, right-padding, top-padding, bottom-padding examples: 10%, 25dp, 15px, 11sp Percentage of parent framesize would be a good starting point, but it would also be useful to be able to specify a value that would not change between the four sides.
DP is obviously very Android specific. It stands for device pixels and is a scaled pixel count, so that pixels appear to be a similar size for different screen densities
PX is for precise amount should it be needed
SP is scaled pixels and is similar to DP but factors in the user’s font size settings on the device.
All Item types v-align, h-align center, top, bottom, left, right (as applicable) How to align the item within its parent
Frame, Group color same as current labelcolor and valuecolor settings Sets the background colour of a Frame
All Item types label=”” Ability to set the label to be empty. I’m not sure if this is currently possible. However, I expect the label to take up no space (visibility=gone in Android) if it’s empty. This is much more applicable for horizontal and grid views than vertical.

Changing colour schemes between fragments

Since a fragment is represented by a Group in the sitemap (as far as I can tell), adding the colours to the Group element would go a long way to being able to define how a fragment is coloured. Additionally, there is a new library called “Palette” with Android 5 (and backported to previous versions) which allows developers to extract colours from an image and use those colours in the UI. In my experience this is a good start but does not always achieve the nicest looking design. The result varies greatly depending on the image. For some images, the palette library is unable to determine anything other than the Primary colour. Images with large single colour areas seem to suffer this problem.
Therefore, it is advantageous to be able to specify colours rather than relying on the palette library. If no colours are provided in the sitemap, palette could then be invoked to colour the UI based on the icon the user had selected.

To give maximum flexibility in rendering the UI, and to adhere closely to the Material design recommendations, the following colours would need to be able to be specified for a Group.

  • Dark primary color
  • Primary color
  • Light primary color
  • Primary text color
  • Secondary text color
  • Accent color
  • Icon color
  • Divider color

A useful visualisation of how these colours are used is available on the materialpalette.com website.

Animation of the selected item and fragment transitions

Another feature of modern Android design is the use of animation to indicate to the user how an interaction transitions to a new screen. With recent additions to the Android API, it is now possible to animate transitions from one Activity or Fragment to another, with common elements remaining on screen. I believe it is now possible to achieve the transition effect shown in the animation above. This would go a long way to adding some extra polish to the UI, and giving some good visual clues about how the screens tie together.

Automatic execution of Item state changes

When HABDroid loads a fragment, and an Item in that fragment’s Group has a property of “automatic”, then HABDroid requests OpenHAB to change the state of that Item to the state of the automatic property. For example,

Switch item="switch01" automatic="on"

would tell HABDroid to call the OpenHAB API and set the value of switch01 to the on state if it is not already in that state.
I’m still not completely convinced about this idea, but propose it as I think there are some use cases where it could be a useful feature.

An “Intent” Item which allows starting another Android application via an Intent

As I eluded to earlier, the tablet is our primary interaction tool with OpenHAB. The tablet is also the tool we use for interacting with a number of other devices in the house. For example, we have apps that allow us to control XBMC, the Oppo Bluray player, MythTV, YouTube, MPD and initiate DLNA streams. The logical next step is to allow HABDroid to be able to start these apps when appropriate.

To support this, I propose a new Item be added to OpenHAB, which is an Intent item. Its purpose is to inform HABDroid which Intent to broadcast to the Android OS to start the relevant controller app. In the animation above, OpenHAB presents to the user an icon they can touch to start the XBMC controller application. To be as powerful as possible, the Item should allow “extras” to be configured, so that any context that the app could take advantage of can also be transferred.

It might be useful for HABDroid to allow the user to determine an App’s intent and be able to present a Share button. This is to send the intent detail to the OpenHAB administrator’s email address or similar, since the sitemap normally resides on another computer.

Comments and responses

I’ve opened a ticket on Github. Please post comments and responses there so they are all in one place.

Advertisements

New tcWebhooks payload format : Tailored JSON

Posted on

Introducing a new payload format called Tailored JSON in tcWebhooks version 0.9.27.61

This format only sends the contents of the “body” parameter as application/json. It is up to the user to define the content of the body parameter.

The easiest way to define the body is with a TeamCity build parameter called webhook.body as per the screenshot below.

Tailored JSON via the body parameter

Building tcWebHooks custom parameters from teamcity build parameters

Posted on Updated on

Custom Parameters are a feature in the tcWebhooks plugin, which allow one to send a custom string to the webhook endpoint made up of a template and variables.

Up until today, those variables have only included other values from the webhook’s payload. However, from now on it is also possible to use build paramters from the TeamCity build configuration. One now has access to the TeamCity build properties. These include properties defined by the build configuration, as well as env.*, teamcity.* and system.* properties.

An example is worth a thousand pictures

      <parameters>
        <param name="aaa_param" value="TeamCity version ${system.teamcity.version} running as user ${env.LOGNAME}" />
      <parameters>

This example parameter will add an item as per the table below.

Name Value
aaa_param TeamCity version 8.1.4 (build 30168) running as user netwolfuk

Using the TeamCity build parameters to create Custom Webhook Parameters

Additionally, any property beginning with the string “webhook.” will automatically be included in the webhook payload with the “webhook.” prefix removed. This allows custom parameters to be declared from the Teamcity build parameters rather than having to edit the webhooks plugin XML file. The above example could then be configured as per the following screenshot.

Screenshot from 2014-09-23 09:27:07
Download the 0.9.26.60 version (or higher) from sourceforge to try it out.

The build parameters configuration in Teamcity is explained on the TeamCity configuration properties wiki page. More info about using tcWebHooks custom parameters is also available.

Triggering a webhook for every TeamCity build (aka using the _Root project)

Posted on

I was recently asked in the comments whether it is possible to add a webhook to trigger for all builds in all projects.

The answer is: yes, but you have to add it to the configuration manually.

The _Root project

In recent versions of TeamCity, a hierarchy was introduced for projects. This means there is now a “Root” project, which is referred to internally by TeamCity as “_Root”. All projects are descendants of the Root project.

When I added descendant project support for the tcWebhooks plugin, I deliberately didn’t allow configuration of the Root project, because it would be too easy to inadvertently add a webhook to every build on TeamCity, even if there are builds that are not your part of a team’s projects.

However, that logic is applied in the UI, not at the webhook triggering level. Therefore, if you configure a webhook in the _Root project XML file on the TeamCity server, it will add a webhook for every build on every project.

Configuring

Edit ~/.BuildServer/config/projects/_Root/pluginData/plugin-settings.xml

Mine looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
 <report-tabs>
  <build-report-tab title="Code Coverage" startPage="coverage.zip!index.html"/>
  <build-report-tab title="JavaDoc" startPage="javadoc.zip!index.html" />
 </report-tabs>
 <webhooks enabled="true">
  <webhook url="http://<webhook_end_point>" enabled="true" format="nvpairs">
   <states>
    <state type="beforeBuildFinish" enabled="false" />
    <state type="buildFixed" enabled="false" />
    <state type="buildFailed" enabled="true" />
    <state type="buildSuccessful" enabled="true" />
    <state type="buildStarted" enabled="false" />
    <state type="buildFinished" enabled="true" />
    <state type="buildBroken" enabled="false" />
    <state type="responsibilityChanged" enabled="false" />
    <state type="buildInterrupted" enabled="false" />
   </states>
   <build-types enabled-for-all="true" enabled-for-subprojects="true" />
  </webhook>
 </webhooks>
</settings>

Integrating TeamCity with Slack.com using WebHooks

Posted on Updated on

Update: Since version 1.1 of tcWebHooks, this  is now much simpler. See A better way of integrating TeamCity with Slack.com using WebHooks


Here is a quick example of how to integrate slack.com with TeamCity using the tcWebHooks plugin.

Messages posted to Slack.com from TeamCity using the tcWebHooks plugin.
Messages posted to Slack.com from TeamCity using the tcWebHooks plugin.

The first three messages were posted using the first example XML configuration below. The last two are more elaborate and utilise the second XML snippet.

Step by step

  1. Create a new integration in Slack by going to the “Integrations” page.
  2. Scroll to near the bottom and click on the “Incoming WebHooks” button.
  3. Choose a channel to post into and click “Add incoming webhook”. A new integration should be created.
  4. Find the section entitled “Your Unique Webhook URL” copy the URL underneath it including the Token at the end.
  5. Switch to your teamcity web page and create a new WebHook.
  6. Paste in the webhook URL from step 4 into the webhook config.
  7. Choose Name Value Pairs payload format and select your trigger events. I suggest only selecting Successful and Failed. Otherwise you will fill your Slack channel with too many events. You may only want to choose when a build changes state to further reduce noise.
  8. After you’ve saved your webhook config, you need to add the Slack specific payload options by editing the WebHooks configuration file on the TeamCity server. In TeamCity 8 it will be located at: $HOME/.BuildServer/config/projects/<your_project_name>/pluginData/plugin-settings.xml
  9. Find your newly created WebHook and add the following block of XML before the </webhook> tag.
<parameters>
    <param name="payload" value="{&quot;text&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;}"/>
</parameters>

The above XML snippet shows a simple message. Below is a more sophisticated example showing the use of the attachment JSON field to show a coloured bar and heading text on the message.

<parameters>
   <param name="payload" value="{  &quot;text&quot;: &quot;All your build failures are belong to us&quot;, &quot;attachments&quot;: [ { &quot;fallback&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;text&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;color&quot;: &quot;danger&quot; } ] }"/>
</parameters>

A more complete example

This shows two full webhook XML configurations so you can see the parameter tag in context. If you look closely, you’ll see the first one only applies to build failures, and the second one only applies to build success messages. That is how you can display a different colour and message for different build results.

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <webhooks enabled="true">
     <webhook url="https://<your_slack_url>.slack.com/services/hooks/incoming-webhook?token=<your_token_here>" enabled="true" format="nvpairs">
      <states>
        <state type="buildSuccessful" enabled="false" />
        <state type="buildInterrupted" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="buildStarted" enabled="false" />
        <state type="buildFailed" enabled="true" />
        <state type="beforeBuildFinish" enabled="false" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildBroken" enabled="false" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
        <param name="payload" value="{  &quot;text&quot;: &quot;All your build failures are belong to us&quot;, &quot;attachments&quot;: [ { &quot;fallback&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;text&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;color&quot;: &quot;danger&quot; } ] }"/>
      </parameters>
    </webhook>
    <webhook url="https://<your_slack_url>.slack.com/services/hooks/incoming-webhook?token=<your_token_here>" enabled="true" format="nvpairs">
      <states>
        <state type="buildSuccessful" enabled="true" />
        <state type="buildInterrupted" enabled="false" />
        <state type="responsibilityChanged" enabled="false" />
        <state type="buildStarted" enabled="false" />
        <state type="buildFailed" enabled="false" />
        <state type="beforeBuildFinish" enabled="false" />
        <state type="buildFixed" enabled="false" />
        <state type="buildFinished" enabled="true" />
        <state type="buildBroken" enabled="false" />
      </states>
      <build-types enabled-for-all="true" enabled-for-subprojects="true" />
      <parameters>
        <param name="payload" value="{  &quot;text&quot;: &quot;All your build successes should to be celebrated&quot;, &quot;attachments&quot;: [ { &quot;fallback&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;text&quot;: &quot;${buildName} &lt;${buildStatusUrl}|build #${buildNumber}&gt; triggered by ${triggeredBy} has a status of ${buildResult}&quot;, &quot;color&quot;: &quot;good&quot; } ] }"/>
      </parameters>
    </webhook>
  </webhooks>
</settings>

There is a full list of the variables available.

new tcWebHooks release. Proper support for TeamCity nested projects

Posted on Updated on

The alpha release from last week is now available as the main release.

This release includes the following new features.

  1. Proper support for TeamCity’s nested project structure. You can now choose if a webhook is inherited by child projects.
  2. ExtraParameters can now be templated in a similar way to the htmlStatusMessage field. This has come in handy for FlowDock integration.

Nested Project support

Webhooks can be inherited by subprojects
Webhooks can be inherited by subprojects

Previous versions of the tcWebHooks plugin did not support nested projects at all. A webhook was configured for a project and only builds in that project would fire them. This version adds support for webhooks to be inherited from parent (and higher) projects.

To enable the old behaviour, I also added control of that feature to the UI as “sub-project builds”. By default webhooks are inherited, but that inheritance can be disabled by deselecting the “All Sub-Project Builds” check box.

Extra Parameter templates

Prior to the latest release, additional parameters were static text only. This release adds the ability to template them in the same manner as the buildStatusHtml message Custom Templates detailed in a previous post.

Here is an example of their use for integration with FlowDock.

 <webhook url="https://api.flowdock.com/v1/messages/chat/your-api-key" enabled="true" format="nvpairs">
   <states>
     <state type="buildFixed" enabled="false" />
     <state type="buildStarted" enabled="false" />
     <state type="buildBroken" enabled="false" />
     <state type="buildSuccessful" enabled="true" />
     <state type="buildFinished" enabled="true" />
     <state type="responsibilityChanged" enabled="false" />
     <state type="beforeBuildFinish" enabled="false" />
     <state type="buildFailed" enabled="true" />
     <state type="buildInterrupted" enabled="false" />
   </states>
   <build-types enabled-for-all="false" enabled-for-subprojects="true">
     <build-type id="bt3" />
   </build-types>
   <parameters>
     <param name="content" value="${message}" />
     <param name="external_user_name" value="teamcity" />
     <param name="tags" value="${projectExternalId},${buildExternalTypeId},${buildResult},teamcity" />
   </parameters>
 </webhook>

These parameters will appear as part of the POST payload and have the ${variables} resolved as per the details in the previous post.

Download and feedback

As usual, please download and post any issues you find on the bugs page.

Custom Templates and branches in tcWebHooks

Posted on Updated on

New release available

There is a new release of the TeamCity WebHooks plugin (tcWebHooks – 0.9.12.158).

  1. Adds branch details to the top level of the WebHook Payload Content object (fixes missing branch info in the Name/Value Pairs format).
  2. Fixes an incorrect link on the WebHooks tab of a build.

Download it from SourceForge

Feature Branches and tcWebHooks

I’ve spent the last few evenings working through various issues with the branch support I added a few releases ago. Because I don’t use a VCS that TeamCity supports for branch building, I have never had the opportunity to thoroughly test the feature.

With the help of Jeff, we worked through a number of issues with the Name/Value Pairs (nvpairs) format and my handling of the Branch interface that was added in TeamCity 7.0

The main problem was that the Branch object was being added to the WebHookPayloadContent, but as a child object. Therefore, structured payload formats like JSON and XML were serialising out the contents of the child object correctly, but the nvpairs format was not. It appears that most users are using the nvpairs format. Especially those POSTing to the HipChat webservice endpoint.

As a result of these changes, I have added the following items to the payload object and they are serialised out for all payload formats at the top level.

  • branchDisplayName – A friendly name like “master” or “feature01”.
  • branchName – A name used internally by TeamCity. In my testing, it shows as “<default>” for the “master” and “feature01” for the “feature01” branch.
  • branchIsDefault – A Boolean (note the uppercase B), that can be null, true or false depending on whether the build has feature branches enabled (null if not), is the master (true) or a branch (false).

These names are gleaned straight from the “Branch” interface in the TeamCity OpenAPI. I note with interest that the actual TeamCity implementation has different names (myBranchName, myDisplayName), so the JSON payload actually looks like this.

  "branchName": "<default>",
  "branchDisplayName": "master",
  "branchIsDefault": true,
  "branch": {
    "@class": "jetbrains.buildServer.serverSide.impl.BranchImpl",
    "myBranchName": "<default>",
    "myDisplayName": "master"
  },

The upshot is that the WebHookPayloadContent bean is what the custom templates use for building up the htmlBuildStatus message. That means that when configuring a custom message, you can only expect to resolve variables from this bean (using the getters). If value is not set for this instance variable, you will get “null” back. If the getter does not exist, you will get “UNDEFINED”.

A gotcha with the Branch object supplied by TeamCity

The Branch object and the new payload variables are completely dependant on TeamCity passing a useful Branch object to the sRunningBuild.
Please be aware that you will only get a sensible set of branch variables if all the following are true:

  1. You are running TeamCity version 7.1 or higher.
  2. The VCS that the build is built from has support for feature branches provided by TeamCity (currently in TC8 this is only GIT and Mecurial).
  3. You have configured feature branch support in your build so that TeamCity is aware that you have more than one branch that could potentially be used for versioning your build. For more information, please see: http://confluence.jetbrains.com/display/TCD7/Working+with+Feature+Branches

If any of these are not correct, you will get null values for the new branch variables supplied by tcWebhooks.

A list of the object variables in the WebHookPayloadContent bean

As of tcWebHooks verion 0.9.12.158, you should expect the following to be available to the buildStatusHtml template engine.

Variable Name Example Value
projectId GitTestBuilds
message Build Git Test Builds :: Git Test Build has finished. This is build number 22, has a status of “success” and was triggered by Net Wolf
buildStatus Tests passed: 2
buildId 76
buildStateDescription finished
extraParameters null
buildInternalTypeId bt9
branchName feature01
comment null
class class webhook.teamcity.payload.content.WebHookPayloadContent
projectExternalId GitTestBuilds
agentHostname localhost
text Git Test Builds :: Git Test Build has finished. Status: success
buildExternalTypeId GitTestBuilds_GitTestBuild
buildResultPrevious success
projectName Git Test Builds
buildTypeId GitTestBuilds_GitTestBuild
rootUrl http://myserver.company.com:8111
triggeredBy Net Wolf
buildResult success
buildRunners [Maven]
agentOs Linux, version 3.2.0-51-generic
agentName Default Agent
buildName Git Test Build
buildFullName Git Test Builds :: Git Test Build
branchDisplayName feature01
buildResultDelta unchanged
buildStatusUrl http://myserver.company.com:8111/viewLog.html?buildTypeId=GitTestBuilds_GitTestBuild&buildId=76
projectInternalId project5
notifyType buildFinished
buildNumber 22
branchIsDefault false