Skip to content

Technical Annexes

Note

Things to keep in mind:

  • Commands can be concatenated, First In, First Out. The message queue is not that big, and some of them might be lost without notice.
  • Message queue is reset on reboot.
  • Mote can send SampleData and Health messages without being asked for when connecting to mote, before or while any cmd is sent (only if it is time do so). Don't be confused: you can receive not-asked data anytime.
  • Even if you disconnect from the mote, it might be working on processing and sending data (eg.: sending RecoverData reports might take up to 8 minutes, asking for 50 nonexistent GSI sensors takes up to 3 min). Data might have been asked for in a previous session. The only TCP is the Seq number of the mote output messages.

Useful User Commands

Some useful commands to get the node working

User Command what to send Expected Response Comments
Get health info LSAMTYPE_IN_GET_HEALTH Rx:LSAMTYPE_OUT_HEALTH_DATA Request the health information to the node. This may be used to ensure that the node is connected, and prevent the serial timeout.
Configure the reporting period LSAMTYPE_IN_SP_CFG Rx:Rx:LSAMTYPE_OUT_RESPONSE (OK) Configure the node's reporting period, how often the node will transmit a data message.
Set current time LSAMTYPE_IN_SET_TIME Rx:Rx:LSAMTYPE_OUT_RESPONSE (OK) Set the current date and time.
Set PR code LSAMTYPE_IN_SET_PRCODE_SN_V2 Rx:Rx:LSAMTYPE_OUT_RESPONSE (OK) If the node has the wrong PR code, some configs will not be accepted.
Set node ID LSAMTYPE_IN_SET_NODE_ID_V2 Rx:Rx:LSAMTYPE_OUT_RESPONSE (OK) Node ID to identify the messages.
Factory reset LSAMTYPE_IN_FACTORY_RESET Rx:Rx:LSAMTYPE_OUT_RESPONSE (OK) Deletes all the configs leaving the node in a predictable state.
Get sample now LSAMTYPE_IN_GET_SAMPLE_NOW Rx: product specific data message Request a new data message from the node. Note that most products will not be configured to send data by default. Thus, a product specific config should be set before.

Note: To enable the radio configuration is best to just use the mobile App. Since it requires multiple different configs.

LoRaWAN/LoRaMAC interface

All messages going through the lora interface follow either the LoRaMAC or LoRaWAN protocol. These protocols define a set of ports (1 to 223) for data frames that can be used by the user to differentiate between different types of data frames. Event detection alert messages use a specific port, and not the standard, as specified in the following table:

FPort (*) AM_TYPE Message
2 0x0A LSAMTYPE_OUT_T360A_ALERT
1 (Standard) All others LSAMTYPE_OUT_* (AM_TYPE ≠ 0x0A)

(*) More detailed information about LoRaWAN ports can be found here (section 4.3.2 Port field).

Annex A: Field Types

Type Description
UInt Unsigned integer
Int Signed integer
Bool Boolean (1 bit)
Enum Enumerated value — possible values listed in Description
Struct Container grouping sub-fields
Switch Conditional container — only one branch is active
Seq Variable-length sequence of repeated elements
Bytes Raw byte payload
TimestampField Unix timestamp
Fragment Part of a larger field reassembled from fragments
Reserved Reserved for future use
Bitmap Bit-level flags

Annex B: DIG Gen Payloads

DIG Generic messages (DigGenDataStrMsg) carry integration-specific payloads identified by a combination of integration_id and message_version. Each payload type is documented as a separate message page.

Annex C: Error Messages

When some parameter is wrong (out of range, invalid size) or something unexpected occurs, the mote sends the message LSAMTYPE_OUT_RESPONSE, with additional information. Be aware that this message is also sent to indicate Ok responses.

Annex D: Serial interface

The messages sent through the serial interface are packetized using the BSC protocol:

  • A DLE STX (\x10\x02) sequence marks the beginning of the message.
  • A DLE ETX (\x10\x03) sequence marks the end of the message.
  • Any DLE (\x10) in the data is doubled.

Annex E: CRC calculation

All the CRCs in the memory are of the type CCITT of 16 bits as given by the following code:

#define CRC16CCITT_INIT 0x0000
#define CRC16CCITT_POLY 0x1021
uint16_t crc16_ccitt( const void *data, uint16_t number_of_bytes_in_data )
{
    uint8_t i;
    uint16_t crc = CRC16CCITT_INIT;
    while( number_of_bytes_in_data-- ) {
     crc ^= *(uint8_t *)data++ << 8;
     for( i = 0; i < 8; ++i ) {
         if( crc & 0x8000 )
             crc = (crc << 1) ^ CRC16CCITT_POLY;
         else
             crc = crc << 1;
     }
    }
    return crc;
}

Annex F: Configuration of LoRa radio per country

See LoRa - Radio Configs spreadsheet.

Annex G: Generic Modbus Instructions Cfg Message

The Generic Modbus Instruction Message configures the instruction program used by the DIG Generic Modbus integration.

It exists in three channel variants (port 0/1/2), but all of them share the same payload format:

  • LSAMTYPE_IN_DIG_GMM_INSTRUCTIONS_PORT0_CFG: 151
  • LSAMTYPE_IN_DIG_GMM_INSTRUCTIONS_PORT1_CFG: 174
  • LSAMTYPE_IN_DIG_GMM_INSTRUCTIONS_PORT2_CFG: 175

