Groups
Soracom Binary Format v1
By sending multiple packets (technically, TCP segments) that comply with Soracom Binary Format v1 (a format defined by Soracom) to the following entry point, you can transfer up to 65,535 bytes of binary data as a single message to the destination.
If you do not use Soracom Binary Format v1, the data sent via TCP by the device’s application may be split or merged during processing. For more details, refer to Beam TCP → HTTP/HTTPS.
| Entry Point | Configuration Method |
|---|---|
| Beam TCP → HTTP/HTTPS | In the TCP → HTTP/HTTPS entry point settings, turn on Receive data in Soracom Binary Format v1. For more details, refer to Beam TCP → HTTP/HTTPS. |
| Funnel TCP | When enabling Funnel, select any service in the Service dropdown, and choose Soracom Binary Format v1 as the Content type. For more details, refer to Configuration. |
| Funk TCP | When enabling Funk, turn on Receive data in Soracom Binary Format v1. For more details, refer to Configuration. |
| Harvest Data TCP | When enabling Harvest Data, turn on Receive data in Soracom Binary Format v1. For more details, refer to Configuration. |
| Unified Endpoint TCP | In the Unified Endpoint settings, turn on Receive data in Soracom Binary Format v1. For more details, refer to Configuration. |
When using Soracom Binary Format v1, it must be configured for each entry point. For example, if the following settings are applied, Soracom Binary Format v1 will not be available when sending data to the TCP entry point of Unified Endpoint.
- Turn on Receive data in Soracom Binary Format v1 in the Beam TCP → HTTP/HTTPS entry point settings.
- Turn off Receive data in Soracom Binary Format v1 in the Unified Endpoint settings.
Soracom Binary Format v1, the binary parser, and Orbit first process data sent to the entry point. For details on the data processing order, refer to Processing Order of Data Sent to Soracom Entry Points.
Byte structure of Soracom Binary Format v1
| Item | Byte Count | Description |
|---|---|---|
| Message Length Field | 2 bytes | Specifies the number of bytes in the message body. 0x0001 represents 1 byte, and 0xffff represents 65,535 bytes. |
| Message Body | Number of bytes specified in the message length field | The binary data to be sent. |
| Checksum | 2 bytes | Checksum of the concatenated message length field and message body. Calculated according to CRC-16 CCITT. |
Configuration
To begin using the Soracom Binary Format v1, enable the Receive data in Soracom Binary Format v1 option in the Beam TCP → HTTP/HTTPS or Funnel TCP entry points. This will ensure that any data sent to these entry points will be treated as though it is using the Soracom Binary Format v1.
Sending Data in the Soracom Binary Format v1
To send the binary data in compliance with Soracom Binary Format v1 to Soracom Funnel as an example, you will need to:
- Calculate the Message Length Field based on the byte count of the Message Body.
- Calculate the Checksum of the concatenated Message Length Field and Message Body fields using CRC-16 CCITT.
- Concatenate the Message Length Field, Message Body, and Checksum binary data and send it to the Beam TCP → HTTP/HTTPS or Funnel TCP entry point.
Following the steps below, let's take a look at an example of sending the binary data 0x01 0x02 0x03 0x04 0x05 0x06 using the Soracom Binary Format v1 to the Funnel TCP entry point.
-
Determine the value to specify in the Message Length Field.
Since the binary data to be sent is 6 bytes in length, the value is as follows:
0x00 0x06 -
Concatenate the Message Length Field and the Message Body.
0x00 0x06 0x01 0x02 0x03 0x04 0x05 0x06 -
Calculate the Checksum (CRC-16 CCITT) for this data.
To quickly calculate the checksum, you can use sites like https://crccalc.com.
0x4917 -
Concatenate the byte sequence up to this point and send it to either Beam or the Funnel TCP entry point.
echo "00060102030405064917" | xxd -r -p | nc -4 -u funnel.soracom.io 23080 -w 1 >200 -
Verify the data arrived at the destination cloud service.
{ ..., "payloads": "AAYBAgMEBQZJFw==", ... } -
Decode
AAYBAgMEBQZJFw==using Base64 and save it to a file.echo 'AAYBAgMEBQZJFw==' | base64 --decode > received.bin
If the data sent to the Funnel TCP entry point following the above procedure is saved at the destination as received.bin, received.bin will include a Message Length Field (first 2 bytes) and a Checksum (last 2 bytes).
On the other hand, if Beam, Funk, Harvest Data, or Unified Endpoint (including cases where Funnel is used) is utilized, received.bin will not include the Message Length Field (first 2 bytes) or the Checksum (last 2 bytes).
Limitations
- When Soracom receives the first TCP segment, a 10-second timer will start. If the next TCP segment does not arrive within this time, Soracom will send a timeout message to the client and discard the message fragments buffered until that point. This timer is reset with each TCP segment arrival.
- It cannot be used in conjunction with the Binary Parser.
On the other hand, when using Beam, Funk, Harvest Data, or Unified Endpoint (including cases where Funnel is used), the Binary Parser can be utilized.
To bypass restrictions while using Funnel, enable Receive data in Soracom Binary Format v1 in the Unified Endpoint settings and use the TCP entry point of Unified Endpoint. For more details, refer to Unified Endpoint Configuration.