Soracom Beam

MQTT Entry Point

This entry point accepts MQTT actions from an Air for Cellular device and forwards the action to an MQTT broker via MQTT or MQTTS. Both publish (from device to broker) and subscribe (receive messages from the broker) are supported.

Versions

When using the Beam MQTT entry point, you may select between version 201509 and 201912.

As of January 2022, MQTT entry point version 201509 has been officially deprecated. While version 201509 can still be selected for use, technical support cannot be provided for it, and it will be removed as an option entirely in the future. For these reasons, Soracom suggests that all new configurations be created using version 201912.

Beam does not support MQTT protocol v5.

Protocol Behavior

Version 201509 is based on MQTT protocol v3.1.1, but with the following limitations:

When using version 201912:

Authentication

When using version 201509, if the client cert option is enabled, Beam will connect to the destination MQTT broker using MQTTS regardless of the configured destination protocol.

On the other hand, when using version 201912, Beam will connect to the destination MQTT broker using the configured destination protocol, regardless of whether the client cert option is enabled.

Billing

Beam is billed according to the number of requests made. When using the MQTT entry point with version 201509, each of the following events is counted as an individual request:

Version 201912 also treats the above events as individual requests, however PINGREQ commands are not counted.

For both versions, Beam fees do not apply for Air for Cellular devices when the corresponding group is attached to a customer VPG.

Configuration

Entry Point

Your device should be configured to publish or subscribe to topics on: beam.soracom.io:1883. The maximum message size of a request is not limited by Beam's MQTT entry points.

Parameters

Multiple Credentials

When the Client cert option is enabled, you can select an X.509 certificate in the Credentials Set parameter that Beam will use for authenticating the connection to your MQTT broker. By default, selecting a single Credentials Set will tell Beam to use the same X.509 certificate credentials no matter which device is connecting to the Beam MQTT entry point.

You can alternatively use a #{imsi} or #{imei} placeholder variable in the Credentials Set parameter. When a device connects to the Beam MQTT entry point, Beam will subtitute the placeholder variable with the subscriber IMSI or device IMEI, and then use the credential set that matches the resulting ID.

For example, by registering the following X.509 certificates:

Then when the Credentials Set parameter is set to device-#{imsi}, Beam will dynamically select the correct credential set when either device connects to the Beam MQTT entry point.

Default Credentials

In some situations, Beam will not be able to find a matching Credentials Set. This may occur because you are using a new SIM or device, and have not yet registered a new set of X.509 certificates that will be used for that subscriber IMSI or device IMEI.

If Beam cannot find a Credentials Set that matches the ID, it will then replace the #{imsi} or #{imei} placeholder variable with the string default and attempt to find a credential set that matches the resulting ID. In the example above, if a device using a SIM with IMSI 295050012345680 connects to the Beam MQTT entry point, Beam will not be able to find any credential sets that match the device-295050012345680 ID, and will instead look for a credential set that matches the device-default ID.

By registering a Default Credential with the ID device-default, you can ensure that devices are still able to securely connect to your MQTT broker. Depending on your MQTT broker, you may choose to enforce specific security policies associated with this default credential, such as limiting devices to requesting provisioning on a specific MQTT topic, and blocking their ability to transmit data until provisioning is complete.

When using the #{imsi} placeholder, Beam will always be able to infer the subscriber IMSI. The default string is used only when a credential set that matches the ID is not found.

On the other hand, when using the #{imei} placeholder, the default string will be used in both of the following situations:

  • The device IMEI is reported from the network, but a matching credential set is not found.
  • The device IMEI is not reported from the network.

Behavior

Publish Example

When publishing a message, our device output looks something like this:

mosquitto_pub -h beam.soracom.io -p 1883 -t mytopic -m message -d
>Client mosqpub/my-device sending CONNECT
>Client mosqpub/my-device received CONNACK
>Client mosqpub/my-device sending PUBLISH (d0, q0, r0, m1, 'mytopic', ... (7 bytes))
>Client mosqpub/my-device sending DISCONNECT

If we inspect the MQTT broker, we should see our message:

>1482290763: New connection from 52.198.245.54 on port 8080.
>1482290763: New client connected from 52.198.245.54 as mosqpub/my-device (c1, k60).
>1482290763: Sending CONNACK to mosqpub/my-device (0, 0)
>1482290767: Received PUBLISH from mosqpub/my-device (d0, q0, r0, m0, 'mytopic/295000012345678', ... (7 bytes))
>1482290767: Received DISCONNECT from mosqpub/my-device
>1482290767: Client mosqpub/my-device disconnected.

In this example, Append IMSI to topic is enabled. When our MQTT broker receives the publish message action, the topic has been updated to include the IMSI of our subscriber.

Subscribe Example

Subscribing to a topic works similarly. Here, we will use two subscribers, with one subscribing to an MQTT topic on our broker, and the other publishing a message on that topic.

On our subscribing device:

mosquitto_sub -h beam.soracom.io -p 1883 -t mytopic -d
>Client mosqsub/my-subscriber sending CONNECT
>Client mosqsub/my-subscriber received CONNACK
>Client mosqsub/my-subscriber sending SUBSCRIBE (Mid: 1, Topic: test, QoS: 0)
>Client mosqsub/my-subscriber received SUBACK
>Subscribed (mid: 1): 0

On our broker, we can confirm that our first device has subscribed:

>1482291094: New connection from 52.198.245.54 on port 8080.
>1482291094: New client connected from 52.198.245.54 as mosqsub/my-subscriber (c1, k60).
>1482291094: Sending CONNACK to mosqsub/my-subscriber (0, 0)
>1482291094: Received SUBSCRIBE from mosqsub/my-subscriber
>1482291094:     mytopic (QoS 0)
>1482291094: mosqsub/my-subscriber 0 mytopic
>1482291094: Sending SUBACK to mosqsub/my-subscriber

When we publish a message from our second device, our MQTT broker should report:

>1482291169: New connection from 127.0.0.1 on port 8080.
>1482291169: New client connected from 127.0.0.1 as mosqpub/my-publisher (c1, k60).
>1482291169: Sending CONNACK to mosqpub/my-publisher (0, 0)
>1482291169: Received PUBLISH from mosqpub/my-publisher (d0, q0, r0, m0, 'mytopic', ... (7 bytes))
>1482291169: Sending PUBLISH to mosqsub/my-subscriber (d0, q0, r0, m0, 'mytopic', ... (7 bytes))
>1482291169: Received DISCONNECT from mosqpub/my-publisher
>1482291169: Client mosqpub/my-publisher disconnected.

And on our first device, we will receive the published message:

>Client mosqsub/my-subscriber received PUBLISH (d0, q0, r0, m0, 'test', ... (7 bytes))
>message

Advanced Configuration

The MQTT entry point can also be configured through the Soracom API or CLI by using the SoracomBeam namespace.

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

Parameters

Sample

[
  {
    "key": "mqtt://beam.soracom.io:1883",
    "value": {
      "name": "AWS IoT",
      "destination": "mqtts://abcd0012345678-ats.iot.us-east-2.amazonaws.com:8883",
      "enabled": true,
      "useClientCert": true,
      "clientCerts": {
        "default": {
          "$credentialsId": "my-device-credentials"
        }
      },
      "addSubscriberHeader": false,
      "replaceTopic": false,
      "version": "201912"
    }
  }
]