Get Started with Super SIM SMS Commands and the Raspberry Pi

To send or receive messages, first power up the device's cellular module.

1. Check the Waveshare Hat's red NET LED — if it's unlit, press the Hat's PWRKEY button.

2. By default, the Raspberry Pi will boot to the desktop. If it's one you've used before and set to boot to the command line, just run startx to launch the desktop.

3. Select Accessories > Terminal from the Raspberry menu.

4. You'll use a command-line serial console tool called Minicom to communicate with the Hat's cellular module. If you would prefer to use an alternative tool, such as Screen, that's fine, but it may have a slightly different device-selection procedure than the one outlined here. Install Minicom with these two commands:

   Copy code block

   1
   sudo apt update
   2
   sudo apt install minicom -y

5. Enter minicom -D /dev/ttyUSB2 to open a connection to the modem. If Minicom posts an error indicating that /dev/ttyUSB2 is inaccessible, please check your Hat setup.

6. The SIM7600-G module probably isn't set to echo back what you type in, so you won't be able to see your side of the conversation, so type in ATE1 and hit Enter. You'll get an OK back, and when you follow the remaining steps you'll see what you type.

Sending an SMS Command to the device is just a matter of making a POST request to the SMS Commands API endpoint, https://supersim.twilio.com/v1/SmsCommands. You need to provide your command, the SID of the Sim resource representing the Super SIM it's being sent to, and of course your Twilio authorization details.

1. Open a second LX Terminal instance on the Pi, or a terminal on your main machine.

2. Let's say this is the message you want to send to the device:\

   Copy code block

   { "command": "wake", "timestamp": "2021-04-19-15-03-49" }

   It's a command encoded in JSON, though you can use any other textual format and with whatever combination of keys and values that's appropriate for your application. The only restriction is that each Command can contain no more than 160 single-byte characters. You can send this message to your device using the twilio command line tool as follows:\

   Copy code block

   1
   twilio api:supersim:v1:sms-commands:create \
   2
     --sim <YOUR_SIM_NAME_OR_SID> \
   3
     --payload '{"command":"wake","timestamp":"2021-04-19-15-03-49"}'

3. Copy and paste the twilio command to the command line then edit it to fill in the identifier of the Super SIM you're using (you can get this from the Console if you don't have it handy), and your account credentials (also available from the Console). The message is the value of the --payload parameter.

The response, posted to the terminal by twilio, will be something like this:

1
SID                                 Status  Date Created
2
HCxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  queued  Jan 26 2022 16:14:36 GMT+0000

As you can see, the message's status is queued: it's in Twilio's message queue waiting to be sent. When the SMS Command leaves the Twilio Mobile Core for the network the device is attached to, its status will become sent and then delivered when it has been confirmed by the network that the message was delivered. Later on, you'll use a webhook, which you'll set up in the next section, to receive notifications about message status changes as they happen.

You know your test device is connected to the cellular network, but a device in the field might not yet have connected when the message request was sent. If it's a mobile device, it might have briefly passed out of cellular range. Consequently, Twilio will continue to attempt to send each new SMS Command for a period of up to 24 hours. If sending fails, the Command will remain in the queue. After 24 hours, it will be sent again, marked as failed and removed from the queue.

The message you just sent will probably already have arrived on the device, but you can check with an AT command sent to the cellular module. In the terminal running Minicom, enter AT+CSCS="IRA" and hit Enter. This tells the module to display characters in the International Reference Alphabet (IRA). We need this to view the braces in the JSON as they are not part of the standard GSM character set, which is the module's default.

Expand image

Now enter AT+CMGF=1 to set the 7600G's input mode to text, and then enter AT+CMGL="ALL" to list all of the SMS messages held on the device. Among them — or possibly the only one — you should see something like:

1
+CMGL: 0,"REC UNREAD","000",,
2
"21/04/19,15:04:26+00","{"command":"wake","time":"2021-04-19-15-03-49"}"

The first value after the command name (+CMGL:) is 0 here, but it might be a different number if your Super SIM has received other SMS messages before. This is this message's index in the cellular module's message store, and you can use it to read the specific message using it with this command:

