Custom Implementation

In most cases, the platform integration provided by Soracom allows you to focus on building your application without worrying about how to implement hardware or firmware functionality, or how to decode/encode messages coming from or going to the Soracom LTE-M Button.

However, in some cases, you may prefer to process the messages on your own, such as to build your own interface for configuring and managing buttons, or inspecting packets for troubleshooting.

Below are the technical specifications for how binary data coming from or going to the Soracom LTE-M Button is implemented.

Implementation overview

The Soracom LTE-M Button is programmed to send messages in a UDP packet using a custom binary data format, allowing it to consume significantly less data compared to other common data formats or protocols and to minimize battery usage. The platform integration provided by Soracom takes care of decoding the binary data from (and encoding binary data responses to) the button into an easier-to-use JSON format.

The Soracom LTE-M Button leverages multiple Soracom services in order to provide full platform integration. Messages sent by the button are processed as follows:

The button sends a binary message to Unified Endpoint.
The binary message is decoded by Binary Parser into JSON using the symbol and message format specifications below.
The decoded message is processed by Soracom Orbit in order to update the SIM tags that correspond to the button, allowing you to check button details such as operation mode and battery voltage from the User Console.
The JSON data is then sent to any Soracom platform services you have enabled for handling the data, such as Soracom Beam or Soracom Funk for forwarding the message to an external server or cloud function, or Soracom Harvest Data to store the message in Soracom.
Finally, if the message sent was a Status message, Soracom Orbit will also check if the button's current configuration matches the configuration you specified. If any changes are required, Soracom Orbit will construct a Set Configuration message using the symbol and message format specification below and send the binary message back to the button to apply the necessary configuration. Otherwise Soracom Orbit simply sends a Server ACK message.

Service integration

By default, all of the services above (except for Soracom Beam, Soracom Funk, or Soracom Harvest Data) are automatically configured when you create a Soracom LTE-M Button group and should provide enough flexibility for most applications.

However, if you want to build your own system for processing button messages, you may need to manually configure the Binary Parser, Soracom Orbit, and Unified Endpoint settings, or reimplement their functionality using the symbol and message format specifications below, depending on your application requirements. The following table summarizes each of the necessary service configurations:

Service	Configuration	Function	Can be manually implemented?
Binary Parser	Format - `@soracom.button`	Converts uplink messages from binary to JSON	Yes
Soracom Orbit	Code SRN - `srn:soracom:OP0052363844:g:Soralet:soracom-lte-m-button-configuration/$LATEST`^1 Content Type* - `application/json` Direction - Downlink Use metadata - Enabled	Updates SIM tags and constructs binary messages to send back to the button	Yes^{2, 3}
Unified Endpoint	Format - Custom Custom response on success Status Code - `200` Content Type - `application/octet-stream` Skip status code - Enabled Custom response on failure Status Code - `400` Content Type - `application/octet-stream` Skip status code - Enabled	Allows sending downlink messages to the button in binary	No^*4

^{*1 - This Soracom Orbit Soralet specified by this Code SRN is officially developed and maintained by Soracom.

*2 - You can use the Soracom API to update SIM tags without using Soracom Orbit.

*3 - You can construct binary messages to send back to your button without using Soracom Orbit. However, if you want to use Soracom Orbit, you must also enable and configure Metadata Service User data.

*4 - Configuring Unified Endpoint is not required but may prevent Set Configuration messages from being delivered correctly.}

Uplink and downlink message flow

When a button sends an uplink message, it expects a response from the server in order to confirm that the uplink message was successfully received. The server should respond with the Server ACK message. If the server does not respond, the button will assume that the uplink message was not received and attempt to send the message again.

When modifying a button's configuration, the server should first wait for an uplink Status message from the button. Once the server receives the message, it can respond with a Set Configuration message containing the configuration options to apply. The button will send an OOB message to indicate that it successfully received the Set Configuration message and applied the configuration.

Symbols

Symbols are the parameters or variables represented in the binary data sent from (uplink) or to (downlink) a button, and their possible values and unit conversions.

Uplink symbols

