Skip to main content

HTTP

This page has not been fully updated to represent the latest state of the Helium Network following the migration to Solana on April 18, 2023.

Add an HTTP Integration​

To add a Integration, go to Integrations on the left-hand menu. Select the integration to add - in this case, the HTTP integration.

The next step is to paste the HTTP endpoint.

If you're still testing, you can find popular sites that can create HTTP endpoints for you and inspect packets. Requestbin and Beeceptor provide tools to make an HTTP endpoint quickly and easily.

Uplinking refers to your device sending data to be received by the network. For the HTTP integration, this will be the data from the device that is sent to your HTTP endpoint of choice.

RequestBin Example​

Create an endpoint by going to requestbin.com and click Create a Request Bin. Once created, copy the endpoint.

... and paste it in Console's Endpoint URL field.

HTTP Header and Value are not required, and can be left blank.

Lastly, provide a name for the integration. Names do not have to be unique.

Click Add Integration.

Your new integration is now ready for use! Please read about the JSON Schema to understand how to parse data received.

Integration Details​

View the details of your integration by clicking on the Integration name.

Integration Details shows the integration ID that is unique to each integration, the name, the type of integration, and whether it is active or not.

HTTP Details shows the specific endpoint which can be changed.

Devices Piped lists all the devices that are currently sending their data to the selected integration.

Update your Connection Details allows you to update your HTTP connection details for the currently viewed integration.

Downlink refers to the network sending data down to be received by your device. With regards to the HTTP integration, this will be data sent to a unique URL called the downlink_url provided by Console.

https://console.helium.com/api/v1/down/{Integration_ID}/{Downlink_Key}/{:optional_device_id}

You can send downlinks to every device that your HTTP integration is attached to or just a single device by including the device UUID at the end. You can find this downlink_url with the required downlink key in it on the HTTP integration page in the details section, an example is shown below.

The downlink URL can also be found in the uplink JSON message for that particular device. It will look similar to the URL shown below. You can also find it using the Debug window on your device page.

"downlink_url": "https://console.helium.com/api/v1/down/897780bc-6980-42c1-a659-30077e8dbcd1/h4IxFDle6biV1ZKmrUJamaXhKjRRF3c-"
"downlink_url": "https://console.helium.com/api/v1/down/897780bc-6980-42c1-a659-30077e8dbcd1/h4IxFDle6biV1ZKmrUJamaXhKjRRF3c-/d2c7b8dc-221a-4ec8-aedd-6c19ae348a33"

To send the downlink message, make a POST request including a JSON body with the following fields shown below, see more details on the fields here.

{
    "payload_raw": "SGVsbG8sIHdvcmxkIQ==",
    "port": 1,
    "confirmed": false
}

The easiest way to send a downlink to your device is to use the built-in downlink tool in Console. You will find it on the right side of every device page, as shown below. In order to use the downlink tool, you must have an HTTP Integration attached to the device.

Once you have the downlink tool open, input the downlink payload string in the payload field. Select Encoded if you are inputting a string that is already Base64 encoded, and Plain if it is plain text. Last, select your FPort, whether or not you want to send a confirmed downlink, and then click the downlink send button, as shown below.

Once you have initiated the downlink, you should see the downlink event show in the event log, as shown below.

Postman Example​

Postman is a popular developer utility for HTTP based services, you can download it here. We can use this utility to easily make a POST request to the downlink URL with our downlink JSON message. Follow the steps below to successfully send your downlink message to your device.

  1. Select the type of HTTP request, POST in this case.
  2. Enter the downlink URL here.
  3. Select Body to begin entering your message details.
  4. Select raw as your body type.
  5. Select JSON as the body format.
  6. Enter your JSON message with the required fields.
  7. Finally, press Send to transmit the message.
  8. You should see a response of Downlink scheduled if successful.

Python Example​

Python is a popular programming language. The following code generates a request to the Helium Network to downlink data to a device.

import requests
import base64

# copy the Device ID from the Device page in the Helium Console
device_id = '...'

# copy the Downlink URL from the Helium Console (HTTP Integration), replacing "{:optional_device_id}" with "+ device_id"
url = f'https://console.helium.com/api/v1/down/a0a0a0a0-10a0-1018-a0a0-a0a0a0a0a0a0/asdfasdfasdf_asdfasdfasdfasdf/' + device_id

payload_str = 'TEST'
payload_b64 = base64.b64encode(payload_str.encode('utf-8')).decode('ascii')

print(f"Payload (base64): {payload_b64}")

data = {
	"payload_raw": payload_b64,
	"port": 1,
	"confirmed": True,
}

r = requests.post(url, json=data)

print(f"HTTP Response: {r}. Text: {r.text}")

# data appears as hex on receiver-side (on many units)
import binascii
print(f"Received client-side hex: {binascii.hexlify(payload_str.encode('utf-8')).decode('ascii').upper()}")

Connecting Integrations to Devices​

Devices or groups of devices (via labels) can be directly connected to integrations on the Flows Worskpace. Labels are identifiers used to group devices for easy management. To connect one or more devices to one or more integrations, simply connect the Device and Integration nodes on the Flows Workspace.

info

Quick video tutorial connecting devices to an integration here.

Node elements (devices, labels, integrations) need to be created before they're available on the Flows Workspace.

Advanced - JSON Message Template​

important

This is an optional, advanced feature and should only be used by users familiar with logic-less templates.

Users can customize the JSON Message structure sent to Integrations (i.e., to the HTTP endpoint, from the Helium Console). This feature includes the ability to write custom JSON Messages, decoder functions, and use supplied predefined JSON templates for Cayenne and Browan.

Decoding base64 payloads​

Users can send decoded base64 payloads (to hex or bytes) from device to desired integration, without creating a decoder function for brevity.

To decode the base64 payload simply use base64_to_hex() or base64_to_bytes() in your integration JSON like the following (other keys are optional):

{
  "payload": "{{base64_to_hex(payload)}}",
  "name": "{{name}}",
  "app_eui": "{{app_eui}}",
  "dev_eui": "{{dev_eui}}",
  "devaddr": "{{devaddr}}",
  "fcnt": "{{fcnt}}",
  "port": "{{port}}",
}
{
  "payload": "{{base64_to_bytes(payload)}}",
  "name": "{{name}}",
  "app_eui": "{{app_eui}}",
  "dev_eui": "{{dev_eui}}",
  "devaddr": "{{devaddr}}",
  "fcnt": "{{fcnt}}",
  "port": "{{port}}",
}