Connecting M2M Devices

Before you can register your M2M devices to KPN Things, you need to be in possession of KPN Things SIM cards. You can visit the All Connectivity page in the KPN Things Portal to see the SIM cards available in your account.

M2M Device registration

When registering an M2M device to KPN Things, some information needs to be provided:

  • IMEI - The IMEI number that uniquely identifies your device. This value is used for authenticating the device when IoT data is received by the system.

  • Shared Secret - The pre-shared password used for authorizing ingestion of IoT data from the device by the system. This value is not required for all types of M2M devices.

Additionally, Things needs to know the ICCID of the SIM card that is inserted in the Device. The ICCID that uniquely identifies the SIM card. This is used for connectivity management and sending SMS to the device if configured.

Additional information

  • MSISDN - MSISDN is a number uniquely identifying your M2M subscription in the mobile network. It is also known as phone number, or 06-nummer in Dutch. Although M2M SIM cards often have a 079-nummer.

  • Rateplan - The commercial bundle of your SIM card.

Why use Things M2M?

KPN Things M2M connectivity is only available for devices with a KPN Things SIM card. Devices with a SIM card from a different provider can be connected to KPN Things through the Internet connection.

When using Things M2M connectivity to connect to KPN Things, we control the communication path between your device and the data processing in KPN Things. We know this path is secure, so SSL is not required anymore to provide data security. Then you don't need to implement SSL on your device anymore, saving power and bandwidth. An HTTPS request uses up to 10 times more bandwidth then a plain HTTP request.

Why KPN Things M2M instead of traditional M2M connectivity:

Network connection

When you have a KPN Things SIM card, you need to use the following information to connect to KPN Things:

  • APN (depends on SIM type):

APN

SIM type

kpnthings.iot

  • Regular KPN Things SIM

  • SIM through Comarch

kpnthings2.m2m

  • KPN Things + (plus) SIM

  • Early access SIM

  • SIM through Jasper

  • IP: 10.151.236.157

There is no DNS available.

HTTP data communication

The request = uplink data

POST /ingestion/m2m/senml/v1 HTTP/1.1
Host: m.m
Things-Message-Token: <messageToken>
Content-Type: application/json
Content-Length: <nrBytes>

[{"bn":"urn:dev:IMEI:<imei>:","bt":<timestamp>},<measurements>]

Body

The body of the HTTP request should be a valid SenML pack. For more information see the SenML documentation.

Base time

The base time bt in the SenML body is optional, because not all devices keep track of the absolute time. If Things Data Management receives a message without base time, the moment that the message is received will be filled in as base time.

Things Message token

For device authentication we introduce a pre-shared secret for each device. This secret is used by the device to generate message tokens that are SHA256-hashes which are send in the Things-Message-Token header of the request. This token can be used by Things to validate the source of the message. At the same time it prevents tampering with the measurement values.

The secret should be at least 30 characters long and no more then 100, is case sensitive and can contain all ASCII characters: ^[0-9a-zA-Z]{30,100}$

The pre-shared secret is used directly for message token calculation. There is no challenge protocol or no session keys, because we rely on the secure channel for complete integrity.

The message token is calculated as following:

messageToken = sha256({requestBody}{sharedSecret})

The requestBody used for the hash should be identical as the body send in the HTTP request. Preferably strip this body from all white space characters before putting it in the hash and the HTTP request.

This authentication method requires a SHA256-function to be executed on the device, this is order magnitude 1 * 10^-7 J (0,1 microjoule), which is reasonable to add to the device.

The response = downlink data

When you send data to KPN Things using a HTTP request, the HTTP response is used to transmit a possible downlink message to your device. Only if a downlink message is in status Executing it will be send, and only one downlink message is send at a time.

A downlink message will be structured as SenML in JSON format. Learn more about downlink communication.

Response code

Using the HTTP response code you can debug some common problems:

Code

Description

202

🟢 The message was received and accepted for further processing.

400

🔴 The received message was not correctly structured.

Check whether all required headers are present and whether the request body is correctly formatted.

401

🔴 The Things Message Token could not be verified.

Check the shared secret and the hashing method in your device.

404

🔴 The provided device identifier was not recognized. Check whether the identifier is correct and known in the Things Portal.

SMS data communication (downlink only)

SMS downlink communication is only available for Things M2M+ SIM cards

When the device receives an SMS, the sender will be 5277.

SMS's are send using a retry back-off schema if the receiving Device is not connected to the network. The schema is as following:

  • First 5 minutes: every minute

  • Next hour: every 10 minutes

  • Next 12 hours: every hour

  • Next 36 hours: every 4 hours

After a total of 48 hours (two days) the network will discard the SMS from the queues due to inactivity. The Actuator API will report the SMS as FAILED.

When designing the on-off power cycles of your M2M device, make sure you take into account to back-off schema in order to not miss the retries of SMS's.

Devices with M2M connectivity have some specific tabs on the Device detail page to display M2M specific information.

MQTT

Read all about the use and possibilities of MQTT ingestion on the next page.

M2M data history

Coming soon

Firmware over the air

The documentation for sending firmware updates to your M2M device can be found at KPN FotA.

Last updated