Symbol	Length/Type	Values	Description	Decoded by Binary Parser
prod_type	3-bit fixed value	`001` - Soracom LTE-M Button	Indicates the product type.	Yes
f_ack	1-bit boolean	`0` - false `1` - true	Indicates if the server needs to send an ACK downlink message.	Yes
msg_type	4-bit enum	`0000` - Status message `0001` - Event message `0010` - Timer message `0011` - Heartbeat message `0101` - Alert message (firmware 3134 only) `0110` - Event with Temperature message `1111` - OOB message (others) - Reserved	Indicates the type of message sent by the button.	Yes
seq_number	16-bit unsigned integer	Range: 0–4,095	Indicates the number of messages sent by the button, excluding retries.	Yes
batt_vol	8-bit unsigned integer	Range: 0–255	Indicates the current battery voltage, in increments of 100mV.	Yes^*5
fw_ver	16-bit hexadecimal	`0x2220` - Firmware version 2220 `0x3134` - Firmware version 3134	Indicates the firmware version of the button.	Yes
hw_ver	16-bit hexadecimal	`0x0102` - Hardware version 102	Indicates the hardware version of the button.	Yes
curr_oper	4-bit enum	`0001` - Timer `0010` - Event `0011` - Event + Timer `0100` - Event + Heartbeat `0101` - Alert (firmware 3134 only) `0110` - Alert + Heartbeat (firmware 3134 only) (others) - Reserved	Indicates the current operation mode of the button.	Yes
curr_sync	1-bit boolean	`0` - false `1` - true (firmware 3134 only)	Indicates if the button will automatically send a Status message once every 24 hours.	Yes
curr_debounce	1-bit boolean	`0` - false `1` - true	Indicates if the button will apply a debounce to reduce false external I/O detections. Applies only when the external I/O mode is configured as Edge Detection or Pulse Detection.	Yes
curr_ext_io	2-bit enum	`00` - Disabled `01` - Edge Detection `10` - Pulse Detection `11` - Temperature Sensor	Indicates the current external I/O mode.	Yes
curr_ul_freq or applied_freq	8-bit unsigned integer	Range: 1–144 `1` - 1 message per day (once every 24 hours) `2` - 2 messages per day (once every 12 hours) `3` - 3 messages per day (once every 8 hours) (etc)	Indicates the interval at which the button will automatically send a Timer message or Heartbeat message.	Yes
curr_nw_standby	4-bit unsigned integer	Range: 0–15 (firmware 3134 only) `0` - Disconnect immediately `1` - Standby for 1 second `2` - Standby for 2 seconds `3` - Standby for 3 seconds (etc)	Indicates how long the button will stay connected to the network in order to send additional messages without reconnecting. Applies only when the operation mode is configured as Alert or Alert + Heartbeat.	Yes
detect_type	8-bit enum	`00000001` - Single short click `00000010` - Double short click `00000100` - Single long click `11000000` - Rising edge `11000001` - Falling edge (others) - Reserved	Indicates the type of click detected from the built-in button, or from the external I/O when configured as Edge Detection or Pulse Detection.	Yes
short_summary_#	8-bit unsigned integer	Range: 0–255	Indicates how many short clicks were detected from the built-in button, or from the external I/O when configured as Pulse Detection.	Yes
long_summary_#	8-bit unsigned integer	Range: 0–255	Indicates how many long clicks were detected from the built-in button, or from the external I/O when configured as Pulse Detection.	Yes
double_summary_#	8-bit unsigned integer	Range: 0–255	Indicates how many double clicks were detected from the built-in button, or from the external I/O when configured as Pulse Detection.	Yes
edge_summary_#	8-bit unsigned integer	Range: 0–255	Indicates how many rising or falling edge events were detected from the external I/O when configured as Edge Detection.	Yes
temp_summary_#	16-bit signed integer	Range: -32,768–32,767	Indicates the temperature measured from an attached Temperature Sensor, in increments of 0.01 degrees (°C).	Yes^*6
temp_cur	16-bit signed integer	Range: -32,768–32,767	Indicates the temperature measured from an attached Temperature Sensor, in increments of 0.01 degrees (°C).	Yes^*6
crc	8-bit checksum	CRC-8 checksum	Used to detect if any data was accidentally changed during transmission.	Yes^*7

^{*5 - Binary Parser will automatically convert the integer value to units of mV.

*6 - Binary Parser will automatically convert the integer value units of degrees (°C).

*7 - Instead of simply decoding the CRC-8 checksum, Binary Parser will verify the checksum and return true or false if the checksum matches.}

Downlink symbols

