Soracom Beam

TCP → HTTP/HTTPS Entry Point

This entry point accepts TCP traffic from an Air for Cellular device, encodes the content using Base64, and forwards the data to the forwarding destination as an HTTP request via HTTP or HTTPS, using one TCP segment per request.

Configuration

Entry Point

Your device should be configured to send TCP traffic to: beam.soracom.io:23080.

Parameters

Behavior

Request Behavior

Beam will encode the original message using Base64, and set the encoded content as the body of an HTTP POST request using JSON format.

{"payload": "<Base64-encoded-message>"}

Beam will also set the user agent string as SORACOM Beam in the HTTP request header.

Since the maximum transmission data size per message conforms to the maximum size of the TCP fragment, it is 65,536 bytes including the header.

Response Behavior

Since TCP has no request and response mechanism like HTTP, Beam will return a TCP packet to the device containing the HTTP response code and message received from the forwarding destination. The TCP packet message will use the following format: ${http-status-code} ${http-response-body}

When receiving the HTTP response code is not required, you can enable the Skip status code option in order to reduce data usage.

EoD Bytes

When a device sends data to the TCP to HTTP/HTTPS entry point, Beam converts the data to an HTTP request and sends it to the specified server. Then when a response is received, Beam similarly converts the body of the HTTP response back to a TCP message and returns it to the device. EoD Bytes are added to the end of this response data, which a device can use to determine when the end of the response data. By default, Soracom Beam appends a LF (line feed) character 0x0a to the response data.

You can change or remove the EoD Bytes sequence. This can be helpful for devices that have trouble recognizing the 0x0a LF character, or for situations where you want to use a different byte sequence. The EoD Bytes option can also be combined with the existing "Skip status code" option which will suppress adding the HTTP status code to the beginning of the response data. With both options enabled, response data will be returned to the device as-is without any modification.

Example

$ nc -v beam.soracom.io 23080
>found 0 associations
>found 1 connections:
>     1:    flags=82<CONNECTED,PREFERRED>
>  outif en0
>  src 192.168.43.232 port 51053
>  dst 100.127.65.43 port 23080
>  rank info not available
>  TCP aux info available
>
>Connection to beam.soracom.io port 23080 [tcp/*] succeeded!

Example of TCP response from Beam when HTTP response does not contain a body:

>200

Example of TCP response from Beam when HTTP response contains a body:

>400 Message from server

Advanced Configuration

The TCP → HTTP/HTTPS entry point can also be configured through the Soracom API or CLI by using the SoracomBeam namespace.

Configuration should be performed using tcp://beam.soracom.io:23080 as the configuration key value.

Parameters

Sample

[
  {
    "key":"tcp://beam.soracom.io:23080",
    "value": {
      "name": "telnet2https",
      "destination": "https://beamtest.soracom.io/",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSimIdHeader": true,
      "addMsisdnHeader": true,      
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "addSignature": true,
      "psk": {
        "$credentialsId": "CredentialsID"
      }
    }
  }
]