SmartThings Octoblu Integration

by Tobias Kreidl, CTP, CUGC Steering Committee

Introduction

As the market continues to expand to support interconnectivity of everything from vehicles to appliances, the home area has grown as one of the more interesting areas because of its plethora of electronic devices, concerns about security, and the desire to simplify and automate day-to-day activities. This has been made possible in recent years via smarter devices, which are programmable or in some cases incorporate sensors (such as light-sensitive alarm clocks). However, strict time-based schedules are not always what everyone wants to follow, so the desire for both more flexibility as well as automation have led to even smarter devices that are voice, motion or hand controlled or in some cases, will integrate with other smart devices. Hence, the market has become ripe for intelligent devices, especially those whose information can be combined well with other such devices. Supporting this are a number of “hubs” that allow the integration of smart devices and control over them via computers or smartphones. The Internet of Things (IoT) has become a familiar term and in its evolution, it has also become apparent that the devices and controls associated with IoT could be used not only for entertainment and convenience purposes, such as triggering the coffee maker to operate, but also functioning as home security devices, controlling watering the lawn and as temperature regulation mechanisms. And with further integration into vehicles, one’s departure can signal doors to lock, lights to be turned on or off and motion sensors and cameras to spring into action.

With all this, one would think there are a lot of controls already built in that allow a multitude of tasks to be undertaken. As much as this is true, there are still things that the human imagination can come up with that no single set of devices can readily do on its own without more specific directions. In some cases, it may actually not be desirable to base decisions on artificial interlligence, but rather have well-defined consequences dictated by what and what not functions to perform. And because we often tend to procure different devices with different capabilities from a number of vendors, seamless integration is not always so easy.

One option lies in obtaining equipment with a sufficient degree of interoperability meshed with an intelligent controlling layer that can combine inputs and create complex decision trees together with multiple potential single or series of outcomes. This can even be by-and-large vendor agnostic as long as certain common protocols are supported. The blending of IoT objects with smart IoT control mechanisms hence becomes a logical avenue to pursue.

What lies ahead is a discussion of one such platform combined with one of the others, in this case, Samsung SmartThings with Citrix Octoblu.

My choice of SmartThings as a platform was based on reasonable cost, its support of Ethernet and WiFi (and future-ready to support Bluetooth) as well as both Z-Wave and Zigbee protocols, plus hundreds of devices already available that are known to work in addition to its own. A large list of such devices from other manufactures is at: https://www.smartthings.com/compatible-products. The choice of Octoblu (https://octoblu.com/) makes sense because for one, many of us are already deeply involved with Citrix products, it has a very user-friendly interface, and I was also interested to see how much effort it would take to get Samsung and Citrix to be willing to make the integration happen. It turns out that very few arms really needed twisting and both parties ended up making it all work and in a much shorter time than I expected! That being the case, the obligation was there for a follow-through report, hence this initial foray into the integration of these products.

