Get Started with Super SIM Connection Events

KORE Event Streams is a new, unified mechanism for tracking your application's interactions with KORE products. It spans KORE's product line to provide a common event logging system that consistently supports product-specific event types. You use a single API to subscribe to the events that matter to you.

Super SIM provides a set of event types focused on devices' attempts to attach to cellular networks and, once they are connected, the data sessions they establish to send and receive information.

This tutorial will show you how the Event Streams API works and how you can use it to monitor your Super SIMs. If you've already set up Event Streams for another KORE product, then you may prefer to jump straight to the documentation that describes the event types unique to Super SIM. No problem. But if you're keen to try Event Streams for the first time to see how this API might help you monitor your IoT fleet, read on.

Event Streams currently supports two destinations for your events: AWS Kinesis and webhooks. For real-world large-scale applications, you'll most likely prefer the scalability and flexibility of AWS Kinesis, but webhooks provide a starting point for smaller apps, API testing, and development, so that's the approach we're taking here.

However, for those of you looking to move to a more sophisticated setup, we have a tutorial that walks you through setting up AWS Kinesis to relay events to ElasticSearch and using Kibana as an events monitor dashboard.

This tutorial assumes you're on a Linux box or a Mac, but it should work under Windows. We'll note Windows-specific points as we come to them. Whatever platform you're using, we'll take it as a given that you have Python 3 installed and are familiar with the basics of the language. Likewise, using the command line on your preferred platform.

OK. Let's get started.

---

1. Turn your Super SIM-enabled device OFF

---

2. Set up your system

The first thing to do is gather the software you will need to complete the tutorial. You'll be using a specific setup to trial Event Streams with Super SIM and while this may not mirror the tools you'd use in a real-world application, it will give you a clear picture of how the system works.

1. Install and set up curl tool: depending on your operating system, this guide will show you how to install it.

2. Install the Python tools Falcon and Gunicorn:

pip3 install falcon gunicorn

1. If you're using Windows but not running the Windows Subsystem for Linux, omit gunicorn and install waitress instead.

2. Download Ngrok then install it by unzipping the download file and moving the ngrok binary to your current working directory. Ngrok is free to use but it requires you to set up an account in order to get a token to authorize its usage. Go and sign up now.

3. Go to the Ngrok dashboard and copy your AuthToken.

4. Hop back to your terminal and configure ngrok replacing the placeholder text with the token you copied in the previous step.

  ngrok config add-authtoken <NGROK_AUTH_TOKEN> 

---

3. Set up and run your events receiver

With the tools in place, you need to establish a server on your machine that will receive Super SIM events streamed from KORE. This is what Falcon and Gunicorn are for. Falcon is an app server and it operates via a basic web server — Gunicorn in this case. First, though you need an app to serve, so copy the code below into a text editor then save it in your working directory as server.py.

# 'wsgiref' is provided by Gunicorn/Waitress
from wsgiref.simple_server import make_server
import falcon, json

class Event(object):
  def on_post(self, req, resp):
    # Configure the response to KORE
    resp.status = falcon.HTTP_201
    resp.body = json.dumps({"success": True})

    # Parse the received data and extract some
    # of the information it contains
    if req.content_length:
      data = json.load(req.stream)[0]
      sim_data = data["data"]
      event_type = sim_data["event_type"]
      time_stamp = sim_data["timestamp"]
      sim_name = sim_data["sim_unique_name"]
      if not len(sim_name):
        sim_name = sim_data["sim_sid"]
      if not time_stamp in events:
        events[time_stamp] = "KORE EVENT " + event_type + " received from SIM " + sim_name
        print(events[time_stamp],"at",time_stamp)

# Main entry point
if __name__ == '__main__':
  events = {}
  app = falcon.App()
  eventHandler = Event()
  app.add_route('/events', eventHandler)

  with make_server('', 8000, app) as httpd:
    print('Serving on port 8000...')
    httpd.serve_forever()

This code uses Falcon to set up an endpoint for POST requests at the path /events. It then serves the endpoint on port 8000. When a POST request is received, it's passed into the function on_post(), which configures a status code 201 ('object created') response, and then prints some of the data included in the event so you can view events as they arrive.

Open a terminal on your system, navigate to the file you just saved and run this command:

python server.py

You'll see the server start and begin listening on port 8000. Remember the port number — you'll need it in the next step.

---

4. Serve your events receiver

Your event receiver is only accessible on your own machine. You need to expose it to the Internet so that KORE can reach it too. The most secure and anonymous way to do this is to use Ngrok, which routes over a virtual private network (VPN) to your computer any HTTP requests that are sent to a temporary public URL.

Not only is it secure, but it's also free and you don't even need to set up an account if you're happy running it for a limited period at any one time.

Open up another terminal tab or window, navigate to where you placed the ngrok binary you downloaded in Step 2, and run this command:

ngrok http 8000

