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?

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:

• Example code for Devices.

• No upfront costs due to private M2M infrastructure.

• Data processing on the KPN Things platform.

• Out of the box compatibility with all our different supported destinations.

• Quicker time to market.

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):

• 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:

SMS data communication (downlink only)

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.

What is Connectivity in KPN Things?

Connectivity management is part of Device management in KPN Things, just like Connectivity is part of your Device in real life.

But what if connectivity is not yet linked to a Device? For instance, you want to view all KPN Things SIM cards you have that are not yet put into a Device. For that and other overviews of your (unlinked) Connectivity we created the .

KPN Things comes with two types of integrated networks:

• Our country wide LoRa-network

• Our cellular M2M network (2G/3G/4G/LTE-M) with non-steered global roaming.

Devices that are not connected to our integrated networks can still connect to KPN Things over the internet.

Since LoRa connectivity can only exist as part of a LoRa Device, the Connectivity detail page for a LoRa device is identical to the .

All Connectivity page

This page gives you an overview of all Connectivity items you have.

The following elements can be found on this page:

1. The number of connectivity items you have.

2. An overview of your connectivity items, displaying the following information:

   1. Type - Type of connectivity.

   2. ICCID / DevEUI - Unique connectivity identifier.

   3. Connection - Whether the connection is active or not.

   4. Activated on - (only for M2M) When the connectivity was first activated.

   5. Device - The Device name of the Device the connectivity item is linked to.

   6. Bundle/Rate plan - (only for M2M) The set of applied rules for your SIM card, i.e. whether you may roam and how much data you can use.

   7. APN - (only for M2M) the APN(s) your SIM card may connect with.
3. A search bar to search in Type, Identifier and Connection.

Add new Connectivity

It is not yet possible to order more SIMs through the Things Portal. If you want to add more SIM cards to your account, please contact us:

Connectivity detail page

On the Connectivity detail page of an unlinked Things M2M Connectivity item - a SIM card - you can see the following:

1. Information of the SIM card:

   • The ICCID of the SIM card.

   • The MSISDN of the SIM card.

   • The connectivity status - Active or Deactivated.

   • The moment the SIM card has been activated for the last time.

   • The rate plan of the SIM card.

Link SIM card to Device

After clicking Link Device on the Connectivity detail page, you will be given a list of Device that do not have a SIM card linked to it.

