Skip to main content

Using Twilio Super SIM With The imp006

The imp006 module supports cellular network connections mediated by Twilio’s Super SIM, a global cellular connectivity platform built to connect IoT devices around the world.

To take advantage of the imp006’s cellular capabilities, your product will require a Quectel BG96 modem and a Super SIM either as a physical SIM card inserted into a suitable retainer or as an MFF2 form-factor SIM-on-a-chip.

This short guide will provide you with the information you need to manage the Super SIMs within your products, whatever their form-factor. To learn how to integrate the BG96 and the Super SIM into your product’s hardware design, please see Design Hardware with the imp006.

You can develop your imp006-based connected product’s application code using a variety of tools, but SIM management takes place within impCentral™ web app and the Twilio API, depending on whether you are working with development or production devices, respectively.

Access to impCentral requires your Electric Imp account credentials; access to the Twilio API requires Twilio account credentials.

Super SIM Management During Development

Track Device Group Data Usage: the Dashboard

Electric Imp’s impCentral provides you with a readout of the aggregated data that has flowed between the impCloud and all of the devices within a given Device Group. This information is available from the Device Group’s Dashboard. This view is available in Device Groups of all kinds: Development, Test and Production.

impCentrals device group dashboard

The readout can show either the number of messages passing in (to devices) or out (to the impCloud), or the overall volume in bytes of the data transmitted. A button at the top right of the chart allows you to switch between these two modes. Please note that the data presented is not broken out by connection type. Whether you see WiFi, Cellular or Ethernet data depends on the network type or types that your device uses.

impCentral allows you to monitor data traffic to and from devices

Move the cursor across the chart to view data for specific dates and times. Click on the date field at the top to select a different end date. How many data points the chart will show depends on whether you select Days, Hours or Minutes: the previous 30 days, seven days or 24 hours, respectively. Click the refresh button to update the chart at any time.

The Dashboard also presents a world map pinpointing the approximate location of the group’s devices based on their IP addresses. Click on the World button at the top right of the map to select a US-only view.

impCentral shows where in the world devices connect from

Note Device locations are derived from known relationships between IP address ranges and geography, but some international Internet Service Providers may span their host nation’s IP addresses across multiple territories, so this data can only ever be an approximation.

Monitor Cellular Data Costs: Account Billing

Development devices’ access to cellular networks is mediated by Electric Imp. We strongly urge you to add payment card details to your Electric Imp account to ensure continued cellular service.

There is no contract — you can cancel at any time. You will pay a minimum of $3 monthly per active SIM. Data pricing depends on where your SIM connects: you can find a full list of partner networks and their Super SIM data rates on the Super SIM pricing page. Payment will be taken from your card automatically each month.

Cellular billing for development devices is set up in impCentral. Click on My Account in the topmost toolbar, select Profile from the menu and then click Account Billing in the left-hand panel.

Add a credit card in the impCentral billing area

Now click Link your card and enter your name and your card details when requested. Check the I Agree to Terms of Service box and finally click Link Payment Method.

Three dollars will be charged to your card immediately, and then every 30 days.

impCentral’s Account Billing page will show you how much credit you have left at any given moment and how much data you have used, so that you can easily manage your development cellular data costs.

Super SIM Management In Production

Cellular data consumed by production devices — ie. devices in the field operated by end-users — is not managed for you by Electric Imp. Instead you must enter into a direct relationship with Twilio to purchase Super SIMs for your devices. You will manage the networks those devices are then able to connect to wherever they are installed around the world.

The Twilio Console Super SIM section

You can manage individual Super SIMs in the Twilio Console but for large volumes of SIMs, it’s more efficient to use the Twilio Super SIM API. Twilio provides a wide variety of SDKs which you can use to create your own scripts and tools to help you manage your SIMs, or you can work at the command line using utilities like curl. Whichever of these approaches you take, the resources and data you work with are the same.

Basic SIM Management

Every individual SIM is represented in the Twilio Super SIM API by a resource called a Sim. Sim resources — and therefore Super SIMs — are uniquely identified by their SID (all Twilio API entities have a unique SID). For example, if you request a list of SIMs in your account, you will receive an array of Sim resources.

To simplify SIM management, you organize your SIMs into groups which apply common settings to all of their member SIMs. These groups are represented in the API by Fleet resources. First you create a Fleet resource using the API and then you apply its SID to each Sim that will be part of that fleet.

Fleet settings include any limit you wish to impose on the amount of data a member SIM allows to be transmitted to and from its host device. Another of the settings determined by a SIM’s Fleet is the list of cellular networks the SIM is permitted to use. Super SIMs are able to connect to multiple networks in countries across the world, but in a given territory some networks have higher data costs than others. Setting limits on which networks a SIM can connect to is a powerful factor in controlling your costs.

Each Fleet resource references a Network Access Profile (NAP), a resource which includes a list of networks. You use the Super SIM API to create NAPs and then assign them to Fleets as required.

How you group your SIMs into Fleets is entirely up to you. You may have Fleets for each of your connected products, or for each of the SKUs within a given. You might also maintain separate Fleets for production devices you are using for testing or monitoring so that you can allow these devices a higher data-transfer limit than you allow end-user devices.

Different Fleets can share NAPs — they all reference the same NAP’s SID — but you may prefer that each Fleet has its own NAP. The choice is yours.

The list of cellular networks within a given NAP is an array of Network resources. Each Network resource describes one of the many networks Super SIM can provide access to. You don’t create Network resources, you fetch existing ones by using the industry standard network registration values, MCC and MNC. You then add that resource to an NAP. Now the Sims in any Fleet using that NAP can access that network.

SIM Usage

There is not a 1:1 mapping between a Production Device Group and the Fleet (or Fleets) that the SIMs in those devices are assigned to. Creating a Production Device Group does not automatically create a Fleet — these tasks are separate. As with Development Device Groups, you can view a Production Device Group’s aggregate data use in impCentral by viewing that group’s Dashboard (described above).

The Super SIM API provides a resource called a UsageRecord which provides you with information about a given SIM’s or Fleet’s usage: you provide the API with the SID of the SIM’s Sim resource or its Fleet, and the period for which you require usage information. The API returns a UsageRecord containing the data you want.

You’ll recall that impCentral’s Device Group Dashboard shows all network traffic, whatever the types of network in use. If your product supports multiple network modes, eg. WiFi and cellular, the combination of the Super SIM UsageRecord data and the Dashboard stats can help you determine how often the devices connect with one mode rather than another. This can help you assess whether your application code’s connection strategy is operating as expected.

Get a New Device’s SIM

You install Super SIMs in your factory as part of the device assembly process. You will likely want to record the unique ID of each device you manufacture and that of the SIM it contains. This can be done using the imp API and your Device Under Test (DUT) factory firmware.

Before a device is blessed, call imp.net.info() and locate the cellular entry in the returned data’s interfaces array: look for the array entry (each one is a table) with the value "cell" for the key type. Now extract the value of that table’s iccid key — this is the SIM’s unique ID. Both the device ID, read using hardware.getdeviceid(), and the SIM ICCID can be sent to the DUT’s agent and then relayed to your server.

To get the SIM’s SID, make a call to the Twilio Super SIM API using the recovered ICCID as a URL-encoded parameter. For example:

curl -X GET 'https://supersim.twilio.com/v1/Sims?Iccid=<SIM_ICCID>' \
-u <YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>

The returned JSON contains the key sims; its value is an array containing a single Sim resource representing the SIM identified by the specified ICCID. If the array is empty, the specified ICCID was incorrect or unrecognized.