Helium compatible Integration - disk91/helium-chirpstack-community GitHub Wiki

HTTP Integration

It's possible to create an helium compatible HTTP integration, this is to maintain the existing application server format and facilitate the migration. This integration also contains the Gateway location when you need this information.

In case of new project, we recommend to prefer a native Chirpstack integration.

Migration

The HTTP integration can be imported during the migration process automatically. Just follow the migration process. Compared to Helium Legacy console, chirpstack does not support multiple integration and you will need to manage things differently. We have no support for such situation.

Manual configuration

If you need to configure a Helium retro-compatible integration, you need to create an integration with the following parameters:

  • endpoint of the https integration http://fwdlb:8082/capture/
  • headers:

    • htype: type of integration, can be http

    • hendpoint: url to call on every uplink received

    • hlocendpoint : url to call on every location event received (works with semtechCloud location service) (optional)

    • hackendpoint : url to call on every ack event received (optional)

    • hjoinendpoint : url to call on every join event received (optional)

    • hverb: type of call, can be post or put

    • hheaders: is a list of headers you want to pass like { "Authorization": "Bearer jhfkhsldk", "Key" : "12356" } or {}

    • hurlparam: is a list of params to be added to the url after the hendpoint like hheader in term of format

    • hid: is a reference to helium legacy console, no need to be filled

    • huptopic: see mqtt documentation above

    • hloctopic: see mqtt documentation above

    • hacktopic: see mqtt documentation above

    • hjointopic: : see mqtt documentation above

    • hdntopic: see mqtt documentation above

    • hformat: see mqtt documentattion above

The hendpoint will be called with every uplinks with a Helium payload enriched with hotspot location. The hlocendpoint will be called on every location event and contain the device location, this works with SemtechCloud location service.

The downlink url is given in every uplink message, the path change for every uplink and the link is only valid for 1 minute after reception of the uplink. If you need asynchronous downlink, you need to use the Chirpstack API.

The payload format for the loc event is described above in the MQTT section.

Add the app_eui into the Helium payload

As Chirpstack does not use app_eui, you need to manually add it into the chirpstack structure to be processed by the forwarder. As the integration is at a group of devices, you need to add this information in the decoding object created by the Codec in the Device_profile.

As an exemple you can add it that way:

function decodeUplink(input) {
  return {
    data: {
      ...,
      appeui: input.variables.app_eui
    }
  };
}

External transformation

You can also choose to receive the Chirpstack payload on your server and request a payload transformation and enrichement by calling the transformation service.

MQTT Integration

The Chirpstack native MQTT integration is using the internal MQTT broker and is not a safe way to do integration for a public usage of Chirpstack, it also not allow to send message to an external broker.

For this reason, we have implemented a connector to send your payload to an external MQTT broker. This connector is mostly compatible with the Helium legacy console MQTT integration. The Payload is also transformed and enrich to be compatible with legacy Helium payload, including the Hotspot location information.

MQTT integration will rely on an HTTP integration on Chirpstack to the forwarder component with the following configuration:

  • endpoint of the https integration http://fwdlb:8082/capture/
  • headers:
    • htype: type of integration, can be mqtt. Mandatory field.
    • hendpoint: mqtt url like mqtt(s)://user:[email protected]:1883. Mandatory field.
    • huptopic: The uplink topic to be used, like myApplication/{{device_id}}/upChannel, {{device_id}} will be replaced. Payload can be Helium legacy (default) or Chirpstack. Mandatory field.
    • hloctopic: The location topic to be used, like myApplication/{{device_id}}/locChannel, {{device_id}} will be replaced. This channel is only activated by loc event, like using the SemtechCloud location service.
    • hdntopic: The downlink topic to be used, like myApplication/{{device_id}}/dwChannel, {{device_id}} is mandatory. {{device_id}} = device_eui
    • hacktopic: The ack event topic to be used, like myApplication/{{device_id}}/ackChannel, {{device_id}} will be replaced. This channel is only activated by ack event. Payload is always Chirpstack format.
    • hjointopic: The join event topic to be used, like myApplication/{{device_id}}/joinChannel, {{device_id}} will be replaced. This channel is only activated by join event. Payload is always Chirpstack format.
    • hqos: Select the QoS or MQTT messages to your broker, default is 2 from version 1.5.1 (0 previously), possible value 0,1,2
    • hformat: Select the payload format output, values are helium or chirpstack. default is helium

The connection to MQTT server will be made on first message and will maintain until we see no uplink for 2 hours on it. The downlink channel must specify the device_id, only devices having sent an uplink during the MQTT session validity will be authorized to receive a downlink for security reasons.

The possible dynamically replaced variables in uplink topic name are: {{device_name}}, {{device_eui}}, {{organization_id}}, {{app_eui}}. On downlink topic name, only {{device_id}} is supported, it is also mandatory, {{device_id}} is device_eui on chirpstack.

The message format for the downlink requests is the following:

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

payload_raw is a base64 Hex-String encoded corresponding to the bytes to be send. When payload contains __clear_downlink_queue__, encoded or not, the downlink queue on Chirpstack will be cleared.

In the case of CLASS C device, the MQTT subscription must be open first with an uplink message from the device and can be maintained with a fake single downlink message for the whole fleet sent once an hour. Fake downlink message have port value -1 and same format as a normal downlink. As HPR load balancer also disconnects the hotspots from the LNS, to get a long tail class C working, the device must have a regular communication with the LNS, like every 15 - 30 minutes. This will also maintain the forwarder subscription to the downlink topic or resume it.

The message format for the location event is the following:

 {
    "dev_eui" : "01a2b3c4d5060708",
    "app_eui" : "0102030405a6b7c8",
    "organization_id" : "1231-1315-1515315315",
    "name" : "myDevice",
    "latitude" : 42.2,
    "longitude": 3.5,
    "accuracy": 20,
    "source": "GEO_RESOLVER_GNSS",
 }

When hloctopic is not defined and a loc event is reported, the default topic is be huptopic/location.