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.

Data sent by the device's application over TCP may be split or combined when converted to HTTP/HTTPS requests.

TCP divides data into segments for transmission, and at the TCP → HTTP/HTTPS entry point, these segments may be combined or split before being sent to the server. This means the data might not be transferred in the same way it was sent by the application. For example:

  1. A single piece of data may be split into multiple HTTP/HTTPS requests.
  2. Multiple pieces of data may be combined into a single HTTP/HTTPS request.

Be aware that data may be split or combined during transfer. If this is a concern, consider using Soracom Binary Format v1 or the HTTP entry point.

Data is only combined within the same TCP connection, not across different connections.

Versions

When using the Beam TCP → HTTP/HTTPS entry point, you may select between version 201509 and 202411. The differences between these versions are as follows.

Unified Endpoint Behavior

The Unified Endpoint behavior does not change based on the Platform Version selected for the TCP → HTTP/HTTPS entry point. If Unified Endpoint's Response Format is set to Soracom Beam, it will always operate based on Platform Version 202411.

The same behavior applies when the Response Format of Unified Endpoint is set to Auto (default) and only Soracom Beam is enabled in the group settings.

Default End of Data Bytes Response

The default End of Data (EoD) bytes returned will change based on the platform version selected:

Platform Version Default EoD Bytes Returned
202411 None
201509 0x0a (Line feed)

Error Responses

If the destination server returns an HTTP status code of 400 or higher, the TCP → HTTP/HTTPS entry point considers it an error response. In such cases, the response is transmitted to the device as the payload of a TCP packet, formatted according to the specifications defined by the platform version. As opposed to platform version 201509, platform version 202411 adds the body of the HTTP response and omits the forwarding URL from the error response.

Platform Version Default Error Response Format
202411 ${HTTP status code} ${HTTP response body returned by the destination server}${byte sequence specified in EoD Bytes}
201509 ${HTTP status code} ${destination URL} returns a status code (${HTTP status code}). Please check your destination.\r\n

Configuration

Entry Point

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

Parameters

For details on configuring and using header manipulations, refer to the Header Manipulation page.

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.

Transmission messages are limited to 65,536 bytes including the header(s), as this is the maximum size of a TCP window.

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.

End of Data 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. End of Data (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.

You can also change or remove the EoD Bytes sequence, which 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.

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,
      "version": "202411",
      "addSubscriberHeader": true,
      "addSimIdHeader": true,
      "addMsisdnHeader": true,      
      "customHeaders": {
        "X-GROUP-NAME": {
          "action": "append",
          "headerKey": "X-GROUP-NAME",
          "headerValue": "TEST"
        }
      },
      "addSignature": true,
      "psk": {
        "$credentialsId": "CredentialsID"
      }
    }
  }
]