Backend Handlers

Handlers define externally handled application, including:

• Format of the uplink and downlink messages
• Data fields forwared via the backend Connectors
• Retransmission logic for confirmed downlinks

Each Handler may be linked with one or more backend Connectors, which handle the communication towards the backend server.

The Handler will process every uplink frame and forward it to the backend. It will also process every downlink request received from the backend.

In addition to uplink frames the backend can receive device related events:

• when a device joined
• when a confirmed frame was delivered
• when a confirmed frame was lost
• for a connection test

Administration

To create a new handler you need to set:

• Application name
• Uplink Fields that will be forwarded to the backend Connector
• Payload format for automatic decoding
  • ASCII Text
  • Cayenne LPP
  • CBOR
  • Custom Binary decoded by the Parse Uplink function
• Parse Uplink function to extract additional data fields from the uplink frame
• Event Fields that will be forwarded to the backend Connector
• Parse Event function to amend event data fields
• Build Downlink function to create a downlink frame based on backend data fields
• D/L Expires defines when the downlinks may be dropped.
  • Never means that:
    • All class A downlinks for a device will be queued and eventually delivered.
    • All confirmed downlinks will be retransmitted until acknowledged, even when a new downlink is sent.
  • When Superseded means that:
    • Only the most recent class A downlink will be scheduled for delivery. Superseded downlinks will be dropped.
    • Unacknowledged downlinks will be dropped when a new downlink (either class A or C) is sent.

Test button can be used to send a test event to all connections associated with this handler.

Connectors related to this Handler are displayed for your convenience. The table lists all backend connectors with the same Application name.

Fields

Uplink

Depending on the Uplink Fields settings the server sends to backend applications the following fields:

The Gateway object included in best_gw and all_gw has the following fields:

For example:

    {"devaddr":"11223344", "port":2, "fcnt":58, "data":"0125D50B020BA23645F1A90BDDEE0004",
        "shall_reply":false, "last_lost":false,
        "rxq":{"lsnr":9.2,"rssi":-53,"tmst":3127868932,"codr":"4/5","datr":"SF12BW125","freq":868.3}}

Downlink

To send a downlink you must define a target node (or a group of nodes) by using one of the following fields either in the Received Topic template or in the message body:

In addition to that you may specify the following optional fields:

For example (class A):

    {"devaddr":"11223344", "data":"0026BF08BD03CD35000000000000FFFF"}
    {"devaddr":"11223344", "data":"0026BF08BD03CD35000000000000FFFF", "confirmed":true, "receipt":"123XYZ"}

Or (class C):

    {"data":"00", "port":2, "time":"2017-03-04T21:05:30.2000"}
    {"data":"00", "port":2, "time":"immediately"}

The time field must not be present if you want to send a Class A downlink.

Events

Depending on the Event Fields settings the server sends to backend applications the following fields:

Payload

The server can auto-parse some well-known data formats. In such case you don't need to write own Parse Uplink function.

ASCII Text

The payload will get stored into the text field as ASCII characters. This can can be used only when the device directly sends human readable text.

Cayenne Low Power Payload (LPP)

For each Data Channel N the server will create a fieldN with the parsed value. See Format Specification.

For example:

Custom Binary

To parse a custom format you need to write own Parse Uplink function.

Parse Uplink

The Parse Uplink is an Erlang function that converts binary data to custom data fields and can extend (or even amend) the Uplink Fields.

This function is optional. If not provided, only the Uplink Fields will be sent to the Backend.

If provided, Parse Uplink shall be a Fun Expression with two parameters: Fields and a binary pattern. The function shall match the binary data and return a map expression with the desired fields.

The selected Uplink Fields are provided in the Fields variable, which you extend, for example:

fun(Fields, <<LED, Press:16, Temp:16, AltBar:16, Batt, Lat:24, Lon:24, AltGps:16>>) ->
  Fields#{led => LED, pressure => Press, temp => Temp/100, alt_bar => AltBar, batt => Batt}
end.

Or even modify, for example:

