Skip to main content

How To Use Cloud Services With Webhooks And Factory Agents

Store Connected Factory Process Output In Online Databases

Electric Imp’s impCentral™ provides product customers with two webhooks: trigger points from which the Electric Imp impCloud™ can message customers’ servers when specific events during the Connected Factory Process and beyond take place. The two webhooks are Blessing and BlinkUp, and are triggered automatically. The first is activated when a Test Production Device has been blessed in the lab, or when a new Production Device has been blessed on the assembly line. The BlinkUp webhook is triggered when either of those two types of device are activated by a tester or an end-user, respectively.

To track other events, customers can make use of their factory firmware agent code, which has the capacity to post data to REST APIs hosted by customers’ servers. Factory agents work in the same way that the webhooks do, but can be customized to a far greater degree, especially in terms of the data, and the structure of that data, that is posted.

Because webhooks and factory agent posts operate using standard HTTPS web communications, it is possible for any customer to utilize third-party database services as endpoints for the webhooks and agents. This may be done to speed development, or for testing purposes — or simply because the customer lacks a suitable server and data logging system. This might be the case if you are contemplating a low-volume production run that doesn’t warrant the establishment of your own record-keeping system.

This short tutorial provides an example of how making use of third-party database services can be achieved. We have used the cloud service Google Firebase, but a number of other, similar services are also available, including Initial State, mLabs’ MongoDB and Keen IO. All such services provide access via HTTPS, and storage for the data passed this way. The collected data can usually be exported in a variety of forms to make analysis easier: for example, saving to a .csv file so the data can be loaded into a desktop spreadsheet.

Many of these companies offer a limited service free of charge, which can be used for low-production run products or for testing, but depending on your final data usage, you may need one of these services’ premium plans.

1. Set Up Firebase

Visit Firebase and create a Google account, or sign in with an existing account.

At the Firebase welcome screen, click Add Project under Recent Projects:

Enter a name for the project, eg. "Webhooks Example" and click CREATE PROJECT:

You will now be taken to the project dashboard; click Database under DEVELOP in the left-hand sidebar, then click Get Started in the Realtime Database panel:

Once the database is ready, you’ll see its URL. It will something like this, depending on the name you chose:

https://webhooks-example.firebaseio.com

You should select and copy this now — you will need it in step 2, below.

Finally, click the RULES tab in the blue bar at the top. This takes you to where you define access rules for your database. We’ll keep this simple for now; you can investigate access rules later if you choose Firebase for your webhook data storage. The database is initially made inaccessible, so just convert the write rule to "auth == null". This allows the webhook to post data to the database without authentication:

2. Configure Your Webhooks

Log into impCentral. Click on your account name in the nav bar to view your Products list. For the required Product, click Test Zone under MANAGE. You’ll now see a list of the Product’s Test Production Device Groups; if the Product has no Test Production Device Groups yet, click ‘Create New Device Group to set one up.

Note If you create a new Test Production Device Group, you will need to have promoted an application firmware deployment from a Development Device Group — you will be asked to select such a promoted deployment when you create the Test Production Device Group.

Now select Settings under the MANAGE column for the Test Production Device Group you’ll be using:

In the Webhooks area, paste the Firebase database URL you copied earlier to the URL field, and add JSON filenames for each of the webhooks. For example, for the blessing webhook, add blessing.json to the end of the URL. This is sufficient for Firebase’s data-entry REST API:

https://webhooks-example.firebaseio.com/blessing.json

The equivalent URL for the BlinkUp webhook is:

https://webhooks-example.firebaseio.com/blinkup.json

Leave the Content Type field set to application/json. Click Update Settings.

3. Add A Test Result Trigger To Your Factory Firmware

The BlinkUp and Blessing webhooks only fire when the events they are named for take place. To trigger messages at a time of your choosing, you can make use of your factory firmware’s agent. This provides a means to connect your code with your logging service of choice.

Locate and view the Test Factory Device Group in which you are developing your Product’s factory firmware: like the Test Production Device Group, it is located in the Product’s Test Zone. Enter the following Squirrel code into the group’s code editor. On the device side, we use the imp API method agent.send() with the message name "testresult". For the message payload, we provide a table containing the data we wish to log:

local impID = hardware.getdeviceid();
local impType = imp.info().type;
local netData = imp.net.info();
local network = netData.interface[("active" in netData ? netData.active : 0)];
local message = "Message from an imp";
agent.send("testresult", {"device_id": impID, 
                          "mac": network.mac, 
                          "type": impType,
                          "msg" : message});

The above lines will relay the four-slot table passed as agent.send()’s second parameter to the factory firmware agent. The message can be received by the following agent code, which you’ll need to add to your factory firmware:

device.on("testresult", function(data) {
  local logurl = "https://webhooks-example.firebaseio.com/testresult.json";
  local headers = {"Content-Type": "application/json"};
  local body = http.jsonencode(data);
  http.post(logurl, headers, body).sendasync(function (response) {
    if (response.statuscode >= 300) {
      server.error(format("failed posting testresults for device %s with response %d:
        %s", data.device_id, response.statuscode, response.body));
    } else {
      server.log(format("Results posted for device %s", data.device_id));
    }
  });
});

Your factory firmware will run on both your BlinkUp fixtures and your Devices Under Test (DUTs), so you will need to make sure that the device code listed above is placed in the correct code path. In this case, that’s the DUT code path. If you wish to log from your BlinkUp fixtures too, you will need to add similar code into the fixture code path in both the device and the agent listings.

Click Build and Force Restart to deploy the code to the group and run it on the group’s BlinkUp fixtures.

4. Set The Test Factory Device Group’s Target

If you have not done so already, set the Test Factory Device Group’s target. Navigate back to the Product’s list of Test Factory Device Groups and click Settings under MANAGE for the Test Factory Device Group you worked on in the previous step.

In the Test Factory Device Group Settings panel that now appears, make sure that the Test Production Device Group you worked on in Step 2 is selected, and click Update.

5. Run Your Factory Firmware

You can now use your BlinkUp fixture to configure a DUT. The DUT will connect to your network, and download and run the factory firmware. The outcome will be that it becomes blessed: at which point, the Blessing webhook will be triggered.

When the DUT has been blessed (its BlinkUp LED will go green and stay lit), you can power-cycle it and use your BlinkUp SDK-based mobile app to perform end-user BlinkUp on the device, which is now a Test Production Device. This will cause the device to enroll into the impCloud. In turn, this causes the BlinkUp webhook to be triggered.

6. Review The Collected Data In Firebase

Now return to the Firebase console and click Webhooks Example under Recent Projects if you are not still viewing the database dashboard. In the left-hand sidebar of the database dashboard, click DEVELOP and then Database. Any data received from the factory agent will appear here:

The Blessing and BlinkUp webhook posts will appear here too, added to the data structure Firebase presents as branches alongside testresult:

If you click on the three dots (), you call up a menu which allows you to export the received data as a JSON file, which you can use for offline analysis or backing up your data:

Conclusion

As this tutorial shows, services like Firebase provide a very simple, straightforward means for collating the results of the factory process. How you make use of this collated information, as presented by Firebase or from a downloaded file, is up to you, of course.

impCentral’s Test Zone exactly matches its Production Zone, so setting up webhooks for Production Devices works in exactly the same way as described above. Having setup and observed the webhooks working in the Test Zone’s Test Production Device Group, you know the same webhook and target will work just the same with a full Production Device Group.