SORACOM Developers

Documents

Using USSD to send data to Beam, Funnel, and Harvest.

This guide outlines how to use USSD to send data to Beam, Funnel, and Harvest services.

Introduction

USSD (Unstructured Supplementary Service Data) is a data transfer method available on SORACOM Air’s Global SIM (plan01s and plan01s-LowDataVolume).

Users can send data from their device through USSD, and transfer it using Beam or Funnel, or store it onto Harvest.

USSD supports data transfer through the AT command from a device, and it can also send data by dialing a specially-designated number using a smartphone’s phone app.

It is not necessary to start a data transfer session when using USSD, so users can send data in a hassle-free manner.

Note that one USSD transmission is limited to 160 bytes (182 characters when using GSM 7 bit default alphabet, including service codes for service identification and symbols such as * and # ) and its transfer speed is not very fast, so it is not suited to a transfer of large data.

Also, it currently does not support data transfer initiated by the network side (downlink transmission). (The network side can send back a response to an USSD transmission from the device side.)

Therefore, USSD is suited for occasionally uploading small data from an IoT device.

Supported format

Currently, USSD only supports text transmissions (Data Coding Scheme = 15, GSM 7bit default alphabet)

To send data, use an MMI string in the format: *{Service Code}*{Arbitrary Data}#

Use one of the following three Service Codes :

For Arbitrary Data, characters defined in GSM 7bit default alphabet can be used.

Device preparations

To send data using USSD, users need a device that supports USSD.

Currently we have confirmed that the following devices are supported and can transfer text data (Data Coding Scheme = 15, GSM 7bit default alphabet):

For other devices, please contact the device’s manufacturer. Users can also send data using a regular smartphone’s phone app.

Using Beam to send data to an arbitrary server.

Constructing a server application that receives data through Beam.

Construct a server application that can receive data of Content-Type: application/json using HTTP or HTTPS.

To respond to the transmission, send a response that satisfies the following criteria from the server side to the device side.

In this document, we will use beamtest.soracom.io as a test server that satisfies the criteria above.

Configuring Beam.

Use SORACOM User Console to configure Beam.

  1. Log into SORACOM User Console.
  2. Select Coverage Type: Global.
  3. Select a SIM that you want to send USSD from, and from the [Action] menu, select [Change Group] > [Create a New Group]. (Alternatively, you can allocate it to an existing group.)
  4. Open the configuration screen of the group that you allocated the SIM to in step 3.
  5. Open the column SORACOM Beam, and click [+]. This will open a menu. From the menu, select [USSD → HTTP/HTTPS Endpoint].
  6. This will open a configuration screen. Input an arbitrary name in “Configuration Name,” and set the host of the “Destination” to beamtest.soracom.io, and click the “save” button.

Sending data from a device using USSD.

If you are using an MS2131i-8 or an MS2372h-607:

Connect an MS2131i-8 or an MS2372h-607 to your PC’s USB port, and use a terminal emulator to connect to the serial transmission port. On Windows, use software such as Putty or TeraTermto connect to the COM port of the MS2131-i8 or the MS2372h-607. On Mac or Linux, use screen command to open a device file. The device file should have a name similar to /dev/tty.xxx or /dev/cu.xxx. Once a serial connection is established, execute the following AT command.

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

Line 1 is a command specific to Huawei models, and configures the USSD to send data in accordance to the 3GPP specifications, which is the default mode of data transmission. Line 2 sets the character set to GSM 7 bit default alphabet. Line 3 sends the actual USSD transmission. It includes service code to specify Beam, Funnel, or Harvest.

The first two lines need to be executed only once after you switch on the modem, and Line 3 can be repeated to send data multiple times.

The server side should receive the following JSON string.

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

ussdString represents the exact string specified by the AT command. value represents a string extracted from ussdString by removing the Service Code, etc.

If you are using a Wio 3G SORACOM Edition:

Launch Arduino IDE, and execute the following sketch. (Execute this after updating Wio 3G’s library to the latest version.)

#include <Wio3GforArduino.h>

Wio3G Wio;

void setup() {
  delay(200);

  SerialUSB.begin(115200);
  SerialUSB.println("");
  SerialUSB.println("--- START ---------------------------------------------------");

  SerialUSB.println("### I/O Initialize.");
  Wio.Init();

  SerialUSB.println("### Power supply ON.");
  Wio.PowerSupplyCellular(true);
  delay(500);

  SerialUSB.println("### Turn on or reset.");
  if (!Wio.TurnOnOrReset()) {
    SerialUSB.println("### ERROR! ###");
    return;
  }

  SerialUSB.println("### Registering location.");
  if (!Wio.WaitForCSRegistration()) {
    SerialUSB.println("### ERROR! ###");
    return;
  }

  SerialUSB.println("### Sending USSD.");

  const char* message = "*901011*123#";  // Beam
  //const char* message = "*901021*123# ";  // Funnel
  //const char* message = "*901031*123#";  // Harvest
  char response[256];
  size_t respLen = sizeof(response);

  if (!Wio.SendUSSD(message, response, &respLen)) {
    SerialUSB.println("### ERROR! ###");
    return;
  }

  SerialUSB.print("### Received response: ");
  SerialUSB.println(response);
}

void loop() {
}

By executing this, a response from beamtest.soracom.io should be displayed.

If you are using a UC20 + Mini PCIe EVBKIT:

Use QCOM tool to execute the following AT command.

AT+CUSD=1,"*901011*123#",15

If you are using a smartphone’s phone app:

Launch the phone app, and dial the following number:

*901011*123#

Using Funnel to send data to a cloud service.

Here, we demonstrate how to use Funnel to send data to AWS Kinesis Firehose.

Refer to this document for how to configure AWS Kinesis Firehose and SORACOM Funnel.

After the configuration of AWS Kinesis Firehose and SORACOM Funnel is completed, follow the same procedure as in a transmission through Beam. However, the Service Code must be switched from 901011 to 901021.

Using Harvest to store and visualize data.

To store data onto Harvest, simply open the configuration screen of the SIM’s group, and enable Harvest. (Note that, if Harvest is kept enabled, it will keep incurring a fee of ¥5 per day, so do not forget to disable it after use.

After Harvest is enabled, follow the same procedure as in a transmission through Beam and send data. However, the Service Code must be switched from 901011 to 901031.

Once the data is transmitted, open the Harvest screen.

The values in “value” should be represented on a graph. (One transmission will only display one dot. If that is hard to see, try changing values and sending multiple transmissions.)

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