What is SIMSY?

SIMSY provides cellular connectivity. It has been designed for IoT and other data-centric applications.

Our platform has been built for innovators, developers and anyone else who needs flexible, reliable and secure connectivity which can be precisely configured for their applications and devices. Whereas ordinary networks provide a service - giving limited control and insight into their configuration and performance, our network is designed as a platform - for you to build-on.

To use the SIMSY network and platform, you need a SIM card - available directly from us, or via one of our distribution partners. Once inserted into a suitable device, and linked with your account, you can immediately control and monitor all aspects of behaviour in real time - just as if you had your own mobile network.

SIMSY SIM cards work wherever we have coverage through our network of partners. We have coverage on over 600 networks in over 200 countries and territories worldwide. Depending on their location, our SIM cards work on 2G, 3G, 4G and 5G networks - and most of our advanced capabilities will work in the same way.

Everything is controllable via our rich API, or using our management portal which we have built using this API. If you are familiar with using cloud platforms for deploying, configuring, managing and monitoring virtual servers, infrastructure and services then you'll feel right at home using SIMSY to do the same for your own programmable mobile network.

Key Concepts

The SIMSY platform, API and portal is based around a number of key concepts - which together are used to configure the network to meet the needs of the application.

• A single customer account can contain multiple VSlices.
• VSlices contain Endpoint Groups, Routing Policies and Routing Targets. Each Endpoint Group can refer to a single Routing Policy, but a Routing Policy can be shared by multiple Endpoint Groups (in the same VSlice).
• Event Maps and Operator Policies are independent of any particular VSlice, so they can be shared by Endpoint Groups in different VSlices.

VSlice

A VSlice is an independent mobile network - used to segregate your estate of devices into logical networks. If you are familiar with public cloud environments, this is similar to a VPC (AWS) or a VNet (Azure). You might create a VSlice for each project, site, team or environment - whatever makes sense for your application.

For example, as a provider of digital signage, you might create a VSlice for each site or building, and another for testing purposes.

IP Subnets

When creating a VSlice (via the portal or API), you will also need to create one or more IP Subnets which are used to assign IP addresses to endpoints. IP Subnets can be 'static' or 'pooled'.

If you are unsure what IP address range to use, we recommend using 100.64.0.0/10. Only IPv4 addresses are supported at present - please contact support if you would like to use IPv6.

Note that the IP subnets assigned to different VSlices can be the same, or can overlap. This is because VSlices are independent networks which are isolated from each other. Even if you assign the same IP subnet to multiple VSlices, this will not ordinarily allow endpoints within the two VSlices to communicate with each other.

VSlices contain Endpoint Groups (as many as are required), which are used to contain Endpoints (SIMs) with similar requirements or configuration.

As with most objects in the SIMSY platform, when creating a VSlice you specify a Name and a Moniker. The Moniker identifies the object when using the API - whereas the Name identifies it for humans. Before changing a Moniker, consider the implications for any systems which use the API.

Endpoint Group

An Endpoint Group is a container for Endpoints. Endpoint Groups are where configuration is specified, which then applies to every Endpoint which it contains. Endpoints are created within a VSlice - so each endpoint in the group is also implicitly within the VSlice.

For a digital signage provider, you might create an Endpoint Group for Media Players, another for Digital Kiosks etc.

The configuration of an Endpoint Group specifies:

• Routing Policy - controlling the flow of data between endpoints and external networks
• Event Map - controlling notifications generated as a result of endpoint behavior
• Operator Policy - defining the countries and networks where the endpoints can be used

Endpoint

An Endpoint represents a SIM card. It is created in the platform when you activate a SIM card you have received. To activate a new SIM card and create an Endpoint, you will need the ICCID number and Activation Code which is printed on the SIM (or supplied with it).

An Endpoint is not useable until it has been assigned to an Endpoint Group, which has been configured appropriately. Once an Endpoint is assigned to a group, it is implicitly part of the Vslice where the group was created, and will be assigned an IP address from the subnet on the Vslice. This happens automatically if not configured otherwise.

For a digital signage installation, an endpoint might be a media player or a digital kiosk.

Endpoint States

Operator Policy

An Operator Policy contains a set of rules or preferences which controls the countries and networks which can be used. A single Operator Policy is selected for each Endpoint Group - which then applies to all Endpoints within the group. Operator policies aren't mandatory - if an operator policy is not selected for a group, the contained endpoints will be able to connect to any available network.