At this point, let me make clear that experimenting with this sort of a setup involving devices that are used around the home is of course entertaining, makes for great demos for friends and family, and is overall something one can enjoy in even some very practical settings. But make no mistake about the fact that this sort of technology is working its way into the workplace where it has already found integration into a number of products (Citrix NetScaler, for one) and as the communication involving software packages and hardware continues to build, the realization of setups such as smart conference rooms and classrooms, medical facilities or data centers that have the ability to self-adjust and make appropriate decisions in terms of load balancing, dealing with issues such as overheated components, or even disaster recovery scenarios all becomes apparent. The initial steps with more simple building blocks only serve as a means to better explore even more complex options, and therein lies the real interest from a corporate view. If you think disaster recovery isn’t important, just take a look at the Delta Airlines datacenter outage of August 2016 as an example (http://up2v.nl/2016/08/16/a-reconstruction-of-the-delta-airlines-datacenter-outage/) which resulted in many tens of millions of dollars of losses. This is not to say that major malfunctions can be totally avoided, but one could envision means to automatically distribute and partition resources to prevent an “all eggs in one basket” sort of vulnerability.

The SmartThings Hub

Order it, download the smartphone app and install on your phone (Android or iPhone). The setup instructions will then have you sign up for an account and create it at https://www.smartthings.com/. You will be instructed to type in the six-character code supplied with the hub when prompted for it. Next, connect the hub to an Internet-aware network switch with the provided Ethernet cable and power on the hub. It will search for any available updates it may need and download those on its own over the Internet.  When complete, the hub’s LED will glow a solid green color and you should see an “OK” result on the phone app. Note that you can set up and support multiple hubs, though not at the exact same location, and control them all independently of each other. The last step in the setup is naming the device and setting up the physical location. You have the ability to also define the extents of the so-called “geofence” that surrounds the location of where the hub is located and can be used to trigger events, such as when you pass into or out of that zone. The hub location can be readily modified, should it be relocated at some future time.

To configure the hub, navigate to https://graph.api.smartthings.com/ide/apps and log on with your account information. You will need to choose the “My SmartApps” tab and click then on the “+ New SmartApp” button. Next, go to the Octoblu download site at https://github.com/octoblu/octoblu-smartapp and carefully select and copy all the SmartApp code from the “app.groovy” link. Carefully paste that into the field you will see displayed under the “New Smart App”-> “From Code” tab and hit the “Create” button at the bottom. Be very careful not to lose any of the code or add any extra characters or lines. Make sure you complete the “Publish” step. You should now see an Octoblu entry appear under your “My SmartApps” tab. Note that under the “OAuth” column, it will currently be blank:

You will need to enable OAuth in order to communicate with the SmartThings app on your phone, so click on the “Edit Properties” icon (the one resembling a pen and pad on the right of the “View Details” icon under the first column) and click on the “OAuth” option; it will show an “Enable OAuth on Smart App button, if not enabled:

Click on “Enable OAuth in Smart App” and it should self-generate contents. Afterwards, be sure to hit the “Update” button at the bottom! The Octoblu SmartApp should now show “true” under the OAuth heading. You can re-generate a new client ID if ever needed or desired and save such changes.

Add a Sensor

The next step is to add a sensor device and make the hub aware of it. Note that some devices also require specific handlers to be able to be properly integrated. In this case, we’ll use the Zooz 4-in-1 ZSE40 sensor as an example. We will configure it since it benefits for a custom device handler and can then incorporate both devices as SmartApps and then integrate them into Octoblu.

First, log onto the SmartThings manager at https://graph.api.smartthings.com/login/auth and navigate to the “My Device Handlers” tab. Click on the “Create New Device Handler” option in the upper right area and select the “From code” option. Navigate in this case to the best source I could find for this device, namely https://raw.githubusercontent.com/robertvandervoort/SmartThings/master/zooZ-4-in-1-Sensor-ZSE40/device_type-zooZ-4-in-1-Sensor-ZSE40_v1.2_motion_primary and carefully select the code block and paste it into the code window. Scroll to the bottom of the browser window and click first on the “Save” button, followed immediately by clicking on the “Publish > for me” option. At this point, you should be able to go to the “Device Handlers” tab and see your installed handler. Note that under most circumstances, you should not have to enable OAuth on your device handlers.

If it had been used before and this is a replacement driver/installation, use the “exclude” option on your smartphone within the SmartThings hub configuration before you perform an “Add thing” > “+ Connect New Device” procedure. The device should be held a couple of feet at most from the hub and a thin, stiff object like the end of a paper clip should be used to push twice, fairly rapidly, into the activation hole to reset the device and commence the discovery process. There should be a couple blinks on the hub, after which the device will need to sit for at least a couple of hours so it can configure itself completely. That part took a lot more patience than first expected and made for a long wait to be reassured that everything finally was working properly. Letting it ‘do its thing’ overnight ended up being a wise decision.

Tie in the SmartThings Devices to Octoblu

At this point, we need to go back to the smart phone to finish setting up the connection between the SmartThings application and Octoblu. Make sure your SmartThings Mobile app that you got from the mobile store is recent enough:

Launch your SmartThings app on the phone and click on the “Marketplace” tab down at the bottom right.

After hitting the “Marketplace” button at bottom right, at top “SmartApps” should appear to the right of “Things”:

Go to the “My Apps” section:

Hit “next” and see if the Octoblu app shows up. If so, you’ll need to authorize, which takes a very long time (note that there will be a very thin progress bar at the bottom of the blue field that shows up during this process):

When complete, it will ask for “Done” to be pressed. You will then be requested to authorize in turn with Octoblu:

Proceed and agree to allow access by clicking on the “Authorize” button:

You will be requested to log onto your Octoblu account to complete the process:

When successful, you will be asked what devices to subscribe to:

These can always be added later, as desired. When finished, hit the “Done” option to complete the setup. Note that each item will show up with a unique UUID:

Now, back on your Octoblu account on the website, you should be able to refresh your “Things” list and see the added devices (in the case below, the hub and the Zooz 4-in-1 sensor):

Success! At this point you can start building flows that incorporate your SmartThings hub and/or any of your attached devices that you added.

Note that back on the SmartThings account page, you now should see your added devices under the “My Devices” tab:

In this case, the smartphone itself was also added as a device.

Creating a Basic Octoblu Flow

With this setup established, we can now turn our attention to creating and testing a simple Octoblu flow that makes use of this new integration. In this example, an email alert will be sent if the temperature falls outside of a certain range and also if the humidity exceeds a specified level. If you do not already have an Octoblu account, go to the https://octoblu.com/ site and create one. Navigate to the flow page via the “Flows” option and create a new flow by clicking on the big “+” option.

In the example below, the Zooz ZSE40 feeds two inequality tools, one for if the temperature falls at or below a prespecified value (e.g., 40 F) and one if it falls at or above a upper maximum limit (e.g., 85 F), The device should definitely be preset to use either the Fahrenheit or Celsius scale! Another option would be to use the range tool, with a different logic, namely to not generate an alert if the conditions were satisfied. When either inequality (technically, a non-strict inequality) is met, the next step is to pull the location from the hub “thing” and inject both it and the temperature into the compose tool, the keys being payload.temperature and payload.hubs[0].name which should be matched to the corresponding values. Note that the first hub device uses the index [0]. The ZSE40 can be configured to use various incremental steps that determine when a new value is transmitted for its various parameters; consult the manual for details. You don’t want to use too fine increments or the devices will be overly utilized and wear down the batteries quickly, plus in most cases, you don’t need to monitor that exact of a level of change, anyway.

The humidity checker is an even simpler example, with an alert generated if the humidity value seen in the diagram below exceeds 85.0 percent at which point it fulfills the compose tool requirement and generates an email message:

Adding a manual trigger and debug tools to your Octoblu flow is recommended, especially while setting up and testing. Note also that these independent events with different sensors can all be contained with a single flow; they do not have to be created separately. This is particularly useful if you wish to enable or disable a number of related actions at the same time.

I would also like to note that I have seen issues with combining triggered events with additional information injected from the hub, so you may need to start with that hub information not initially incorporated into the compose tool and add it later once the basic alert works. The integration of SmartThings into Octoblu has only taken place very recently, plus flow behavior may vary, depending on how it is integrated. It’s still a learning process. There are forums for both SmartThings and Octoblu that may be able to provide useful help and guidance.

There you have it: a SmartThings hub and device integrated into the Octoblu environment! From here, you can explore the extents of one or more sensors and the plethora of options of what to do with these data and how to let Octoblu help make smart decisions based on the combination of the information provided and your imagination.

I hope this “how to” guide and example of the setup and integration of the SmartThings environment into Octoblu has been of interest and has provided some incentive for others to further investigate this combination. The surface has really only been scratched.

Bonus Zooz 4-in-1 Handler Modification

As an extra, I’m throwing in a tip about how to modify the behavior of the Zooz 4-in-1 detector. By default, when motion is detected as well as various other settings (such as the current temperature), it will flash or display certain colors to indicate feedback. However, what if you want to use the detector stealthily so that it doesn’t give itself away when it reacts by lighting up to any sort of stimulus?

If you examine the handler that you installed in one of the steps above, a review of the code reveals a parameter called “LEDbehavior” and it’s set to be “Quick Blink on Temp/PIR” as the default (which is also seen in the device configuration listing). In other words, the device will emit light in some form depending on the temperature as well as if it senses motion with its PIR (Passive InfraRed) sensor. In the code, I see:

input “LEDbehavior”, “enum”,

            title: “LED Behavior”,

            options: [“LED Off”, “Breathing”, “Quick Blink on Temp/PIR”],

which simply means you can pick one of these with the SmartThings device editor. If all should be off, then “LED Off” is the choice you want.

Go to https://graph-na02-useast1.api.smartthings.com/device/list (or to the corresponding link at your particular region) and click on the “My Devices” tab and click on the name of the device under “Display Name” (in this particular case, “Zooz 4-in-1 sensor – RV 1.2”):

Edit the configuration as shown in the attachment to be “LED Off” (and be sure to get the capitalization correct):

Save the modified version and review the update, which should take effect instantly:

The Zooz 4-in-1 should now not show any LED activity whatsoever. Note that you might want to turn this back on, should you need to do any debugging or re-purposing of the device where LED feedback is desired.

Acknowledgements

My gratitude is extended to Erik Wilson, Andrew Steinheiser, Jody Albritton and Chris Matthieu for their efforts and contributions to bringing the whole SmartThings-Octoblu integration and functionality to fruition and to Robert Vandervoort for his development and making available of the Zooz ZSE40 handler with enhanced functionality.

References

Andrew Steinheiser’s basic SmartThings integration into Octoblu: https://www.hackster.io/andrewstein/home-security-with-smartthings-via-octoblu-764873

Robert Vandervoort’s Enhanced Zooz 4-in-1 ZSE40 handler code: https://raw.githubusercontent.com/robertvandervoort/SmartThings/master/zooZ-4-in-1-Sensor-ZSE40/device_type-zooZ-4-in-1-Sensor-ZSE40_v1.2_motion_primary

Leave a Reply