Symbol	Length/Type	Values	Description	Decoded by Binary Parser
res_type	4-bit enum	`1010` - Server ACK message `1110` - Set Configuration message (others) - Reserved	Indicates the type of response sent by the server.	—
flow_ctrl	8-bit fixed value	`00000001` - Enabled (others) - Reserved	Configures the button to reply with an OOB message.	—
conf_oper	4-bit enum	`0001` - Timer `0010` - Event `0011` - Event + Timer `0100` - Event + Heartbeat `0101` - Alert (firmware 3134 only) `0110` - Alert + Heartbeat (firmware 3134 only) (others) - Reserved	Configures the current operation mode of the button.	—
conf_sync	1-bit boolean	`0` - false `1` - true (firmware 3134 only)	Configures the button to automatically send a Status message once every 24 hours.	—
conf_debounce	1-bit boolean	`0` - false `1` - true	Configures the button to apply a debounce to reduce false external I/O detections. Applies only when the external I/O mode is configured as Edge Detection or Pulse Detection.	—
conf_ext_io	2-bit enum	`00` - Disabled `01` - Edge Detection `10` - Pulse Detection `11` - Temperature Sensor	Configures the external I/O mode.	—
conf_ul_freq	8-bit unsigned integer	Range: 1–144 `1` - 1 message per day (once every 24 hours) `2` - 2 messages per day (once every 12 hours) `3` - 3 messages per day (once every 8 hours) (etc)	Configures the interval at which the button will automatically send a Timer message or Heartbeat message.	—
conf_nw_standby	4-bit unsigned integer	Range: 0–15 (firmware 3134 only) `0` - Disconnect immediately `1` - Standby for 1 second `2` - Standby for 2 seconds `3` - Standby for 3 seconds (etc)	Configures how long the button will stay connected to the network in order to send additional messages without reconnecting. Applies only when the operation mode is configured as Alert or Alert + Heartbeat.	—
crc	8-bit checksum	CRC-8 checksum	Used to detect if any data was accidentally changed during transmission.	—

Checksum algorithm

Each uplink and downlink message includes a CRC-8 checksum (SMBus), which the server and button can use to verify the message contents. The checksum value is calculated from the first byte to (N-1)th bytes.

Initial = 0x00
Polynomial = 0x07 (x⁸ + x² + x + 1)

uint8_t crc_checksum(uint8_t *data, uint32_t len) {
    uint8_t crc = 0x00; uint8_t MSB;
    uint8_t *buf = (uint8_t*) data; int i, j;

    for (i = 0; i < len; i++) {
        crc ^= buf[i];
        for (j = 0; j < 8; j++) {
            MSB = crc & 0x80;
            crc = crc << 1;
            if (MSB) crc ^= 0x07;
        }
    }

    return (crc);
}

Firmware 3134 message formats

Message formats describe the structure of each type of message sent from or to the button.

Uplink messages

The Status message reports the current configuration of the button.

Message is sent when:
- the button is powered on for the first time
- the batteries are replaced after power was depleted
- pressing and holding the built-in button for 10 seconds
- the external I/O mode is configured as Pulse Detection and the external I/O is triggered for 10 seconds
Message length: 14 bytes
Example: 30 00 00 21 01 02 01 01 11 60 00 00 00 66