AT+CMGR=<message_index>

Of course, a real-world application would handle these AT commands itself by taking directly to the cellular module. It would also parse the command embedded in the message and then perform the required action.

If you're wondering what the "000" in the third parameter of the message listed above is, it's Twilio's SMS Commands number. All SMS Commands your devices receive will have come from this number, which you'll now use to send a message back from the device.

The SMS Commands API provides a specific phone number, 000, to which all SMS messages, from every device are sent. Twilio relays the ones it has received from your SIMs on to you. How does it know exactly where to send them? You specify a webhook address.

Super SIMs are organized into Fleets: groups of SIMs that have common settings, such as which networks they are able to connect to and whether they can make use of cellular data services. Fleets are represented in the Super SIM API by Fleet resources, and SMS Commands adds properties to each Fleet resource in which you can store your SMS Commands webhook address and, optionally, the HTTP method it uses.

So before you can send a message from the device, you need to set up a webhook target URL and add it to your Super SIM's Fleet.

Beeceptor is a handy service for testing webhooks. It's designed for developing and testing APIs of your own, and offers free mock servers — virtual endpoints that can receive webhook calls. Let's set one up to receive messages from the device.

1. In a web browser tab, go to Beeceptor.

2. Enter an endpoint name in the large text field and click Create Endpoint :

   Expand image

3. On the screen that appears next, click on the upper of the two clipboard icons to copy the endpoint URL:

   Expand image

4. Keep the tab open.

Now you update your Super SIM's Fleet to add an SMS Commands webhook. You can do this with the API, but we'll use the Console for this demo.

1. Open a second web browser tab and log into the Twilio Console.

2. Go to IoT > Super SIM > Fleets and select the Fleet containing the Super SIM you are using.

3. Scroll down to SMS Commands Callback URL and paste in your webhook URL from the previous section. By default, webhooks are triggered with a POST request. Leave it unchanged for now, but if you need to use another method for your own application, you can change it later:

   Expand image

4. Click Save .

5. Close the tab if you like.

1. In the LX Terminal instance running Minicom — the one you're using to talk to the 7600G — enter the following command: AT+CMGS="000"
   This tells the module to read in what you're going to type in next and then send it as an SMS message to the number 000.

2. Minicom will now display a > prompt to show you that the 7600G is awaiting some text. Key in a Command — Super SIM says hi, for example — and then hold down the Ctrl key and hit Z . The 7600G will attempt to send the Command, and you'll see a readout of the number of characters sent and OK if it succeeded:

   Expand image

1. Jump back to the Beeceptor tab in the browser. You should see — or will shortly see — the endpoint has received a POST request. Click on it to see the request body, then on the JSON icon, {:} , to view the data more clearly.

2. Look for the line beginning Payload= — right after it is the message you sent:

   Expand image

   
   You'll also see that the Direction parameter now reads from_sim.

The webhook URL you just put in place was set up to receive SMS Commands from the device. You can also use it in a tutorial context for monitoring messages being sent to the device. Using the same technique you applied in the Send messages to the device section, above, but this time add the following extra parameter to the twilio call, adding --callback-url <YOUR_WEBHOOK_URL> with your Beeceptor endpoint to the command:

1
twilio api:supersim:v1:sms-commands:create \
2
  --sim <YOUR_SIM_NAME_OR_SID> \
3
  --payload '{"command":"wake","timestamp":"2021-04-19-15-03-49"}'
4
  --callback-url <YOUR_WEBHOOK_URL>

This time, you'll receive a series of notification messages as the SMS Command's status moves from queued to sent to delivered:

Expand image

You've set up a SImcom 7600G cellular modem to send and receive M2M SMS messages, and you've sent messages to the device and back again, all through Twilio Super SIM's SMS Commands API. You've also used the API's webhook mechanism to keep track of Command delivery.

The next stage, of course, is to build a device-side app that listens for commands, parses them and triggers actions accordingly. You may also want to create a server app that's able to request information from devices: it sends a request command which causes the device to send a second, data-bearing message back. Or you might code up a mobile app that uses SMS Commands to control the device remotely.

We can't wait to see what you build with Super SIM SMS Commands!