On this page you can search for the Device you are looking for using the search bar (#1 in the screenshot above). By clicking Link in the row of the desired Device (#2 in the screenshot above), you will link the SIM card to that Device.

KPN Things LoRa

Allows the connection of KPN Things LoRa devices.

KPN Things M2M connectivity

Allows the connection of KPN Things M2M devices.

Internet connected

Allows the connection of IP capable devices or systems.

You can register your LoRa devices directly on KPN Things. This will register your device in our network simultaneously. After registration your device can directly join our network. Further configuration KPN Things allows you to decode and forward the data of your LoRa devices to your application. Learn more about all parts of .

LoRa Device registration

Currently only LoRaWAN 1.0.x is supported. Also, only OTAA is available. ABP is not available since it is less secure.

To register a LoRa device on KPN Things you need to enter the following details:

• DevEUI - Unique LoRa device identifier.

• AppEUI - LoRa application identifier.

• AppKey - LoRa device authentication and encryption root key.

LoRa data history

This tab shows you detailed information about the messages send to and from your Device from the perspective of our LoRa network.

Messages in LoRa data history are stored up to 1 month.

Message overview

The message overview of LoRa data history gives you an overview of all message to and from your Device in descending order of time. So the most recent message is at the top of the list of messages.

What you can see here is:

1. The type of LoRa message.

   1. Whether it was an uplink (🔵 blue) or downlink (🟢 green) message.

   2. Whether it was a Join request, Join accept or regular message.

   3. Whether the message was confirmed or unconfirmed, or whether the message carried an ACK.

   4. Whether the messages contained data, mac, or both.

3. The exact timestamp of the message, with millisecond accuracy.

4. The frame counter value of the message. Uplink (FCntUp) and downlink (FcntDown) communication has its own counter.

5. An indication of the signal strength the message.

6. Click on the chevron at the end of a row to see more details of a message.

7. Search bar to see the message history up to a certain point in time.

8. Button to load more data history (if available).

Message detail

When you open the details of a message by clicking the chevron at the right side of the row, you can see the following:

1. Details about the message signal:

   3. The number of gateways that received the message (uplink only).

   4. The Received Signal Strength Indicator (RSSI) of the message (uplink only). This gives you an indication of how strong the message's signal has been received by the best receiving gateway. The closer the number is to zero, the stronger is the received signal.

   5. The Signal to Noise Ratio (SNR) of the message (uplink only). This gives you an indication of the amount of noise when the message was received by the best receiving gateway. It is used to determine the quality of the signal. If the number is high (far above zero), it is easy to demodulate the signal. If the number is low (far below zero), it is hard or impossible to demodulate the signal.

   6. The Estimated Signal Power (ESP) of the message (uplink only). ESP is calculated from RSSI and SNR and gives an indication of the used link budget. The closer to zero the better is the signal.

2. Details about the content of the message:

   1. The LoRa application port on which data was send or received (if applicable).

   2. The exact payload of the LoRa message (if applicable).

   3. The exact MAC content of the LoRa message (if applicable).

   4. Flags that were in the LoRa message, like ACK, FPending or ADRAckReq.

3. Details of the LoRa Geolocation result:

   1. Coordinates of the calculated location.

   2. Radius in meters, the theoretical inaccuracy of the LoRa Geolocation result.

What to expect on first use

This section will explain what you can expect when you first connect your LoRa Device to KPN Things.

In the screenshot below you can see the beginning of a typical LoRa data history. The message are shown in descending order of time, so the first message is at the bottom of the list of messages.

Step 1. Join request

Your LoRa data history should look like this when the join request is sent.

I don't see a join request appearing in the LoRa data history!

This means the network does not see any activity from your device. Try one of the following actions to fix:

• Maybe the network coverage is not ideal at your current position. Thick walls or a sub-optimal antenne can cause issues. Try to move to a more exposed location for better coverage, like moving closer to a window.

• It could be that your device is not sending the join request on SF12, the spreading factor with the farthest reach. Program/configure your device to use this spreading factor when joining to increase coverage of your device.

Step 2. Join accept

After receiving the join request, the network will check whether the Device is known and whether the security details are correct. If so, the network will respond with a join accept.

Your LoRa data history should look like this when the join accept has been sent.

I don't see a join accept appearing in the LoRa data history! I only see join requests.

This means the network sees your requests to join the network, but there is a (security) reason not to accept your join request. Try the following to fix it:

• Check if your device is programmed/configured with the correct AppEUI.

• Try to remove your device from the Portal and re-add it, maybe you made a typo when registering your device.

Step 3. First uplink

After your Device has received and processed the join accept, it can begin sending data.

Your LoRa data history will look this way after your Device has sent its first uplink.

I don't see uplink data appearing in the LoRa data history! I only see join requests and accepts.

This means the join is completed from the network point of view, but somehow your device does not see it the same way. Try the following to fix it:

• Often join accepts are sent on the RX2 receive window. Is your RX2 receive window correctly configured? This should be 869525000 MHz and DR0 (SF12). Some device manufacturers have the device wrongly configured with the RX2 receive window listening on DR3 (SF9). (This is a common issue with Dragino devices!)

• Sometimes the link budget for downlink is smaller than uplink, meaning downlinks are harder to receive than it is to send uplinks. This accounts for worse coverage for downlink than for uplink. Try to move to a more exposed location and try again.

The network is sending Join accepts, but my Device says joining did not succeed!

• It could be that there is a programming error in your Device that causes your Device to incorrectly process the Join accept. Please refer to your device manufacturer documentation for more help on that.

• It could be a LoRa reception problem, due to configuration problems or insufficient coverage. You can check the possible solutions for "I don't see uplink data appearing in the LoRa data history!" above for more info.

Step 4. First downlink

Download messages are messages send by the network to your Device. These can be mac messages, containing commands to your Device about LoRaWAN transmission settings, or they can contain data from your application or from KPN Things.

After a Device has joined, the network will send up to three downlink messages with mac commands in them.

Step 5. Normal operation

Now your Device will go into normal operation, often meaning periodically sending uplink messages. In the screenshot below you can see a typical LoRa data history.

Other things you can see

Example A. Too high sending interval ⚠

Make sure your Device does not send more often than once every 5 minutes on average.

Example B. No answer to mac messages. ⚠

Each mac command consists of a request and an acknowledge message. So mac messages should come in pares in the LoRa data history.

If this is often not the case and you see that downlink mac messages are not answered by the Device, please check your Device, because there might something wrong. If your Device does not follow up mac commands, the transmission settings cannot be optimized.

Make sure your Device responds to all mac commands.

Example C. No new LoRa Geolocation for an uplink. ℹ

Not every uplink message will give a new calculated LoRa Geolocation. This is normal. It can be caused by the fact that too few gateways received the uplink, or if other circumstances were sub-optimal.

Example D. Missing FCntUp: message lost. ℹ

When a value for FCntUp is missing in the LoRa data history, it means that that specific message has not been received by the network. In LoRaWAN communication it is normal to have lost messages, your application should take this into account. It is a side-effect of the very energy efficient way LoRaWAN works. In normal situations you can expect up to 5% message loss. If your losses are higher, coverage on the location of your Device might be temperate.

Example E. Join for each uplink message. ⚠

If you see a join ceremony before each first message (FCntUp = 0), there is something wrong with your Device. Maybe it is losing power in between data transmissions or there is another reason your Device rejoins after each message.

Your Device should not rejoin after each message, because it puts unnecessary stress on the battery consumption of your device and it prevents the network to optimize the LoRaWAN transmission configuration through mac commands.

Make sure your Device remembers its join in between uplink messages.

Example F. Only Confirmed uplink messages ⚠

If you see your Device (almost) only send Confirmed uplink messages, your Device is not properly configured. Sending too much Confirmed uplink messages puts too much demand on downlink communication, since every Confirmed uplink message requests a downlink message containing an ACK (acknowledgement) from the network. The network has not been designed to handle constant Confirmed uplink messages. This will negatively impact the overall capacity of the network. Therefor the use of Confirmed uplink messages is part of our Terms of Use.

No more than 10% of the uplink messages of your Device may be Confirmed messages. All other messages must be Unconfirmed.

LoRa Connectivity details

This tab contains detailed information about how your device is configured inside the LoRa network. When a device is added to the LoRa network, it is configured with a device profile and a connectivity plan.

Device profile

The device profile name consists of three things: the device profile, the LoRa class and the LoRa version.

The profile is used when determining the geolocation of a device. Generally speaking, the geolocation can be determined with greater accuracy for slower moving devices than for faster devices. This is because the algorithm will use the average location of multiple measurements for slower devices.

The profile should describe the motion of the device as it is being tracked. A stolen bike, for example, is usually in one place as it is being located, so it should have the static profile.

The LoRa version is currently always 1.0.x.

Motion indicator

A more fine-grained version of the profile of a device. Values are Near static, Walking speed, Bike speed, Vehicle speed, and Random. Like the profile, this is used when determining the geolocation of the device.

Connectivity plan

Determines the capabilities of the device in the network. Things like how many uplinks and downlinks the device may send and receive, whether to perform geolocation and whether to use a channel mask are configured using this setting. A bit like your mobile phone bundle, this setting also determines the price for device connectivity. This is set by KPN and can't be changed.

Data protocol choice

Learn more

As a prerequisite to use MQTT with KPN Things, you need either a Device with a KPN Things SIM card which is configured to use the kpnthings2.m2m APN or a configured Internet device.

Integrating your device using MQTT is easy as it relies on standard publish and subscription methods. After ingestion, data will be processed and delivered using the KPN Things flow mechanism. Downlinks towards a device can be specified using the Portal or available API's.

Portal configuration

How to enable MQTT for a device

Login to the Things Portal:

1. Find an M2M enabled Device (e.g. a type "Own M2M") in your Devices list. Open the Device details page by clicking on the Device.

2. On the Device details page you will see a link in the top-right corner: "Activate MQTT service". Click the link.

3. You should see a message "MQTT Service was successfully activated." and the MQTT tab will appear, showing the MQTT details.

4. This is the only time you will be able to read (and copy) the generated password, so make sure you note it down. If you need to, you can edit the MQTT configuration to set a different (generated) password.

5. Use the credentials to configure your Device and you are good to go!

Connecting your MQTT device to KPN Things

KPN Things provides an MQTT connector that can be used to publish uplinks from your MQTT device to the KPN Things platform and receive downlinks from the KPN Things platform. Note that the KPN Things MQTT connector is not a full MQTT broker. It can only be used to send uplinks to and receive downlinks from the KPN Things platform. Uplinks published by your device will not be visible to other devices that connect to the MQTT connector. Likewise, downlinks sent to your device will only be visible to your device.

The KPN Things MQTT connector supports MQTT 3.1, MQTT 3.1.1 and MQTT 5.0.

Connecting to the KPN Things MQTT connector

For M2M devices that use a KPN Things SIM card (using APN kpnthings2.m2m), the MQTT connector can be accessed using the MQTT protocol on 10.151.236.154 port 1883. Note that even though the MQTT protocol is unencrypted, your connection to KPN Things is secure because your device has a direct encrypted connection to KPN Things through the mobile network.

If your device does not use a KPN Things SIM card and you have configured it as an Internet device in KPN Things Portal, you can only access the MQTT connector using MQTTS on connect.mqtt.kpnthings.com port 8883.

For MQTTS to work correctly, many devices and/or MQTTS clients must be configured to trust KPN Things MQTT connector's server certificate (or rather the CA root certificate). Whether your device needs this extra configuration depends on the device or MQTT client used. Should you need it, you can download the CA root certificate from our certificate provider Sectigo (from the Root Certificates section). For convenience, you can also find the root certificate here.

When connecting to the MQTT connector, you must provide the username and password that were displayed in Things Portal when you activated MQTT for your device. The MQTT connector currently does not support authentication using client certificates.

To recap:

Sending an uplink

KPN Things MQTT connector will ingest uplinks on any topic, so you're free to choose. The expected message format depends on the decoder you have configured for your device. The decoder for the "Own M2M" and "Own Internet" device types supports SenML, the internal format of the Things Platform. If you're using the decoder › Decoded ThingsML and raw SenML data, your message payload should be a valid SenML pack. For more information see the SenML documentation.

Sending a downlink

Things Manager

You can send a downlink to your MQTT device using the "Send instruction" tab on the device detail page in Things Portal.

API

Or you can use the Actuator API to send downlinks automagically.

The downlink will be published to the downlink topic and will be delivered to the MQTT device the next time the device connects and subscribes to the topic.

The LoRa Connectivity configuration page gives you the opportunity to choose the communication profile that best suits your application.

The Devices overview provide you with a list of all devices als the connectivity used.

1. Click on Devices to show the device overview on the Things Manager tab

2. Search for a device Name of DevEUI to find the device and click the icon to open the Device and Connectivity details

3. Or click on the icon to open the Device and Connectivity directly in your device overview list

1. Click on the Connectivy Plan name to go to the LoRa Connectivity configuration section

2. Or open the LoRa tab and scroll down to the LoRa Connectivity configuration section

1. Click Edit LoRa Connectivity configuration

2. The page show an overview of the current connecivity settings for this device

3. Want to learn more about the different settings how they work then click the link to go to the documentation about LoRa connectivity configuration

Edit configuration

The connectivity plan can be updated here, by selecting the Connectivity plan selection box a new dialog opens In this dialog all available connectivity plans are shown, it shows per connectivity plan if it includes geolocation.