Creating an Add-on for the Project Things Gateway

The Project Things Gateway exists as a platform to bring all of your IoT devices together under a unified umbrella, using a standardized HTTP-based API. Currently, the platform only has support for a limited number of devices, and we need your help expanding our reach! It is fairly straightforward to add support for new devices, and we will walk you through how to do so. The best part: you can use whatever programming language you’d like!

High-Level Concepts

Add-on

An Add-on is a collection of code that the Gateway runs to gain a new features, usually a new adapter. This is loosely modeled after the add-on system in Firefox where each add-on adds to the functionality of your Gateway in new and exciting ways.

Adapter

An Adapter is an object that manages communication with a device or set of devices. This could be very granular, such as one adapter object communicating with one GPIO pin, or it could be much more broad, such as one adapter communicating with any number of devices over WiFi. You decide!

Device

A Device is just that, a hardware device, such as a smart plug, light bulb, or temperature sensor.

Property

A Property is an individual property of a device, such as its on/off state, its energy usage, or its color.

Supported Languages

Add-ons have been written in Node.js, Python, and Rust so far, and official JavaScript and Python bindings are available on the gateway platform. If you want to skip ahead, you can check out the list of examples now. However, you are free to develop an add-on in whatever language you choose, provided the following:

  • Your add-on is properly packaged.
  • Your add-on package bundles all required dependencies that do not already exist on the gateway platform.
  • If your package contains any compiled binaries, they must be compiled for the armv6l architecture. All Raspberry Pi families are compatible with this architecture. The easiest way to do this would be to build your package on a Raspberry Pi 1/2/Zero.

Implementation: The Nitty Gritty

Evaluate Your Target Device

First, you need to think about the device(s) you’re trying to target.

  • Will your add-on be communicating with one or many devices?
  • How will the add-on communicate with the device(s)? Is a separate hardware dongle required?
    • For example, the Zigbee and Z-Wave adapters require a separate USB dongle to communicate with devices.
  • What properties do these devices have?
  • Is there an existing Thing type that you can advertise?
  • Are there existing libraries you can use to talk to your device?
    • You’d be surprised by how many NPM modules, Python modules, C/C++ libraries, etc. exist for communicating with IoT devices.

The key here is to gain a strong understanding of the devices you’re trying to support.

Start from an Example

The easiest way to start development is to start with one of the existing add-ons (listed further down). You can download, copy and paste, or git clone one of them into:

/home/pi/.mozilla-iot/addons/

Alternatively, you can do your development on a different machine. Just make sure you test on the Raspberry Pi.

After doing so, you should edit the package.json file as appropriate. In particular, the name field needs to match the name of the directory you just created.

Next, begin to edit the code. The key parts of the add-on lifecycle are device creation and property updates. Device creation typically happens as part of a discovery process, whether that’s through SSDP, probing serial devices, or something else. After discovering devices, you need to build up their property lists, and make sure you handle property changes (that could be through events you get, or you may have to poll your devices). You also need to handle property updates from the user.

Restart the gateway process to test your changes:

$ sudo systemctl restart mozilla-iot-gateway.service

Test your add-on thoroughly. You can enable it through the Settings->Add-ons menu in the UI.

Get Your Add-on Published!

Run ./package.sh or whatever else you have to do to package up your add-on. Host the package somewhere, i.e. on Github as a release. Then, submit a pull request or issues to the addon-list repository.

Notes

  • Your add-on will run in a separate process and communicate with the gateway process via nanomsg IPC. That should hopefully be irrelevant to you.
  • If your add-on process dies, it will automatically be restarted.

Examples

The Project Things team has built several add-ons that can serve as a good starting point and reference.

Node.js:

Python:

Rust:

References

Additional documentation, API references, etc., can be found here:

Find a bug in some of our software? Let us know! We’d love to have issues, or better yet, pull requests, filed to the appropriate Github repo.

About James Hobin

Level 25 Computer Wizard on a quest to keep the Internet of Things free and open.

More articles by James Hobin…

About Michael Stegeman

Michael is a software engineer at Mozilla working on WebThings.

More articles by Michael Stegeman…


4 comments

  1. voracity

    HTTP or HTTPS?

    Has anyone worked out partially or fully decentralised S yet?

    February 10th, 2018 at 03:09

    1. James Hobin

      When configured to use our tunneling service, the Gateway serves its API over HTTPS using a certificate issued by Let’s Encrypt. If you instead want to run locally, we support either using self-signed certificates for HTTPS or running as HTTP.

      We definitely want to support decentralized HTTPS when a globally implemented standard appears. We’re keeping our eye on groups like the W3C HTTPS in Local Networks community group. They’re doing a lot of interesting work in this space: https://www.w3.org/community/httpslocal/

      February 12th, 2018 at 08:00

  2. Wim Haanstra

    Just trying out to get my own adapter into this. I copied the example plugin, and build a tiny addon that should just add a ‘device’ to the system.

    I just got a couple of questions, hoping you might be able to answer them:

    – Can I turn off the SHA256 checksum check? Having to run the package.sh everytime can be quite annoying.
    – When starting the server (with npm start), it tells me my package isn’t enabled. But I can’t find a way to enable it anywhere. It’s not listed in the “Settings” > “Addons” screen.

    February 20th, 2018 at 13:11

    1. James Hobin

      Thanks for trying it out! You can turn off the SHA256 checksumming by adding a `.git` directory in the plugin directory, e.g. ~/mozilla-iot/gateway/build/addons/philips-hue-adapter/.git. This directory can be empty or can be a real git directory.

      If your package is loading but not enabled it should be visible in the Settings/Addons screen with the option to enable it. Usually the gateway will list more information about what’s happening.

      February 20th, 2018 at 13:30

Comments are closed for this article.