Introduction

The IoT Programmable SIM API allows you to build smart cellular-based IoT applications. The API actually consist of a family of APIs that you can use to customize cellular network resources to adapt to any IoT use case. These APIs connect all devices to the JpU HyperCore platform.

For example:

  • Activate and deactivate IoT SIM cards on demand.

  • Isolate and customize communication between IoT devices with vLANs.

  • Create IPSec tunnels for security.

  • Restrict access with firewall rules.

  • Ensure delivery to specific devides with IoT/M2M secured SMS.


Conceptual model

Conceptual model

IoT conceptual model

Definitions


Definitions

The IoT Programmable SIM API use the Internet of Things terminology. It refers to a SIM card as a 'Thing' and to a group of SIM cards sharing the same network configuration as a 'Things Group'. Below are the definitions of the main terms that you need to understand to use the API.

APN

An Access Point (APN) is a gateway between a GSM, GPRS, 3G or 4G mobile network and another computer network, such as the public internet.

IP Profile

The 'IP Profile' is a private network-based firewall module that can be used to protect the IoT devices in the from undesired incoming traffic or restrict access from the devices to specific network destinations.

IPSec VPN

Internet Protocol Security (IPsec) VPN refers to the process of creating and managing VPN connections or services using an IPsec protocol suite. It is a secure means of creating VPN that adds IPsec bundled security features to VPN network packets.

NAT

Network Address Translation (NAT) is a method of remapping one IP address space into another by modifying network address information into Intenet Protocol (IP) datagram packet headers while they are in transit accross a traffic routing device.

Network

A 'Network' is a virtual local network with one or more IP address pools. These pools are assigned to Things when connecting to the network. The Network also includes a routing table used to determine the network routes to external entities. You can define independent NAT port forwarding rules and IPSec VPN tunnels within each Network.

Thing

A 'Thing' represents a SIM card or a device with a SIM card, thus an entity that has internet connectivity through a cellular network. The 'Thing' has many properties that you can use to retrieve detailed network information related to a specific SIM card and configure settings.

Things Group

A 'Things Group' is an entity that allows to tie together all the configuration profiles that define an IoT use case. With this input, the same configuration profiles are easily applied to all the 'Things' in the 'Things Group'.


API workflow

API WorkFlow


Features and constraints

By default, upon shipping, all your Things are provisioned in a default Things Group. The default Things Group is in itself provisioned with a default IP pool, Network and IP profile, to make it easy for you to get started. Although, to avoid preliminary charges, the Things are set to the state of 'PROVISIONED'. Before you can start using the IoT Programmable SIM card, the state needs to be set to 'ACTIVE'.

The default configuration of the firewall is empty, meaning all traffic in the inbound and outbound chain is allowed by default, similarly to any traditional mobile data service. If your IoT device does not recognize the APN automatically, find the APN name in the Network profile. The Things are all configured by default to get an IP address dynamically from the Network IP pool. At the initial stage, the Network profile does not include any NAT or VPN configuration.

Features

  • Isolating use cases with multiple networks: Use this feature to isolate use cases that need different levels of security or network configurations, like IPSec VPNs or different firewall rules. For this you need to create a multitude of Things Groups, Networks and IP Profiles and distribute the Things across different Things Groups.

  • Isolating Things within a network: Use this feature to prevent potential malware from moving from one IoT device to another. Things will only be able to communicate with the back-end application.

  • Restricting mobile services for Things: Use this feature to eliminate potential vulnerabilities by restricting mobile services for specific Things to data or SMS services, for example.

  • Monitoring physical SIM location: Use this feature to identify potentitial physical threats to IoT devices by monitoring changes in SIM card IMEI parameters in the Thing attributes. The IMEI parameters are updated each time the SIM card is used by the IoT device.

  • Locking IP addresses: Use this feature to lock an IP address to a Thing when using NAT port forwarding rules. This way the lease time of this IP addresses will never expire and the Thing will always have the same IP address.

  • Retrieving billing reports: Use this feature to retrieve mobile services charges for your whole account, or specific Things or Things Groups within your account. The report show what your account will be charged at the end of the billing cycle per MB or per SMS.

  • Reporting lost or damaged SIM cards: Use this feature to update the status of your Things. When a SIM is permanently out of service, stop charges to this SIM by setting the status of the Thing to 'RETIRED'. When a SIM card is out of service temporarily, change the Thing state to 'SUSPENDED'. It needs to be set to SUSPENDED during the entire billing cycle to be dismissed from charges.

  • Creating users for your account: Use this feature to create additional users within a same account. Choose the right permission level from the pre-defined settings to grant partial or complete access to the API.

  • Performing bulk actions: Use this feature to invoke the API to perform an action on several Things at once, such as activating all SIM cards. If you are using multiple Things Groups and want to perform and action to many Things across several Things Groups, assign tags to the Things and use the tags to apply bulk actions.

Constraints

  • Account access constraints: A user with administrator rights can create more users for a single account, but it is currently not possible for to create a second account for a user or to create sub-accounts.

  • Mobile services constraints: The mobile services provided by the IoT programmable SIM cards enable consumption of cellular data and exchange of M2M SMS commands. Since the IoT programmable SIM card is not equiped with an addressable mobile phone number, it is not possible to receive phone calls or short messages from a foreign landline or mobile phone. If you require an addressable phone number, you can create a virtual phone number with Nexmo's Phone Number API and assign it to your Things.

  • IP address and IP pool constraints: Your account is pre-configured with one or more IP pools. Each IP pool has a limited amount of IP addresses which are dynamically assigned to the IoT programmable SIM cards that consume data services. If you use multiple Networks, you might reach a limitat when resizing the IP pools. If this is the case, please contact us to request IP pool extensions.

  • APN selection constraints: Your account is loaded with a fixed shared APN which is fragmented to ensure a complete segregation of data between accounts. It is currently not possible to assign or request a different APN. If your IoT device does not automatically detect the serving APN, retrieve the APN name using the Network API.

  • Roaming and coverage constraints: The IoT programmable SIM card can use mobile services in the Netherlands, Belgium and Luxembourg on any of the following network generations: 2G, 3G, 4G, LTE-M. Support of NB-IoT is planned in the future but not yet available on this service.


How to...

Retrieve initial information

Sequence diagram #1

Activate a new IoT SIM card

Sequence diagram #2

Add a firewall filter rule

Sequence diagram #3

Add a NAT port forwarding rule

Sequence diagram #4

Set up an IPSec tunnel for end-to-end encryption

Sequence diagram #5

Send an SMS command to a Thing

Sequence diagram #6


Return codes

Code   Description
200   Success.
201   Created.
202   Accepted.
302   Found. Link in location header.
400   Bad request.
401   Unauthorized.
403   Forbidden.
404   Not found.
405   Method not allowed.
412   Precondition failed.
429   Too many requests.
500   Internal server error.
502   Bad gateway.
503   Service unavailable.