Soracom Air for Cellular

Sending Data with SMS & USSD

Most Soracom IoT SIMs support SMS (Short Message Service) and USSD (Unstructured Supplementary Service Data), allowing for data transmission and actions such as restarting a device via SMS or periodically sending diagnostic data without needing to establish a network data session.

Compatibility

The following tables outline Soracom IoT SIM SMS and USSD support by Coverage Type:

^{*1 - MT (Mobile Terminated) SMS refers to delivering an SMS to the SIM card from the User Console, Soracom API, Soracom CLI, or another device. Subject to limitations.
*2 - MO (Mobile Originated) SMS refers to sending an SMS from a SIM to a Soracom service or to another device. Subject to limitations.}

Service Codes

By using Soracom IoT SIMs, you can also extend SMS / USSD functionality with Soracom Beam, Funnel, and Funk (to forward SMS/USSD data over HTTPS, MQTTS, TCP, or to cloud services), and also Harvest Data (to store and visualize data directly on Soracom).

When sending an SMS or USSD, simply specify one of the following service codes where you would normally specify a phone number:

• 901001 - Unified Endpoint
• 901011 - Soracom Beam
• 901021 - Soracom Funnel
• 901031 - Soracom Harvest Data
• 901041 - Soracom Funk

Beam, Funnel, Funk, and Harvest Data will then take the data or body of the message, and forward or store it based on their respective configurations.

Configuration

When sending an SMS or USSD message from your device to Beam, Funnel, Funk, Harvest Data, or any of the above with Unified Endpoint, you must also configure the following:

1. Create a Group
2. Configure the Group to enable Beam, Funnel, Funk, or Harvest Data, with appropriate settings
3. Add your IoT SIM to the Group

Once the Group configuration is complete, SMS and USSD messages sent from your device will be sent to the respective service.

SMS Usage Overview

Similar to typical SMS usage on mobile phones, SMS is bi-directional and can be used both to send messages to a device, as well as sending data from a device to another device or data endpoint.

Requirements

With the ubiquity of SMS-capable devices, there is generally no special requirement needed. However, keep the following in mind:

• Your device is configured to enable roaming
• Your device is compatible with the cellular radio frequencies available in the country of use
• Your device is within cellular range

Limitations

For security, SMS sending and receiving is limited to the following conditions:

• Sending SMS from the User Console, Soracom API, or Soracom CLI to an IoT SIM.
• Sending SMS from one IoT SIM to another IoT SIM. ^*1
• Sending SMS from an IoT SIM to Soracom Beam, Funnel, Funk, or Harvest Data.

^{*1 - When sending SMS from one IoT SIM to another, both IoT SIMs must be registered to the same Operator}

SMS Failure

If your device is not connected to the network when the SMS is sent, SMS delivery may fail. SMS messages are usually stored by the network for a limited time; however, the exact duration varies by carrier.

If SMS delivery fails Soracom will attempt to resend the SMS at the following progressively longer intervals:

1. 20 attempts to retransmit at 2-minute intervals (40 minutes total).
2. 20 attempts to retransmit at 15-minute intervals (300 minutes).
3. 20 attempts to retransmit at 1-hour intervals (20 hours).

If the SMS is not reported as delivered by the time the retries are completed, Soracom will stop attempting delivery and the SMS will have to be resent.

Sending SMS to a Device

Soracom provides several ways to send SMS to your IoT SIM device. The simplest method is with the User Console; however, the Soracom API allows programmatic usage for integration with applications, and the Soracom CLI allows quick sending from any terminal.

From the User Console

1. Login to the User Console. From the Menu, open the SIM Management screen.

2. From the list of subscribers, click the for the SIM you want to send an SMS to.

3. Click the Actions menu, then select Send SMS.

   https://console.soracom.io

   

4. Select the Encoding for the message and enter the SMS content, then click Send SMS.

   

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "payload": "Hello world!",
>        "encodingType": 1
>      }' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/send_sms

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "payload": "Hello world!",
>        "encodingType": 1
>      }' \
>  https://jp.api.soracom.io/v1/subscribers/<IMSI>/send_sms