fun(#{fcnt := FCnt}, <<LED, Press:16, Temp:16, AltBar:16, Batt, Lat:24, Lon:24, AltGps:16>>) ->
  #{seq => FCnt, led => LED, pressure => Press, temp => Temp/100, alt_bar => AltBar, batt => Batt}
end.

To accept various frames in one function you can write alternative functions, for example:

fun (Fields, <<16#0402:16, Temp:16/signed>>) ->
        Fields#{temp => Temp};
    (Fields, <<16#0405:16, Level>>) ->
        Fields#{level => Level}
end.

To send multiple messages based on one frame (or even discard the frame and send no message) the function may also return a list of map expressions, for example:

fun(Fields, <<LED, Press:16, Temp:16, AltBar:16, Batt, Lat:24, Lon:24, AltGps:16>>) ->
  [
    Fields#{led => LED},
    Fields#{pressure => Press},
    Fields#{temp => Temp/100}
  ]
end.

This will generate 3 messages, each including the selected Uplink Fields plus one data field.

To send one message with a list of expressions, send a list-in-list, for example:

fun(Fields, <<LED, Press:16, Temp:16, AltBar:16, Batt, Lat:24, Lon:24, AltGps:16>>) ->
  [
    [
      Fields#{led => LED},
      Fields#{pressure => Press},
      Fields#{temp => Temp/100}
    ]
  ]
end.

This will generate one message containing a list of 3 items.

The <<A, B, C>> used to match the frame payload is a binary pattern, where A, B, C are "variables" corresponding to the values encoded in the binary. Erlang matches the incoming binary data against this pattern and fills the "variables" with the values in the binary. Here are some examples:

• <<A>> matches 1 value, 1 byte long.
• <<A, B>> matches 2 values, each 1 byte long.
• <<A:16>> matches 1 unsigned int value, 2 bytes long in big-endian
• <<A:16/little-signed-integer>> matches 1 signed int value, 2 byes long in little-endian
• <<A:2/binary>> matches an array of 2 bytes

To match a variable sized array of bytes, prefixed with a size byte, you can do:

fun(Fields, <<Count, Data:Count/binary>>) ->
  Fields#{data => binary_to_list(Data)}
end.

The expression #{name1 => A, name2 => B, name3 => C} then creates (depending on your Connector settings) a JSON {"name1":A, "name2":B, "name3":C}, or a Web-Form name1=A&name2=B&name3=C.

Retained Messages

The field retain has a special meaning for the MQTT handler:

• retain = false - create a non-retained message
• retain = true - create a retained message
• retain = delete - delete the retained message and create a non-retained message

The field retain is not sent in the message to the MQTT handler.

If the field retain is not present, a non-retained message is created.

Parse Event

The Parse Event is an Erlang function that converts event name to custom data fields and can extend (or even amend) the Uplink Fields.

Also this function is optional. If not provided, only the Uplink Fields will be sent to the Backend.

To generate events like {"devaddr":"00112233", "event":"joined"} you can write:

fun(Vars, Event) ->
  Vars#{event => Event}
end.

Alternatively, to generate an object like {"joined":{"devaddr":"00112233"}} write:

fun(Vars, Event) ->
  #{Event => Vars}
end.

Returning a list to send multiple event messages is not allowed.

Build Downlink

Build Downlink works in the opposite direction. It takes the data fields and constructs the binary payload.

This function is optional. If not provided, the downlink data will be taken from the data field, e.g. when you send {"devaddr":"11223344", "data":"01"}. The data field must be in hexadecimal notation.

If provided, Build Downlink shall be a Fun Expression with a single parameter, which gets an Erlang representation of JSON and returns binary data.

JSON data is converted to a map. Fields taken from the MQTT topic are added to the map. This map is passed as sole parameter to the downlink function. The download function may either return a binary, a map, or a (possibly empty) list of maps.

• If a binary is returned, this binary is used to fill the data field which is sent to the device.
• If a map is returned, this map replaces the original map. All relevant fields like devaddr, deveui, port, and data may be set in the downlink function.
• If a list of maps is returned, the server triggers multiple downlink messages, one for each list item. Upon returning an empty list no downlink will be triggered.

For example, if you send {"devaddr":"11223344", "led":1}, you can have a function like this to convert the custom field (led) to downlink data:

fun(#{led := LED}) ->
  <<LED>>
end.

The #{name1 := A, name2 := B, name3 := C} matches the fields attribute containing a JSON structure {"name1":A, "name2":B, "name3":C}. The order is not significant, but all fields are mandatory.

The binary is then built using similar approach as the pattern matching explained above. For example, <<A, B, C>> builds a binary of three 1-byte integers.

To build a variable sized array you can do:

fun(#{data := Data}) ->
  <<(length(Data)), (list_to_binary(Data))/binary>>
end.

Here is a simple example just adding a port and a data field to the original map:

fun(Fields) ->
  Fields#{
    port => 43,
    data => << 16#88 >>
  }
end.