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:

  1. Calculate the Message Length Field based on the byte count of the Message Body.
  2. Calculate the Checksum of the concatenated Message Length Field and Message Body fields using CRC-16 CCITT.
  3. 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.

  1. 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

  2. Concatenate the Message Length Field and the Message Body.

    0x00 0x06 0x01 0x02 0x03 0x04 0x05 0x06

  3. Calculate the Checksum (CRC-16 CCITT) for this data.

    To quickly calculate the checksum, you can use sites like https://crccalc.com .

    0x4917

  4. 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

  5. Verify the data arrived at the destination cloud service.

    {
  ...,
  "payloads": "AAYBAgMEBQZJFw==",
  ...
}

  6. 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