david_a_mitchell355242

IoT Integration - Geofences, NEST Thermostats and Boomi

Blog Post created by david_a_mitchell355242 Employee on Jun 30, 2018

In this post I wanted to share my experience and a "How To" for building a Boomi process and triggering it whenever a user enters or exits a geographical area. This was the first Boomi use case I thought of when joining team. From a Boomi point of view it isn't complex at all. Nevertheless I've shared relatively step-by-step instructions.

 

 

Background

Not so long ago I decided that I wanted more control of my heating bills. I invested in a wireless thermostat. It was great, looked cool on the wall and had some interesting features. I was excited when a new feature was introduced which allowed me to control the thermostats state purely based upon my mobile phones location. I tried it and I 'think' it worked. I wasn't totally sure what it's criteria was for adjusting the heating, turning it up or down and on and off. What are the thresholds for this? To get full control and learn about geofencing I decided that I'd like to see what's involved in building a similar system. Why not build it with Boomi !

 

Requirements

There are a few elements required for this process:

 

  • Location Platform such as Radar.io, HERE.com etc. – I’ve chosen Radar.io for this example as it offers a free plan to get started
  • NEST thermostat developer account – you can register here
  • Mobile Phone either Android or IOS
  • Boomi Connectors required
    • Boomi Web Services Server connector – available with Professional Plus, Enterprise, and Enterprise Plus Editions
    • HTTP Client Connector

 

Creating your Callback URI

We'll need to build our Callback URI which will allow us to authenticate our HTTP Client connector with our NEST OAuth Client. This is unique to each user account in Atomsphere. Login to Atomsphere and navigate to your username at the top towards the right and select "Setup" from the drop down menu. Take note of your "Account ID" from the "Account Information" section.

 

Append this to the the callback URl format as follows:   https://platform.boomi.com/account/<ACCOUNT_ID>/oauth2/callback

 

 

So in this case it would be:

https://platform.boomi.com/account/boomi_xxxxxxxxx_xxxxxx/oauth2/callback

 

Building a NEST

We'll need two things to configure the NEST side of the equation. An OAuth Client to authenticate our Boomi process with and a NEST thermostat. You can either use a live NEST that you own or the simulator that they provide.

 

Creating an OAuth Client

Now Go to https://console.developers.nest.com and register/sign in to gain access. Once in we'll create a new OAuth Client which is effectively allowing us to authenticate our Boomi process with the NEST environment and provide permission to change the temperature. Then we'll download the NEST Simulator Application and use that in place of a real NEST. It's exactly the same API but allows you to test all works well and also use this example if you don't actually have a NEST.

 

Once logged in hit "Create New OAuth Client" and fill in all the mandatory fields. Paste in the Boomi Callback URI we created earlier into the Default OAuth Redirect URI field. Then go to permissions and select Thermostat. I chose to get read and write permissions as I'll need read permissions later when I build the NEST JSON profile. You'll need to type in a description into the permissions dialog which will be displayed to users upon authenticating.

 

Setup Nest OAuth Client

 

Once created take note of the OAuth section in which you'll find the:

 

  • Client ID
  • Client Secret
  • Authorization URL

 

We'll use these when we're configuring our HTTP Client connector.

 

Setting up the NEST Home Simulator Application

In reality you'd want to set this up to work with a real thermostat. If you have one that's fine. If not then the NEST Home Simulator will suffice. It's a Chrome plugin available here. Once it's download you should login with the same credentials as those for your NEST developer account. Then create a new thermostat and you're all set.

If you have a NEST thermostat then by all means use that instead of the simulator. Keep in mind that the NEST API has certain rules around the state that your thermostat is in when away from home i.e. ECO mode. I encourage you to have a read at the Documentation for the API here.

  

 

Building it out in Boomi

Now we have a virtual NEST thermostat setup and the OAuth Client created we can create a process in Boomi which will interact with it. The Boomi process will only have three shapes. A Web Services Service Connector at the start to listen for data coming from Radar.io, a decision shape to route the process and then an HTTP Client connector for changing the temperature on the NEST. First of all however we'll create a test process to perform a GET request so we can built our a JSON profile.

 