curl -X POST \
>  ...
>  https://g.api.soracom.io/v1/subscribers/msisdn/<MSISDN>/send_sms

curl -X POST \
>  ...
>  https://jp.api.soracom.io/v1/subscribers/msisdn/<MSISDN>/send_sms

{
  "payload": "74657374",
  "encodingType": 1
}

soracom subscribers send-sms --imsi <IMSI> --payload "Hello world!" --coverage-type g

soracom subscribers send-sms --imsi <IMSI> --payload "Hello world!" --coverage-type jp

soracom subscribers send-sms-by-msisdn --msisdn <MSISDN> --payload "Hello world!" --coverage-type g

soracom subscribers send-sms-by-msisdn --msisdn <MSISDN> --payload "Hello world!" --coverage-type jp

Sending SMS from a Device

The method for sending an SMS will vary depending on the type of device. Regardless of the type of device and method for sending SMS, you will need to know the destination address, which must be one of the following:

• 901001 - Unified Endpoint
• 901011 - Soracom Beam
• 901021 - Soracom Funnel
• 901031 - Soracom Harvest Data
• 901041 - Soracom Funk
• MSISDN of another Soracom IoT SIM device in your account

In addition to the destination address, you may need to manually set the encoding type for your content, so that the content is transmitted correctly. The maximum length of the content may vary depending on the encoding type.

From a Smartphone

To send the value 123 to Harvest Data, simply launch the messaging app and send a message containin 123 to the service code 901031.

From a Modem using AT Commands

When interacting directly with a modem, you can connect to the modem's serial interface and send AT commands to send an SMS.

• On Windows, you can use PuTTy or TeraTerm to connect to the COM port of the modem
• On Mac and Linux, you can use screen to connect to the /dev/ttyXXX serial interface of the modem

Once connected, we can send the following AT commands:

• Use the AT+CMGF= command to configure the modem to use text format:

  AT+CMGF=1
  <OK
  <
  AT+CMGS="901031"
  <>123 <Ctrl+Z or Esc>
  <OK

• Then, use the AT+CMGS= command to start the send SMS message command.

  AT+CMGS="901031"
  <>123 <Ctrl+Z or Esc>
  <OK

  The modem will accept input for the SMS content. Once we have entered our content, we need to send a control code to tell the modem that we have finished entering the content. Typically, pressing Ctrl+Z or Esc will complete the send SMS command.

The above commands works well for many typical modems, however in some instances, the modem may return CMS ERROR along with an error code. The modem manufacturer's AT command manual will usually explain the meaning of each error code.

If an error is due to using an incorrect encoding type, you can use the AT+CSCS= command to change it:

AT+CSCS="GSM"
<OK

Then we can run the AT+CMGF= and AT+CMGS= commands above to send an SMS.

From an Arduino Device

GSM libraries are usually available for several kinds of devices and allow you to send SMS without directly entering AT commands. For example, the Wio LTE microcontroller can be used with the Wio LTE for Arduino library, which includes a command for sending an SMS. All we need to provide is the SMS destination address and message to send:

#include <WioLTEforArduino.h>

WioLTE Wio;

void setup() {
  delay(200);

  Wio.Init();
  Wio.PowerSupplyLTE(true);
  delay(500);

  Wio.TurnOnOrReset();
  delay(3000);

  Wio.SendSMS("901031", "123");
}

void loop() {

}

You can find the full code example, which includes basic error handling, from the Wio LTE for Ardunio library within Arduino IDE Library Manager.

USSD Usage Overview

USSD allows similar functionality as SMS, however messages can only be sent from a device to the network, and must be sent while the device is connected to the network. USSD is best suited when you only need to occasionally upload small amounts of data from your device.

Requirements

Sending USSD requires a device that supports USSD.

Soracom has tested and confirmed a number of devices that support USSD, including:

• Huawei MS2131i-8 3G USB modem
• Huawei MS2372h-607 3G/LTE USB modem
• Wio3G Soracom Edition
• Quectel UC20 modem (with Evaluation Board kit)
• Quectel UG96 modem (with Evaluation Board kit)