Byte	Bits
Byte	0	1	2	3	4	5	6	7
1	prod_type Fixed value `001`			f_ack Fixed value `1`	msg_type Fixed value `0000`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3	seq_number 16-bit unsigned integer (range: 0–4,095)
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	fw_ver 16-bit hexadecimal (format: `0x0000`)
6	fw_ver 16-bit hexadecimal (format: `0x0000`)
7	hw_ver 16-bit hexadecimal (format: `0x0000`)
8	hw_ver 16-bit hexadecimal (format: `0x0000`)
9	curr_oper 4-bit binary (see Symbols)				curr_sync Boolean	curr_debounce Boolean	curr_ext_io 2-bit binary (see Symbols)
10	curr_ul_freq 8-bit unsigned integer (range: 1–144; see Symbols)
11	curr_nw_standby 4-bit unsigned integer (range: 0–15; see Symbols)				(reserved)
12	(reserved)
13	(reserved)
14	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0001`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	detect_type 8-bit binary (see Symbols)
6	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0110`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	detect_type 8-bit binary (see Symbols)
6	temp_cur 16-bit signed integer (range: -32,768–32,767; see Symbols)
7
8	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0010`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	applied_freq 8-bit unsigned integer (range: 1–144; see Symbols)
6 \| 10	short_summary_1, short_summary_2, short_summary_3, short_summary_4, short_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
11 \| 15	long_summary_1, long_summary_2, long_summary_3, long_summary_4, long_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
16 \| 20	double_summary_1, double_summary_2, double_summary_3, double_summary_4, double_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
21 \| 25	edge_summary_1, edge_summary_2, edge_summary_3, edge_summary_4, edge_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
26 \| 35	temp_summary_1, temp_summary_2, temp_summary_3, temp_summary_4, temp_summary_5 (5x) 16-bit signed integer (range: -32,768–32,767; see Symbols)
36	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0101`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	detect_type 8-bit binary (see Symbols)
6	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0011`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `0`	msg_type Fixed value `1111`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	crc 8-bit CRC-8 checksum

The Server ACK message should be sent to the button when the server receives an uplink message from the button where the ACK flag f_ack is 1. The Server ACK message indicates to the button that the uplink was successfully received. If the button does not receive the Server ACK message, it will attempt to resend the uplink message. (reserved) sections should be 0-filled.

Message length: 2 bytes
Example: a0 69

Byte	Bits
Byte	0	1	2	3	4	5	6	7
1	res_type Fixed value `1010`				(reserved)
2	crc 8-bit CRC-8 checksum

Byte	Bits
1	res_type Fixed value `1110`	(reserved)
2	flow_ctrl Fixed value `00000001`
3	conf_oper 4-bit binary (see Symbols)	conf_sync Boolean	conf_debounce Boolean	conf_ext_io 2-bit binary (see Symbols)
4	conf_ul_freq 8-bit unsigned integer (range: 1–144; see Symbols)
5	conf_nw_standby 4-bit unsigned integer (range: 0–15; see Symbols)	(reserved)
6 \| 8	(reserved)
9	crc 8-bit CRC-8 checksum

Firmware 2220 message formats

Message formats describe the structure of each type of message sent from or to the button.

Uplink messages

The Status message reports the current configuration of the button.

Message is sent when:
- the button is powered on for the first time
- the batteries are replaced after power was depleted
- pressing and holding the built-in button for 10 seconds
- the external I/O mode is configured as Pulse Detection and the external I/O is triggered for 10 seconds
Message length: 14 bytes
Example: 30 00 00 21 01 02 01 01 11 60 00 00 00 66

Byte	Bits
Byte	0	1	2	3	4	5	6	7
1	prod_type Fixed value `001`			f_ack Fixed value `1`	msg_type Fixed value `0000`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3	seq_number 16-bit unsigned integer (range: 0–4,095)
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	fw_ver 16-bit hexadecimal (format: `0x0000`)
6	fw_ver 16-bit hexadecimal (format: `0x0000`)
7	hw_ver 16-bit hexadecimal (format: `0x0000`)
8	hw_ver 16-bit hexadecimal (format: `0x0000`)
9	curr_oper 4-bit binary (see Symbols)				(reserved)	curr_debounce Boolean	curr_ext_io 2-bit binary (see Symbols)
10	curr_ul_freq 8-bit unsigned integer (range: 1–144; see Symbols)
11 \| 13	(reserved)
14	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0001`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	detect_type 8-bit binary (see Symbols)
5	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0110`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	detect_type 8-bit binary (see Symbols)
5	temp_cur 16-bit signed integer (range: -32,768–32,767; see Symbols)
6
7	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0010`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	applied_freq 8-bit unsigned integer (range: 1–144; see Symbols)
5 \| 9	short_summary_1, short_summary_2, short_summary_3, short_summary_4, short_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
10 \| 14	long_summary_1, long_summary_2, long_summary_3, long_summary_4, long_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
15 \| 19	double_summary_1, double_summary_2, double_summary_3, double_summary_4, double_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
20 \| 24	edge_summary_1, edge_summary_2, edge_summary_3, edge_summary_4, edge_summary_5 (5x) 8-bit unsigned integer (range: 0–255)
25 \| 34	temp_summary_1, temp_summary_2, temp_summary_3, temp_summary_4, temp_summary_5 (5x) 16-bit signed integer (range: -32,768–32,767; see Symbols)
35	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `1`	msg_type Fixed value `0011`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	crc 8-bit CRC-8 checksum

Byte	Bits
1	prod_type Fixed value `001`	f_ack Fixed value `0`	msg_type Fixed value `1111`
2	seq_number 16-bit unsigned integer (range: 0–4,095)
3
4	batt_vol 8-bit unsigned integer (range: 0–255; see Symbols)
5	crc 8-bit CRC-8 checksum

Downlink messages

Server ACK
Set Configuration

Message length: 2 bytes
Example: a0 69

Byte	Bits
Byte	0	1	2	3	4	5	6	7
1	res_type Fixed value `1010`				(reserved)
2	crc 8-bit CRC-8 checksum