Configuring the HTTP Client connector

Boomi doesn't have a predefined Application Connector for NEST at present so we will build one out of the HTTP Client Connector.

 

Start a new process and drag an HTTP Client connector onto the canvas. Create a new connection and insert the Client ID, Client Secret and Authorization URL that we recorded whilst creating our NEST OAuth Client previously. Input the Authorization URL from the NEST OAuth Client into the Authorization Token URL and the client secret and ID into the corresponding fields. Use the below table if you need to.

 

HTTP Client Connector Field

URL

https://developer-api.nest.com 
Authentication TypeOAuth 2.0
Client ID<Client ID from the NEST OAuth Client App>
Client Secret<Client Secret from the NEST OAuth Client App>
Authorization Token URL<Authorization URL from the NEST OAuth Client App>
Access Token URLhttps://api.home.nest.com/oauth2/access_token 

 

We don't need to set any fields in the SSL Options or Advanced Tabs. Hit "Generate" and we will be taken to an authorization screen for our NEST OAuth Client app and allow our HTTP Client connector to generate a token for future use. You should see a screen similar to the below. Hit allow and we'll be redirected to a Boomi screen stating "Authorization Code Received". Close this window and you'll see on your Atomsphere screen that the "Access Token generation successful" message is displayed.

 

Now create a new Operation. No configuration is required here other than ticking the "Follow Redirects" check box. Once saved we can now make calls to our NEST OAuth Client app.

 

Blog NEST ConnectorOAuth 2.0 Authentication

 

Importing the NEST JSON Profile

Lets test this simple process and get back an outline of the content that the NEST API provides. Kick off a Test Mode run and select either a local atom or the atom cloud. You should receive JSON content back relating to your NEST Account. Viewing the Connection Data will display the JSON response. Something similar to the below. I've removed some of the structure. You'll receive more data than this in reality.

 