If your device is not listed, please check the device manual or contact the device manufacturer to confirm USSD capability.

Appended Data

When USSD is used to send data to Beam or Funnel, the data is cast into a JSON object before it is sent to the destination endpoint, in order to provide additional information about the USSD data.

For example, when we send a USSD message with the following AT command:

AT+CUSD=1,"*901031*123#",15
<OK

Soracom Beam or Funnel will receive the data and send the following JSON payload to our endpoint:

{
  "imsi": "295000012345678",
  "ussdDataCodingScheme": 15,
  "ussdString": "*901011*123#",
  "value": "123"
}

In addition to our value 123, we will receive the imsi which we can use for handling the data on our endpoint, and we will also receive the ussdString which we can use to inspect the message for errors.

Limitations

Currently, USSD can only be used with an IoT SIM to send data from a device, and is limited to the following conditions:

• Only for sending data from an IoT SIM to Soracom Beam, Funnel, Funk, or Harvest Data
• Must use GSM 7-bit default alphabet encoding type
• Limited to 182 characters in length

Additionally, the transfer speed is relatively slow, so it is not suited for sending large amounts of data.

Sending USSD from a Device

Sending a USSD message is typically done by sending AT commands to a modem, or by dialing a specially-designated number using a device's dialer interface.

Regardless of device, USSD messages use the following format: *{service code}*{data}#, where:

• {service code} is one of the following options:
  • 901001 - Unified Endpoint
  • 901011 - Soracom Beam
  • 901021 - Soracom Funnel
  • 901031 - Soracom Harvest Data
  • 901041 - Soracom Funk
• {data} - any number of characters defined in GSM 7-bit default alphabet

From a Smartphone

To send the value 123 to Harvest Data (service code 901031), simply launch the dialer and dial the following code:

*901031*123#

From a Modem using AT Commands

When interacting directly with a modem, you can connect to the modem's serial interface and send AT commands to send a USSD message.

• On Windows, you can use PuTTy or TeraTerm to connect to the COM port of the modem
• On Mac and Linux, you can use screen to connect to the /dev/ttyXXX serial interface of the modem

Once connected, we can send the following AT commands:

• Use the AT+CUSD= command to send a USSD message:

  AT+CUSD=1,"*901031*123#",15
  <OK

This command works for standard modems such as the Quectel UC20 and UC96, however some device manufacturers initialize their modems with different configurations. For the Huawei MS2131i-8 and MS2372h-607, we also need to run AT^USSDMODE and AT+CSCS= to make sure the USSD mode and character set is configured correctly, respectively:

AT^USSDMODE=0
<OK
AT+CSCS="GSM"
<OK
AT+CUSD=1,"*901031*123#",15
<OK

From an Arduino Device

GSM libraries are usually available for several kinds of devices and allow you to send USSD without directly entering AT commands. For example, the Wio 3G Soracom Edition microcontroller can be used with the Wio cell lib for Arduino library, which includes a command for sending a USSD. All we need to provide is the USSD message to send:

#include <WioCellLibforArduino.h>

WioCellular Wio;

void setup() {
  delay(200);

  SerialUSB.begin(115200);
  Wio.Init();
  Wio.PowerSupplyCellular(true);
  delay(500);

  Wio.TurnOnOrReset();
  Wio.WaitForCSRegistration();

  const char* message = "*901031*123#"; // USSD message
  char response[256];
  Wio.SendUSSD(message, response, sizeof (response));

  SerialUSB.println(response);
}

void loop() {

}

You can find the full code example, which includes basic error handling, from the Wio cell lib for Ardunio library within Arduino IDE Library Manager.

Testing

Since the Harvest Data service captures data without requiring any configuration, you can use it to quickly perform SMS and USSD connectivity tests. Enable the Harvest Data service in your Group configuration, then send an SMS or USSD to the 901031 service code.

If the send is successful, the transmitted data will be stored in Harvest Data. To view the data, open the User Console and select the next to the IoT SIM, then click the Actions menu and select Harvest Data. The test data will appear in the logs below.