Operator Policies can contain rules at one of three levels:

• Global - allows a default behaviour to be defined, which applies to all networks and countries if not configured otherwise. The global behaviour can be 'Allow' or 'Reject'.
• Country - allows the Global behaviour to be overridden for particular countries. This can be 'Inherit' (rely on the Global configuration), 'Allow', or 'Reject'.
• Operator - allows the Country and Global behaviour to be overridden for particular operators. This can be 'Inherit' (rely on the Country and/or Global configuration), 'Allow', 'Reject' or 'Fallback'. If configured as 'Fallback', the Endpoint will be allowed to attach to the selected network if it appears that it is out of coverage for any 'Allowed' networks.

Once you have created an Operator Policy, it needs to be selected on the Endpoint Groups you want it to apply to. An Operator Policy not associated with any group won't have any effect.

Note that changes to the operator policy do not immediately affect Endpoints which are already connected to the network. The next time the check in with the network (usually every few hours), the new policy will be applied.

For the full list of where SIMSY SIMs can be used, ask to see our coverage.

Routing Target

A routing target is an external network which your endpoints can communicate with, or vice versa. The most common external network is the Internet - so if you want your endpoints to be able to connect to servers on the public Internet, you'll need to create an Internet routing target for this purpose.

Another type of routing target is a VPN which you configure between the SIMSY platform and your remote VPN server (for example, a firewall or a public cloud provider such as Amazon AWS, Microsoft Azure or Google). SIMSY VPNs use the industry standard IPSec protocol.

Routing targets can also be used to connect directly to external networks - using private cross-connects, private cloud connections or MPLS. If you want to use these services, please get in touch.

Routing Targets are created within a VSlice, so if you want to route to the same network from several VSlices you will need to create several Routing Targets. (This is because the IP addressing between VSlices can overlap, which would create ambiguous routing.)

When creating a Routing Target, you will need to provide configuration information which varies based on the type. For the Internet, nothing needs to be configured - but to create a VPN you will need the IPSec configuration parameters. Consult the documentation of your device (e.g. firewall) or cloud provider (for example AWS).

IP Addressing

For Internet routing targets, we use NAT (Network Address Translation) - to translate whatever IP address is assigned to your device to a public IP address which is suitable for the Internet. This also helps to keep your endpoints secure by hiding the private IP address so it is inaccessible from the Internet.

For other routing targets, such as VPNs, the endpoint IP address is not translated and is passed transparently from end-to-end. It is therefore important that your configure the subnets in your VSlice to suit the needs of the remote network, and set the VPN configuration to suit.

Routing Policy

Routing policies are used to control the flow of data to and from endpoints. They are a core concept in the SIMSY platform, and are a very powerful way to tailor the network for the needs of the application. They affect routing, security and edge services.

Configuration

The configuration of a routing policy is split into three sections:

• Details - basic information such as name, monitor and status
• Policy Rules - the set of rules controlling how data is routed to/from Routing Targets.
• Edge Services - the services within the SIMSY platform which can exchange data with the endpoints related the policy.

The logical order used to create Routing Policies is:

1. Create a VSlice (if it doesn't exist already)
2. Create one or more Routing Targets to represent the external networks which you want your endpoints to connect to
3. Create a Routing Policy to define how these Routing Targets are selected and used
4. Create an Endpoint Group which refers to the Routing Policy
5. Put appropriate the Endpoints into the group.

Policy Rules

A Routing Policy typically contains a number of rules. As data passes through the platform, the rules are consulted in order, one-by-one, until a matching rules is found. Once a match is found, the data is routed according to the configuration of the rule.

If no rules are matched, then the data is dropped and not forwarded.

If you are familiar with IP Access Lists on routers and firewalls, the principle is similar - except that as well as configuring whether data is dropped or forwarded, you can also configure where it is forwarded to.

The example policy above contains three rules, plus the default 'drop' rule which cannot be changed. Traffic which matches either of the first two rules ('iPad to Order Server' and 'Photo App') will be forwarded to the 'AzureVPN' Routing Target], anything else will be routed to the Internet.

Changes to these rules will not take effect until they overall policy is saved.

New rules can be added by clicking 'Add Rule', and existing rules can be changed by clicking the edit (pencil) icon alongside each rule.

Rule Matching

