Ubidots and Helium have partnered to create a pre-built integration allowing users to easily forward sensor data from Helium Console to Ubidots using Plugins.
This Integration is optimized to automatically decode Helium’s JSON schema (pulling items such as hotspot metadata so you don’t have to!), while still allowing for full customization using the power of Python.
Table of Contents
- Creating a Helium Plugin
- Decoding payloads from Helium Devices
- Editing the Plugin's device type
- Feedback & suggestions
1. Creating a Helium Plugin
A Helium plugin is a serverless function that exposes a private HTTP Endpoint URL optimized to decode Helium's JSON schema. Every time an HTTP POST request is received at such URL, a pre-defined decoding function will be executed.
You can create a plugin from either Helium's console or Ubidots platform:
Creating the plugin from Helium
1. In your Ubidots account, copy an existing or new account token. We recommend creating a new token dedicated to this plugin only, should you need to increase its rate limit in the future.
2. In the Helium Console, go to "Integrations", then click on "Ubidots":
3. Paste the Ubidots account token in the field "Enter Auth Token", then click on "Get Webhook URL". This will automatically provision a new Helium plugin inside your Ubidots account.
4. Add a name to the integration, assign a Helium label, and click on "Add Integration" to finish the process:
PROTIP: Helium labels are a powerful mechanism to organize devices and integrations. Simply attach a label to one or more devices, and then attach the same label to one or more integrations.
5. Finally, back to your Ubidots account, go to the "Devices" tab, click on "Plugins", and check that a plugin was eventually created:
The plugin may take up to a minute to provision.
Creating the plugin from Ubidots
Alternatively, advanced users may choose to create the plugin directly from Ubidots, and then create a custom HTTP integration in Helium.
- In your Ubidots account, go to the "Devices" tab, click on "Plugins", then click on the "+" icon to create a new Plugin. Search for the Helium Plugin and click on it:
2. The plugin readme will appear. Click on the "Next" icon, then review the configuration:
- Ubidots device type: An Ubidots device type will be created and linked to this plugin. This allows you to make batch changes to all of the devices that receive data through this plugin.
- Helium labels as: Select how you'd like Helium labels to be treated within Ubidots. Currently supporting "Device tags".
- Ubidots token: Select the Ubidots token you'd like to use for this plugin. We recommend creating a new token dedicated to this plugin only, should you need to increase its rate limit in the future.
3. Finish the process and a new plugin will appear in the Plugins list:
4. Click on the newly-created Helium Plugin, click on the "Decoder" tab, and copy the "HTTPs Endpoint URL":
5. Finally, go to the Helium Console, create an HTTP integration, and paste the plugin's "HTTPs Endpoint URL":
2. Decoding payloads from Helium Devices
After creating a Helium Plugin and clicking on it, you will see a "Decoder" tab, which contains a "Decoding Function" that you can edit at will, in order to decode your data frames.
By default, you will see a pre-loaded sample decoder that does the following:
- Create RSSI and SNR variables for each hotspot receiving a signal from your device.
- Create a Frame counter, and a Port variable.
- If found, the decoded.payload JSON will be forwarded as-is to Ubidots, assuming it has an Ubidots-friendly format. If not, then a custom decoder can be used.
Ubidots will automatically create a device every time a payload from a new device is received. This saves you the need to manually create hundreds or thousands of devices, or copy-and-paste DevEUI's from one platform to the other.
See here how Helium's JSON schema is mapped to Ubidots devices:
Please note that you can change some but not all of the above configurations:
Configurations that CAN be edited from the decoding function:
- Hotspot parameters: You may choose to drop unwanted parameters
- Variables: You may choose to drop variables, or even create new ones using the power of Python (See supported libraries!)
- Timestamp: You may choose to ignore Helium's timestamp and have our API assign one automatically upon reception
Configurations that CANNOT be edited in the decoding function:
- Device name: The Plugin always uses Helium's device name as Ubidots' device name
- Device label: The Plugin always uses Helium's "id" as Ubidots device label
- Device properties: The Plugin always uses Helium's "app_eui", "dev_eui", and "devaddr" as Ubidots device properties.
If you wish to have control over these, you may want to build your own UbiFunction instead.
3. Editing the Plugin's device type
An Ubidots device type will be created and linked to this plugin. This allows you to make batch changes to all of the devices that receive data through this plugin.
For example, let's imagine you edited the decoding function to generate two variables: Temperature and Pressure. By default, these variables will contain default colors and icons, and no units. If you wish every future device to have an automatic and custom configuration for these variables, then you will want to change the device type:
The best way to test the plugin is by making an HTTP request to the Plugin's URL. Just grab the sample JSON payload from Helium's docs, and send it in an HTTP POST request using an HTTP client of your choice (Postman or similar). Make sure you add the header "Content-Type:application/json":
After making the request, a new device should be created.
Please note the first time the plugin is executed, it may take a few seconds to respond. To check the Plugin logs, go to the Plugin, click on the "Logs" section and you should see a list of the latest executions. Click on the last one and check its contents:
5. Feedback and suggestions
Learn more about other plugins: