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:

When creating a TCP → HTTP/HTTPS entry point in the User Console, the EoD Bytes (End of Data bytes) field must be left blank. !!! This prevents termination bytes from being appended to the response body. However, this does not mean a default value will be used. For example, if 201509 (Deprecated) is selected as the Platform Version, the End of Data Bytes is not appended.

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.

Configuration

Entry Point

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

Parameters

• Configuration name (string, required) - A string to identify this configuration.
• Destination - The forwarding destination.
  • Protocol (HTTP or HTTPS, required) - The protocol to use for forwarding HTTP requests.
  • Host name (string, required) - The FQDN of the forwarding destination.
  • Port number (number, required) - The port number of the forwarding destination.
  • Path (string, optional) - The URI path to use for forwarding HTTP requests.
• Platform version - Select the platform version to use. See Versions.
• Entry point settings
  • Receive data in Soracom Binary Format v1 - See Soracom Binary Format v1
• Client Certificate - The SSL/TLS client authentication configuration.
  • Use client cert - Enables the use of a client certificate for authentication.
  • Credentials set - The client certificate stored in Credential Sets to use for authentication.
• Header manipulations - Operations to perform on the HTTP request headers.
  • IMSI header - Adds X-Soracom-IMSI: {IMSI} to the HTTP request header.
  • SIM ID header - Adds X-Soracom-SIM-ID: {SIM_ID} to the HTTP request header.
  • MSISDN header - Adds X-Soracom-MSISDN: {MSISDN} to the HTTP request header.
  • IMEI header - Adds X-Soracom-IMEI: {IMEI} to the HTTP request header.
  • Signature header - Adds X-Soracom-Signature: {Signature} to the HTTP request header. This option requires IMSI header or IMEI header to be enabled in order to generate the signature.
  • Pre-Shared Key - The key to use when generating the Signature header.
  • Custom headers - Additional options for adding, modifying, or removing headers from HTTP requests before they are forwarded to the destination.
• Response - Configure response behavior.
  • Skip status code (optional) - When enabled, Beam will not return a status code to the device.
  • EoD Bytes (hexadecimal string, optional) - Changes the End of Data Bytes.

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

To see the processing order when using Binary Parser or Orbit together, refer to Processing Order of Data Sent to Soracom Entry Points.

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 modify or remove the EoD Bytes sequence as needed. This can be useful for devices that have difficulty recognizing the 0x0a (LF) character or when a different termination sequence is required.

If you set EoD Bytes to an empty value, no termination bytes will be added to the response.

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

Example of TCP response from Beam when HTTP response contains a body, and the EoD Bytes value is set to an None. The $ symbol, which is the next shell prompt, appears immediately after the body with no line break.

>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

• key (string, required) - tcp://beam.soracom.io:23080
• value (object, required) - The configuration parameters.
  • name (string, optional) - Name to identify this configuration.
  • destination (string, required) - URL of the forwarding destination.
  • enabled (boolean, required) - Enables or disables the configuration.
  • useClientCert (boolean, optional) - Enables or disables the use of an SSL/TLS client certificate for authentication.
  • clientCerts (object, optional) - The SSL/TLS client certificates to attach.
    • $credentialsId (string, optional) - ID of the credential set with the appropriate client certificate.
  • version (string, optional) - Defines the Beam platform version to use. If not defined platform version 202411 will be used.
  • addSubscriberHeader - (boolean, optional) - Enables or disables adding the subscriber IMSI as an HTTP header in the forwarded request.
  • addSimIdHeader - (boolean, optional) - Enables or disables adding the SIM ID as an HTTP header in the forwarded request.
  • addMsisdnHeader - (boolean, optional) - Enables or disables adding the SIM MSISDN as an HTTP header in the forwarded request.
  • addEquipmentHeader - (boolean, optional) - Enables or disables adding the IMEI as an HTTP header in the forwarded request.
  • customHeaders (object, optional) - Defines custom headers behavior. Each custom header is defined using:
    • X-Header-Name (string, required) - Name of the custom header.
      • action (string, required) - Defines the header behavior using one of the following values:
        • append - Appends the defined header to the HTTP request.
        • replace - Replaces any existing header with the defined header value.
        • delete - Deletes the header from the HTTP request.
      • headerKey (string, required) - The header name.
      • headerValue (string, required) - The header value.
  • addSignature (boolean, required) - Enables or disables adding a signature header for subscriber verification.
  • skipStatusCode (boolean, optional) - Whether to include the HTTP status code in the response.
  • eodBytes (string, optional) – One or more bytes appended to the end of the response to indicate the end of the data. Set to an empty string ("") to omit EoD Bytes entirely. If this option is omitted, the default End of Data Bytes response will be used.
  • psk.$credentialsId (string, optional) - The ID assigned to the pre-shared key credential set. Used for signing when addSignature is set as true. This ID is set when the credential is registered in the Credentials Store.
  • useSoracomBinaryFormat - (boolean, optional) - Enables or disables Soracom Binary Format v1, which is available when the device sends the binary data via TCP.

To see the processing order when using Binary Parser or Orbit together, refer to Processing Order of Data Sent to Soracom Entry Points.

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"
      },
      "useSoracomBinaryFormat": false
    }
  }
]