What Is Different In This Message

Unlike fixed-range messages, this one is data-driven by generic_modbus_configs.json:

  • configId accepted range is not hardcoded.
  • Min and max configId are loaded from JSON cfg_id values at runtime.
  • Adding/removing JSON entries automatically updates accepted configId bounds without changing message code.

Important: the message payload still carries raw instruction bytes (globalInstructionBuffer and sensorInstructionsBuffer). The parser validates the schema and ranges; it does not auto-generate instruction bytes from configId.

Instruction Base Format

Each instruction is encoded as:

Code Arg 1 Arg 2 Arg 3 Arg 4
1B Optional (up to 2B) Optional (up to 2B) Optional (up to 2B) Optional (up to 2B)

Rules:

  • Minimum valid instruction is the single-byte opcode.
  • Arguments are opcode-dependent.
  • Last instruction in each buffer must be followed by zero padding up to full buffer size.

Supported Instruction Opcodes

Opcode Mnemonic Description Arg 1 Arg 2 Arg 3 Arg 4
0x00 Push_16 Push typed 16-bit value to stack Type (2 bits: 00 float32, 01 uint32, 10 int32) Value (16 bits) - -
0x01 Push_32 Push typed 32-bit value to stack Type (2 bits: 00 float32, 01 uint32, 10 int32) Value High (16 bits) Value Low (16 bits) -
0x02 Pop Pop top stack element - - - -
0x03 Read Modbus Read 1 or 2 Modbus registers and push typed result Type of value (2 bits) 00:float32_t, 01:uint32_t, 10:int32_t Modbus reg type (1 bit: 0 holding, 1 input) Reg count (1 bit: 0->1, 1->2) Addr (16 bits)
0x04 Write Multiple Modbus Write top stack value to Modbus address Reg count (1 bit: 0->1, 1->2) Addr (16 bits) - -
0x05 Jump Unconditional branch Instruction idx (8 bits) - - -
0x06 Branch eq Branch when N-1 == N Call (3 bits) Call Param (8 bits) - -
0x07 Branch nq Branch when N-1 != N Call (3 bits) Call Param (8 bits) - -
0x08 Branch gt Branch when N-1 > N Call (3 bits) Call Param (8 bits) - -
0x09 Branch ge Branch when N-1 >= N Call (3 bits) Call Param (8 bits) - -
0x0A Branch lt Branch when N-1 < N Call (3 bits) Call Param (8 bits) - -
0x0B Branch le Branch when N-1 <= N Call (3 bits) Call Param (8 bits) - -
0x0C ADD Add top two stack elements - - - -
0x0D SUB Subtract top element from previous (N-1 - N) - - - -
0x0E MULT Multiply top two stack elements - - - -
0x0F DIV Divide previous by top (N-1 / N) - - - -
0x10 OR Bitwise OR of top two stack elements (no float) - - - -
0x11 AND Bitwise AND of top two stack elements (no float) - - - -
0x12 XOR Bitwise XOR of top two stack elements (no float) - - - -
0x13 Shift R Right shift top element N bits (5 bits) - - -
0x14 Shift L Left shift top element N bits (5 bits) - - -
0x15 Cast Change top element type Type (2 bits: 00 float->int, 01 float->uint) - - -
0x16 Sleep ms Sleep top element milliseconds - - - -
0x17 Push to data Out Append N bits from top element to output data Number of bits (6 bits) - - -
0x18 Check voltage supply Compare top uint32 stack value with configured supply threshold - - - -
0x19 Duplicate Duplicate top stack element if stack is not full - - - -
0x1A Bury Move top element to target stack position Stack position (4 bits, top not allowed) - - -
0x1B Dig Move target stack position element to top Stack position (4 bits, top not allowed) - - -
0x1C Branch float NaN Branch if top float is NaN Call (3 bits) Call Param (8 bits) Push-out error type (2 bits, only when call is error) -
0x1D Branch float Inf Branch if top float is Inf Call (3 bits) Call Param (8 bits) Push-out error type (2 bits, only when call is error) -
0x1E Branch float NotFinite Branch if top float is not finite Call (3 bits) Call Param (8 bits) Push-out error type (2 bits, only when call is error) -
0x1F Branch float NotNormal Branch if top float is not normal Call (3 bits) Call Param (8 bits) Push-out error type (2 bits, only when call is error) -
0x20 Write Single Modbus Write top stack value to Modbus address (16-bit value only) Addr (16 bits) - - -

Branch Call Table

Branch instructions use a 3-bit Call selector plus an 8-bit call parameter.

Call Meaning Param
0 ERROR CALL Error action code
1 GOTO CALL Instruction index
2..7 Reserved Not accepted (config error)

ERROR CALL parameter values:

  • 0: Not allowed.
  • 1: Sensor did not respond; stop current sensor execution; set sensor error bit.
  • 2: Measurement out of range; skip until next push data out; clamp value to max according to output signedness/bit-width.
  • 3: Voltage error; stop all sensor execution and send error message.
  • 0x04..0xFF: Not used yet (config error).

GOTO CALL parameter:

  • Instruction index starts at 0.
  • Valid range is 0..SNI.
  • If index >= SNI, configuration is invalid.