Rules contain a number of parameters which are used to specify what data traffic will match the rule, and how matching traffic should be handled.

• Direction defines which direction of traffic will be matched. 'Uplink' is traffic from the Endpoint towards the Routing Target; 'Downlink' is traffic in the opposite direction.
• Destination IP Pattern is optional, and contains a list of CIDR -formatted subnets.
• Source IP Pattern is the equivalent for downlink traffic - and follows the same rules. The source for uplink traffic is always the endpoint.
• Reflexive toggle is used to control whether returning traffic is also matched. It is usually appropriate for this to be set - otherwise (for example), the responses to outbound requests will be blocked.
• Protocol is used to select a transport protocol (such as TCP, UDP or ICMP). If unselected, traffic of any protocol is matched.
• If TCP or UDP is selected as a transport protocol, Source or Destination ports can optionally be specified too - which will be used in matching. Valid port patterns are as follows: (empty) matches any port, 80 matches the single port (80 = HTTP), 80 443 matches either port 80 (HTTP) or 443 (HTTPS).

Rule Application

Once traffic has been matched against a rule using the above parameters, it is handled according to the following parameters:

• Forward: Routes the data to the selected Routing Target (required)
• Drop: Discards the data and does not forward further
• Reflect: Routes traffic back towards another Endpoint in the same VSlice, identified based on the destination IP address - and subject to appropriate Policy Rules being present in the policy related to the destination Endpoint.

Once a Routing Policy has been created and saved, it can be selected on appropriate Endpoint Groups in the VSlice. Routing Policies not applied to any Endpoint Groups have no effect.

Edge Services

Whereas Routing Targets represent remote networks and services outside of the SIMSY network, Edge Services are securely provided inside our network - closer to the endpoints, and not reliant on the Internet. These services provide benefits over remote services accessed via a Routing Target.

• Performance - access to edge services provides lower latency, since the traffic does not need to traverse the internet
• Security - the services are within the SIMSY network, so are accessible by endpoints but not from users and systems elsewhere on the Internet.
• Authentication - since our platform is tightly integrated into the world's mobile networks, we can identify the endpoint sending data without requiring them to authenticate themselves. This simplifies configuration, and allows less sophisticated devices to be supported.
• Decoupling - edge services can receive and store data, and then subsequently forward it to remote networks. If these remote networks are disrupted or inaccessible, this doesn't impact the endpoints.
• Extensible - the list of Edge Services available is expanding all the time. Powerful services are already available, but there are many more in the pipeline. The Edge Services available to an Endpoint are controlled within the Routing Policy applied to the appropriate Endpoint Group.

Standard Edge Services

• Endpoint Monitor - real-time packet tracing of endpoint traffic
• Edge/Endpoint API - API providing services to endpoints (Environment, Key Value store etc)
• Embedded Terminal- Web-based SSH terminal for remote access to endpoints
• HTTP Publisher - Publish an HTTP based web service running on the Endpoint on the Internet with a unique website address

Event Handlers

Event Handlers represent remote systems to which events can be sent. Various types of event handlers allow events to be sent to different types of receiver. Once one ore more event handlers has been configured, an Event Map is created which controls which which Event Types are sent to which Event Handler(s).

Webhook

The default type of Event Handler is a webhook - a remote URL/script which is called using an HTTP POST request. The URL and path is configured in the Event Handler/Webhook configuration - the HTTP payload contains the data specific to the particular type of event (in JSON format).

In addition to the URL (http supported but https recommended), configuration can contain a timeout (in seconds) and authentication data (where required).

Authentication can use a Bearer Token or HTTP Basic Authentication.

If delivery of an event to a webhook fails, it will be retried according to a back-off schedule but then eventually discarded.

In order to preserve the order of events for a particular scope (Endpoint, Routing Target or Customer Account), should event delivery fail, subsequent events will also be delayed too.

Event Map

Once one or more Event Handlers have been configured, Event Maps are used to control which events they receive. There are many event types which can be generated - and the list is increasing as new features are introduced. See 'Event Types' for the list of event types currently supported.

Event Handlers are associated with Event Types by subscribing. The same Event Handler can be subscribed to multiple event types, and a single event type can have multiple subscribed Event Handlers.

Regional Policies

Regional Policies are used to configure the region your endpoint connectivity enter our global SIMSY network.

