SORACOM Developers

Getting Started

Using SORACOM Beam to safely send data

SORACOM Beam is a service designed to offset the load associated with encryption, advanced processing, and connection settings from IoT devices onto the cloud.

Using SORACOM Beam also enables you to ship SIMs set to send data to a fixed address, then have end users change the destination themselves after receiving the SIM. Other usage cases include wanting to use HTTPS for greater security, but lacking the resources on the IoT device in question to achieve that. By offloading encryption to the cloud, these processes become possible.

For example, you can use this functionality with sensor devices containing multiple Air SIMs and send data over MQTT, use SORACOM Beam to encrypt with MQTT, or send data to a specific MQTT broker.

Beam explained

For a more detailed explanation, please seehttps://www.soracom.io/products/beam/

SORACOM offers a sandbox server that allows you to test the functionality of the service. In this section, we describe how to use the server to configure SORACOM Beam. Below are examples using TCP/SSL and HTTP/HTTPS.

On Beam, settings are configured on a group basis, so you must first create and configure groups for your Air SIMs.

Air SIM group creation and setup

SORACOM Beam requires that you configure Air SIMs on a group basis. You must first assign those Air SIMs to some sort of group. In this example, we create a dedicated group used for testing the SORACOM Beam functionality and assign SIMs to it. To create a group and assign SIMs, take the following steps. First open the Air SIM administration page and select the Air SIM you want to communicate with SORACOM Beam with. Click the Execute button, then select Change Assigned Group.

Changing groups

A dialog asking you to select the group with which the Air SIM is associated will appear. From the [New Group] dropdown, select [Create New Group…]

New groups

A group creation dialog like that seen below will appear. Enter the group name and click the Create Group button. In this example, we crete a group with the name “hello beam.”

Creating groups

Pressing the Create Group button will take you back to the Change SIM Group dialog. A dropbox indicating New Group will appear; confirm that this is set to the newly-created “hello beam” group and click the Change Group button.

Changing groups

TCP/SSL

Devices connect to the Beam entry point via a VPN, so even plain text is transmitted securely. Communication from Beam externally is conducted over SSL, so it is encrypted, and the load of encryption is not borne by the device. SORACOM offers a demo echo server at tcps://beamtest.soracom.io:1234. Access this server to test SORACOM Beam.

tcp/SSL summary

We now configure SORACOM Beam settings for the previously created “hello beam” group. Open the group administration page and select the “hello beam” group, then proceed to the group details page.

Group details

Click the + ▼ button within the SORACOM Beam Settings group. A dropdown menu will appear, allowing you to select the entry point you desire. In this example, we select TCP Entry Point.

tcp_entry point

A dialog will appear; configure the settings as per below and click the Save button.

Paramater Value
Configuration name echo over ssl
Destination - Protocol TCP(SSL)
Destination - Host name beamtest.soracom.io
Destination - Port Number 1234
Optional IMSI header ON

tcp_entry

The values for TCP Entry Point are explained below:

Parameter meaning required
Configuration name the name given to this TCP Entry Point setting
Choose a simple name.
Yes
Entry point protocol Select the protocol used to connect to this entry point from the SIM. Yes
Entry point host name The host name used to connect to the entry point from the SIM.
Currently, only beam.soracom.io is available.
Yes
Entry point port number The port number used to connect to the entry point from the SIM.
Currently only 8023 is supported.
Yes
Destination protocol Select the protocol used to connect from SORACOM to the destination.
You can select either TCP or TCP (SSL).
Yes
Destination host name The host name used to connect from SORACOM to the destination. Yes
Destination port number. The port number used to connect from SORACOm to the destionation. Yes
Optional ISMI headers When connecting from SORACOM to the destination, “imsi=IMSI number” will be displayed.
Optional IMEI headers When connecting from SORACOM to the destination, “imei=IMEI number” will be displayed.
Optional signature headers Creates a digest value with SHA256 based on the IMSI, IMEI, and time stamp found in the connection headers and public key.
Optional public key Enter an optional string that is appended to the signature headers.

Confirm on device

When connecting over telnet on an Air SIM connected device to the entry point specified above and using Beam, the IMSI data will be displayed. You can use a telnet app when connecting with an Android smartphone to test this.

telnet connection

android

You can also connect over telnet on Raspberry Pi or other devices. When you type a string on the telnet keyboard, the echo server will echo it back.

pi@raspberrypi:~$ telnet beam.soracom.io 8023
Trying 169.128.169.128...
Connected to beam.soracom.io.
Escape character is '^]'.
Hello Soracom Beam Client IMSI:4XXXXXXXXXXXXXX !
hi        (<- typing in keyboard)
hi        (<- echo back)

If the line is echoed back correctly, setup is complete.
If you are not connected to SORACOM Air via WiFi or another means, confirm that the line is not echoed back.

HTTP/HTTPS

A test server is also available for HTTP Entry Point testing. Access it at https://beamtest.soracom.io.

android

When accessing the above page from a web browser on a desktop or smartphone, the system will be unable to capture that device’s IMSI, so it will print, “Hello Unknown Client…” Configure the settings such that when using Beam to connect via SORACOM Air, IMSI data is properly shown.

From the group settings page, click the + on the bottom left and add an HTTP entry point.

android

The settings dialog will display. Enter the requisite information as per below and click the Save button. Custom headers are described in the next section; you can leave them blank for now.

Parameter Value
Configuration name http over ssl
Entry point - Protocol HTTP
Entry point - Path /
Destination - Protocol HTTPS
Destination - Host name beamtest.soracom.io
Destination - Path /
Optional IMSI header ON
Custom header N/A

android

Use the browser on a SORACOM Air-enabled smartphone or other device to access the URL at http://beam.soracom.io:8888. The IMSI headers for that HTTP connection will be displayed.

“Hello SORACOM Beam Client xxxxxxxxxxxxxxx !”

If IMSI headers are disabled, the response will be like that when connecting over the Internet, indicating that the accessing client is unknown (“Hello Unknown Client…” ).

Setting custom headers

You can set and delete custom headers used during forwarding.

Headers begin with “X-”. From the SORACOM Beam settings index, click the … button on the far right of the “http over ssl” line previously added to open a settings dialogue. Fill in the requisite information and click the Save button. To add custom headers, click the + button on the bottom left of the Manipulate Headers area.

android

From a SORACOM Air-enabled smartphone or other device, point the browser to http://beam.soracom.io:8888 to display the newly-added HTTP headers.

“HTTPXSORACOMBEAM=SUCCESS
HTTP
XSORACOMIMSI=4XXXXXXXXXXXXXX”

This concludes the section on safely transmitting data with SORACOM Beam. With SORACOM Beam, protocol conversions like data encryption are performed not on IoT devices, but with cloud resources on the SORACOM platform, and the results can be forward to a specified server.

Getting Started

SORACOM Air for Cellular

SORACOM Air for Sigfox

SORACOM Beam

SORACOM Canal/Direct/Door

SORACOM Endorse

SORACOM Funnel

SORACOM Gate

SORACOM Harvest

SORACOM Inventory

SORACOM Junction

SORACOM Krypton

SORACOM Lagoon

Service Detail

Developer Tools

pagetop