Note in the layout of this JSON that the id of my NEST Thermostat is "3hL-EH_gBl3APR7XB5JR9-qoPde-hzuH".

    
{
  "devices": {
    "thermostats": {
      "3hL-EH_gBl3APR7XB5JR9-qoPde-hzuH": {
        "humidity": 50,
        "locale": "en-GB",
        "temperature_scale": "C",
        "is_using_emergency_heat": false,
        "has_fan": true,
        "software_version": "5.6.1",
        "has_leaf": true,
        "where_id": "FydB4fkOWmyhzdeEDpGYOg7udugr_YTnOf3fhm3sJoGHw-q_8AY96A",
        "device_id": "3hL-EH_gBl3APR7XB5JR9-qoPde-hzuH",
        "name": "Guest House (2D5E)",
        "can_heat": true,
        "can_cool": true,
        "target_temperature_c": 13.5,
        "target_temperature_f": 56,
        "target_temperature_high_c": 26,
        "target_temperature_high_f": 79,
        "target_temperature_low_c": 19,
        "target_temperature_low_f": 66,
        "ambient_temperature_c": 5.5,
        "ambient_temperature_f": 42,
        "away_temperature_high_c": 24,
        "away_temperature_high_f": 76,
        "away_temperature_low_c": 12.5,
        "away_temperature_low_f": 55,
        "eco_temperature_high_c": 24,
        "eco_temperature_high_f": 76,
        "eco_temperature_low_c": 12.5,
        "eco_temperature_low_f": 55,
        "is_locked": false,
        "locked_temp_min_c": 20,
        "locked_temp_min_f": 68,
        "locked_temp_max_c": 22,
        "locked_temp_max_f": 72,
        "sunlight_correction_active": false,
        "sunlight_correction_enabled": true,
        "structure_id": "WoPouIo-IsQTuGgTd1HfbVtJ1y7XErHcj2hebmTEMyLPtovAH0PTpQ",
        "fan_timer_active": false,
        "fan_timer_timeout": "1970-01-01T00:00:00.000Z",
        "fan_timer_duration": 15,
        "previous_hvac_mode": "",
        "hvac_mode": "heat",
        "time_to_target": "~0",
        "time_to_target_training": "ready",
        "where_name": "Guest House",
        "label": "2D5E",
        "name_long": "Guest House Thermostat (2D5E)",
        "is_online": true,
        "hvac_state": "off"
      }
    }
  },
  "structures": {
  "metadata": {
}

The above is just an example. Copy the actual output from your test mode run and save that to a text file.

    

Now we can create a new profile in Atomsphere and select the JSON Profile Format. Select Import and browse to the file we just created and upload it. This will build out our JSON profile which will be specific to that of our virtual NEST. We're now ready to interact with the NEST API.

 

NEST JSON Profile

 

Importing the Radar.io Webhook JSON Profile

We'll need to create the profile of the data that will be received from Radar.io. We could configure Radar.io and do some test runs to receive this data however to speed things up I've pasted their test run output below. Follow a similar process as above and build out a JSON profile for the Radar.io Webhook.

{
  "event": {
    "_id": "56db1f4613012711002229f6",
    "createdAt": "2018-04-07T12:49:21.890Z",
    "live": false,
    "type": "user.entered_geofence",
    "user": {
      "_id": "56db1f4613012711002229f4",
      "userId": "1",
      "description": "Jerry Seinfeld",
      "metadata": {
        "session": "123"
      }
    },
    "geofence": {
      "_id": "56db1f4613012711002229f5",
      "tag": "venue",
      "externalId": "2",
      "description": "Monk's Café",
      "metadata": {
        "category": "restaurant"
      }
    },
    "location": {
      "type": "Point",
      "coordinates": [
        -73.977797,
        40.783826
      ]
    },
    "locationAccuracy": 5,
    "confidence": 3
  }
}

This is also just an example but it's fine for the Webhook profile.

    

 

Building the main process

Let's start a new process and configure the start shape as a "Web Services Server" then create a new operation.  These settings are important to make sure the process is executed correctly. The "Operation Type" and "Object" fields will be appended to the URL of our Atom where this process will be deployed to. The "Expected Input Type" should be "Single Data". We aren't sending back any data because there won't be anyone listening to receive it so we can leave the "Response Output type" as None.

 

Geofence Operation

 

Now drag in a decision shape and choose the Radar.io Webhook profile we created earlier for the First Value field. Next choose the element that we want to make a decision based upon. Drill down through the Element field to the Event object and select "Type".

 

This object will either contain "user.entered_geofence" or "user.exited_geofence". I configured the rest of the shape so that the comparison was "Equal To" with the second value configured as a static value of "user.entered_geofence". Therefore whenever a user enters the geofence the decision rule is set to true and proceeds down the True path. Otherwise it will proceed down the false path.

 

Now let's add in an HTTP Connector to the True path. Leave the action as a Get. Choose our previously configured Virtual NEST Connector for the connection and then create a new Operation. Configure it as in the below image using the NEST JSON profile we created in the Configuring the HTTP Connector step.

 

 

Make sure to choose PUT for the HTTP Method here and also check the Follow Redirects check box. This is because the NEST API ingests data using the PUT method only and upon making a request to the API it will issue a 307 redirect which the process will need to follow.

    

Now select parameters and add a new parameter. Selecting the Input will show the objects for our NEST JSON profile. Drill down through it to your NEST simulators device and select a target temperature object. I chose "target_temperature_c" object and gave it a static value of 25. Probably a little too hot in reality...

 

Make a copy of this Connector to the False path and change the temperature parameter to a lower value such as 10.

 

Nest Temperature parameter

If all has gone well you should have a process that looks something like this. Remember it's always best practice to put a stop at the end of each route.

 

Geofence NEST Control Process

 

Deploying to a local Atom

We would typically want authentication configured on our Atom Shared Web Server however that won't be possible for this example. It isn't possible to configure Radar.io to pass  our Atom credentials along with the Webhook data. As a result we need to configure it as a basic API Type with the Authentication Type set to "None". This also means that this process must live on a locally deployed Atom because the Atom cloud requires user Authentication when using the Shared Web Server.

*IMPORTANT* This isn't secure so keep this in mind. We could use the Security Token generated by the Radar.io Webhook to make this more robust however I haven't implemented it here. Perhaps someone could offer up an example of this in the comments?

    

Navigate to the Manage tab in Atomsphere and select Atom Management. Choose the atom you are going to deploy this process to and then select Shared Web Server from the Settings and Configuration section. Configure your atom similar to the below. The Base URL will need to relate to your specific Atoms web addressable URL and listening port. Don't override unless necessary. If you need in depth help around this then have a look in the community. There's a lot of help there.

 

Shared Web Server

Take note of your Base URL here which we'll append with our Simple URL path from our Web Services Server Operation later.

    

Finally navigate to the Deploy tab and Deploy the process to your Atom.

 

Setting up Radar.io

Registering for a Radar.io account is very straightforward and the free edition provides enough functionality for us to achieve this integration.

Go to https://radar.io/signup and fill in the details. Confirm your email to validate your account and login. Once logged in we need to create a Geofence to monitor and a Webhook to send data to when our user crosses the threshold of our geofence. We also need a mobile app to create a user and update Radar.io with their location.  An SDK is available for developing your own mobile app. For this example I'm going to use the test app they provide.

 

Creating a Geofence

Login into https://radar.io/geofences/new and search for your location. Addresses and place names are supported. Once you've found your desired location it's just a case of setting the threshold of our geofence. We would likely want to activate the heating system when we are close but not too close.

I've used a 1km radius which fits well with me walking around the city. Now hit Create and your Geofence is set to go. I've used our office as an example.

 

Create new Geofence

 

 

Setting up a Webhook

The Webhook is configured in the Integrations section of the Radar.io dashboard. Here we will input the URL of our Web Services Server.

Choose the same environment in which your Geofence exists (Test or Live) and select "Single Event". In the URL we want to input our Web Services Server URL from the Boomi process we created earlier and append it with the Simple URL path from the Web Services Service operation.

 

In my example the completed URL would be as below. Base URL from your Web Services Server and Simple URL from your Web Services Service Operation.

http://my_boomi_atom.com:9090/ws/simple/execute/executeTemp

 

Radar.io Integration

At this stage we can hit Test and Radar.io will send a sample JSON message to our process. You should see the temperature on your NEST simulator app change. If it doesn't then there's a problem. It's a good idea to troubleshoot at this stage to make sure that the Atom and process are configured correctly. We can also use Postman to test as I have in the video below.

 

 

Installing and configuring the Radar.io test mobile app

As mentioned at the beginning there is an SDK available for developing your own app however the test app is really simple and will work just fine.

It is available for either IOS or Android. Once installed we just need to install the relevant publishable key.

These keys are available at https://radar.io/organization 

 

My Geofence and Webhook resides in the Test environment of Radar.io so I used the Test publishable key. It's worthwhile copying this to an email and sending it to yourself. It's lengthy. Copy it into the app on your mobile device and enable Tracking. If you look in https://radar.io/users you'll now appear with a user ID and device ID. You're being tracked! Now whenever this device crosses the threshold of your Geofence it will fire an event at our Boomi process which will then interact with our NEST thermostat and change the temperature.

 

Final thoughts

This is a basic use case using some fairly powerful Boomi shapes and connectors. There is much more we could do here to make this more interesting such as adding additional actions and connecting to multiple NEST devices at the same time. We could trigger lighting, music, all sorts of IoT devices that exist in the home, office or workplace.

 

In a more commercial use case we could use a similar method for monitoring deliveries, trucking, ships, you name it. Boomi processes can be triggered like this in many different ways to provide services and solutions that can streamline all kinds of scenarios out there.

 

Looking at this simple example really opened up my mind to the huge number of use cases there are when it comes to IoT and Geofences. The variety of ways in which we could utilize the data in these devices and how we could take action based upon their location.

 

I hope you've found this of interest and would love to hear your thoughts, suggestions and the use cases you have found which could be solved using Geofences and IoT devices and of course Boomi.

Outcomes