Our SIMSY SIMs have global coverage which is achieved by agreements shared between all the global mobile network operators around the world. These mobile operators share a global private network between them to exchange network connectivity. Our SIMSY network is connected to this private global mobile network at specific locations around the world.

When using our SIMSY network, your endpoint connection, must pass though the global mobile network, and enter our SIMSY network from where you can make use of all the features in our portal, like accessing the internet or connecting directly to your backend through a private VPN connection.

Regional Policies allow you to choose in which region your endpoint connectivity enters our SIMSY network.

There are many use cases for which Regional Policies cater for, but primarily it allows your data connection to be closer to your target location (where you have your VPN server hosted for example), to reduce network latency. Another common use case is to keep your "Data Packets" inside a certain region or country border for legal requirements in certain markets.

Regional Policies can be selected and applied to a group of Endpoints, by selected a Regional Policy on an 'Endpoint Group'.

Regional Gateways

The location where an endpoint connection enters our SIMSY network, is called a 'Regional Gateway'. SIMSY has strategically placed regional gateways around the world to choose from.

The first entry in the grid view is the 'Default' option, this indicates the 'Regional Gateway' which will be used, unless overridden by a country/network.

A 'Regional Gateway' selected on a country, means that when an endpoint is in that country, it will use the specific 'Regional Gateway' to enter our SIMSY network.

A 'Regional Gateway' selected on a network, means that when an endpoint is on that network, in that country, it will use the specific 'Regional Gateway' to enter our SIMSY network.

The 'inherit' option is used to indicate that the 'Regional Gateway' is inherit from the parent.

Events

There are many types of event which happen on the network - and which contain detailed information which is useful to developers. The SIMSY network can send these to external systems Event Handlers, and they are also retained within the platform where they can be searched and analysed.

The detail of each event uses a JSON representation - some information is common, whereas other information is specific to the event type.

Each supported event type has a scope - it relates either to a particular Endpoint, a Routing Target or a Customer Account overall.

Event Queries

As events are generated, they are stored within the platform where they can be explored and searched. This is the case irrespective of whether you have created Event Handlers or Event Maps.

In the portal, select 'Event / Event Viewer'.

Filtering

You can search based on timestamp, and filter on specific Event Types.

Event Details

For each event found, the JSON will be included which would have been sent to any Event Handlers, if configured.

API Overview

Every element of the SIMSY platform can be configured and controlled using the API. The SIMSY portal uses this API - so anything that can be achieved with the portal can be achieved from other systems. This allows for tight integration and powerful automation of SIMSY functions.

The API is based on REST - and all the methods and operations are described in the Reference Documentation.

In order to use the API, it is necessary to generate an API token, which is used as Bearer Token. The easiest way to generate an API token is to log in to the portal and choose 'Access Control / API Tokens'.

Tokens are specific to a customer - and by default, the token generated will have access to the same functionality as the user account used to create it.

Tokens can be tested by using Curl or similar - by calling the token verification API - replacing the 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' with the API token generated.

If all is well, the response should be:

This shows the common format of most SIMSY API calls - an outer block of JSON indicating whether the operation was successful, optionally an array of messages (useful if the operation fails), and optionally a 'data' block containing any results.

As an example, consider the API to retrieve the details of a particular VSlice. On success, the data retrieved using this method is as follows:

The 'success' value is 'true', there are no messages, and the 'data' value contains a JSON representation of the VSlice (plus associated data).

Identifying objects

All objects within the SIMSY platform have a unique ID - normally a GUID. This can be used as the identifier when using the API, but if you have assigned a moniker, then this can be used as a convenient alternative.

Getting Started

To get the most out of the SIMSY network and platform, and to benefit from the advanced features it provides, it's best to understand the basic concepts. However, if you're impatient and want to get the data flowing as quickly as possible, here's what you need to do.

1. Get a SIM card
2. Grab a device
3. Activate the SIM
4. Configure the device APN
5. Ready to test!

SIM Activation Steps

• Buy a SIM card directly from us, or from one of our distributors.
• Insert the SIM into your device (computer, IoT device, LTE dongle, Raspberry Pi, or mobile phone).
• Activate the SIM using the portal (you'll need the ICCID and Activation Code).
• Choose default configuration or configure manually.
• Default configuration will automatically create a VSlice, Endpoint Group, Routing Target, Routing Policy, and assign the SIM as an Endpoint.
• Configure the device APN as 'SIMSY.flex' if needed.
• Power up your device and connect to the network.