You'll recognize the port number from Step 3.

ngrok will output a bunch of information — make a note of the https forwarding address. It'll be something like https://0bc7bd985b0f.ngrok.io and it will be forwarding to http://localhost:8000 which is your event handler. It will look something like this:

---

5. Configure KORE Event Streams

1: Create a Destination

A Destination is an Event Stream destination. To set up a Destination, you create a Destination resource using the Event Streams console. Event Streams currently support two Destination types: AWS Kinesis and webhooks. The former requires an AWS account, so we're going to demo Event Streams with a webhook. To be precise, you're going to configure Event Streams to send events to your event handler via Ngrok. A quick guide on how to create a Destination is available through the Webhook Quick Start guide.

You'll need to enter the Ngrok forwarding URL from Step 4. Make sure you don't overwrite the /events in the Destination URL field — this is the endpoint defined in your server code in Step 3. You can name your destination according to your preference, in this example, we will use the name "New-Webhook-Destination" as Destination Name and "https://0bc7bd985b0f.ngrok.io" - same as provided for your in Step 4 - as your the Destination URL.

Click Finish. The page should create a Destination which you'll need in the next step.

---

2: Create a streaming rule

Event Streams uses a publish-subscribe (aka 'pub-sub') model: you subscribe to the events that interest you, and KORE will publish those events to your Destination.

There are six Super SIM event types, each identified by a reverse domain format string:

Event Type	ID String
Attachment Accepted	com.twilio.iot.supersim.connection.attachment.accepted
Attachment Rejected	com.twilio.iot.supersim.connection.attachment.rejected
Attachment Failed	com.twilio.iot.supersim.connection.attachment.failed
Data Session Started	com.twilio.iot.supersim.connection.data-session.started
Data Session Updated	com.twilio.iot.supersim.connection.data-session.updated
Data Session Ended	com.twilio.iot.supersim.connection.data-session.ended

The types are largely self-explanatory. The exception is Attachment Failed, which is a generic 'could not connect' error that you may encounter when your device tries to join a cellular network.

In a typical connection sequence, you would expect to receive: one Attachment Accepted, one Data Session Started, and then multiple Data Session Updated events. When your device disconnects, you'll receive a Data Session Ended event at that point.

Now let's set up some Streaming rules.

To get events posted to your new Destination, you need to create a Streaming rule. This essentially tells KORE what events you're interested in. A quick guide on how to create a Streaming rule is available through the Webhook Quick Start guide.

Select the destination where these events will be delivered. In this example, we've included all but the Data Session Updated event so you don't impact your free event quota.

Click Create. The page should create the Streaming rule that will deliver the events to your destination.

Are you ready? Switch back to the terminal tab running the event handler — it's the first one you opened — and…

---

6. Turn your Super SIM-enabled device ON

You'll see a series of events printed to the terminal as your device boots up, tries to connect to the network, does so, and then begins sending and receiving data. For example:

If you're running this guide on a Mac, you may see some errors in the output too, in particular OSError: [Errno 41] Protocol wrong type for socket. This is nothing to worry about, and you'll soon see the subscribed notifications appear. The errors relate to longstanding bugs in Python's internals, not to the code you've entered.

---

7. Tidy up

When you've seen enough, you should cancel this sample Event stream by deleting the Streaming rule and the Destination you created in Step 5. This ensures that KORE doesn't continue to send messages to your events handler, when you're about to shut down.

First, Goto Streaming Rules, select the test rule, delete, and confirm.

Next, delete the Destination as well because it's bound to the Ngrok input URL, which is temporary. Goto Destinations, select the Destination, delete, and confirm.

When done, you can switch to your Ngrok terminal and close the tool down with Ctrl-c. Use the same keys to shut down the event handler in the remaining terminal window or tab.

If you restart Ngrok, you'll get a new URL. You can't update an existing Destination with an alternative destination, so you will need to create a new Destination with the new URL — just re-run the code you created in Step 4.

---

Next steps

You've used the KORE Build page, a pair of Python applications, and Ngrok to receive and display events streamed from KORE in response to actions performed by your Super SIM-connected device. Your computer and the device may only be inches apart on your desk, but you've seen how Event Streams can be used to feed you event data from any of your Super SIM-connected devices anywhere in the world.

As a next step in exploring Super SIM and Event Streams, you might try changing the event handler code to write a log file for all your SIMs, the events they generated, and when. You might also write some code to parse that log and present the results graphically.

We've only displayed a few data points in each event. When you fully harness the power of Super SIM events, you'll be able to get network and cell tower level location information, data usage reports, and so much more.

If your want a more sophisticated setup, why not work through our Connection Events , AWS ElasticSearch, and Kibana tutorial? You'll set up an AWS Kinesis Destination, use it to relay Super SIM events to ElasticSearch, and then use Kibana as an events monitor dashboard.

We can't wait to see what you build with Super SIM connection events!