Groups
Soracom Binary Format v1
This feature is currently available as a Public Beta.
Using the Soracom Binary Format v1, you can transfer up to 65,535 bytes of binary data as a single message by sending multiple packets (specifically TCP segments) in the following format to Beam TCP → HTTP/HTTPS or Funnel TCP entry points.
| 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, 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
The saved received.bin file will also include the Message Length Field (first 2 bytes) and the Checksum (last 2 bytes).
Limitations
- While this feature is in Public Beta, specifications and behavior may change without notice.
- 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. When the Binary Parser is used, the data is processed in JSON format.
- It cannot be used with the Unified Endpoint. If binary data compliant with the Soracom Binary Format v1 is sent to the Unified Endpoint, it will not be processed as Soracom Binary Format v1 compliant data.