Developer kit (SODAQ R412M)
To quickly get started with development of a KPN Things M2M device.
A nifty, industry standard IoT developer board that allows you to utilize LTE-M networks with integrated GPS, Accelerometer and Magnetometers, Grove Connectors, JST connectors and Arduino compatible open source software that allows for low-power applications.
This getting started targets the SODAQ SARA Arduino Form Factor (AFF) R412M device. Probably other AFF and SFF SODAQs with an R41xM module will work, but we did not test them (yet). If you share your experiences with one of these devices, we can update this manual!
This getting started will give you step by step instructions to get your KPN Things M2M developer kit connected to KPN Things!
0. Check if everything is in the box
Before we start, you should check if everything is present in the box.
Contents
KPN Things SIM card
SODAQ SARA AFF R412M Board
PCB Antenna
LiPo Battery
1. Register for free KPN Things account
If you did not do already, you should register for a free KPN Developer account. This account will grant you access to the KPN Things Portal with a freemium registration.
Having trouble registering? Here you can find more help on registration.
Request test SIM cards
After registration there is another step in order to receive test SIM cards, since we don't know your home address yet to send them to! After registering and logging in for the first time, click on the link in the M2M is now available in KPN Things! notification box on the home page and follow the directions.
You will receive your test SIM cards in a couple of days. The SIM cards will be added to your Portal account already, ready to go!
2. Prepare your development environment (Arduino IDE)
This part of the manual is based on the Getting Started of SODAQ.
Setup your Arduino IDE
With the Arduino IDE we will write our code and program it on the Device.
Download the Arduino IDE and follow the installer.
Open your freshly installed Arduino IDE.
Download the board configuration files for Sodaq boards
When your IDE is all started, execute the following steps to install the Sodaq board configuration files.
Click on File > Preferences
At the bottom you should see Additional Boards Manager URLs. This is where you need to paste the following URL:
After adding the URL, your preferences screen should look like this:
Close the preferences screen with OK
Click on Tools > Board:… > Boards Manager…
Search for SODAQ.
Click on SODAQ SAMD Boards and an install button will appear.
Click Install to install the latest version of your selected board collection.
When the installation is done, click Close.
3. Prepare your Device
Assemble your Device
Step 1: Insert the KPN Things SIM card.
Step 2: Connect the antenna. Push the connector straight on the board.
Step 3: Connect the battery to the right terminal on the board, the one stating BATT.
Step 4: Connect the USB cable to the left USB port, the one next to the SIM card slot.
Make sure you connect your battery when using the board, else the module won't work correctly!
Configure your Arduino IDE
From the Tools menu, under Board, select the correct board type:
Device | Board type |
SODAQ SARA Arduino Form Factor (AFF) R412M | SODAQ SARA |
Also from the Tools menu, under Port, make sure the correct COM port is selected. If you have multiple options, select the one stating SODAQ SARA.
If none of your ports is labelled that way, disconnect your SODAQ, reopen the menu, check which COM port disappeared, reconnect the SODAQ and choose the previously identified COM port.
Upload test sketch
With this test sketch we are going to check whether your Device works.
Copy the passthrough example code from the following SODAQ documentation page:
Paste the passthrough example code in you Arduino IDE.
Uncomment the third line, since you have a u-blox R4xx module
From the Sketch menu, click Upload to send the software to your SODAQ.
If all went well it will say the following in the bottom of the Arduino IDE:
Meanwhile, from the Tools menu, open the Serial Monitor
In the Serial Monitor, select Both NL & CR and set the baud rate to 115200 baud (#1 in the screenshot below).
#2 in the screenshot above illustrates where you can enter commands to be sent to the u-blox module that sits on your Development board.
#3 shows where you will see the responses from the module.
Use the command
AT+GSN
to get the IMEI of your module.You will be needing this value when registering your Device in the next step of this getting started.
Additionally, with the command
ATI9
you can check your firmware version.
The latest firmware version for the R412 is M0.10.00,A.02.14
(as of November 2020)
Available commands
Command | Description | Expected response |
| Communication test |
|
| Firmware version | Some ID. |
| Check signal quality | No connection: Good connection: value around 20 |
| Fetch IMEI of module |
The SODAQ passthrough documentation gives some more available commands. All available commands can be found in the SARA-R4 AT commands manual of u-blox.
4. Register your Device to KPN Things
Open the KPN Things Portal
Open the KPN Things Portal. Go to the All Devices page and click on Add new Device.
Fill in your device information
Select the Own M2M device device type.
Enter a name for your SODAQ device.
Click Add Device to continue.
Provide Network Information
Now enter the M2M specific information of your Device.
IMEI of your Device. This value is printed on your u-blox module:
2. ICCID of your SIM card. This value is printed on your SIM card. Select the correct SIM card from the drop down.
If you have an Early access SIM, you choose the option "Add early access SIM" and enter the ICCID of the SIM manually in the newly appeared input field.
3. Shared secret - a kind of password for the future data coming from your Device. Here you should come up with a unique password containing at least:
One lower case character.
One upper case character.
One number.
One special character.
32 characters in total.
The shared secret should also be programmed into your Device in step 5.
4. Click Add Network Info to save the network information and then Finish to continue.
Learn more about M2M in KPN Things.
5. Program your device to send a message
In this step we are going to flash the Device with a program to send data to KPN Things.
Download the ThingsML and Sodaq libraries
The ThingsML library will provide code for your Device to communicate with KPN Things. The SODAQ libraries will provide code to interface with the components on the development board.
From the Tools menu in your Arduino IDE click on Manage Libraries...
Now, in the Library Manager, wait for all libraries to load.
Then search and install the following libraries:
ThingsML
Sodaq_LSM303AGR
Sodaq_R4X
Sodaq_wdt
When the installations are finished, click Close.
Upload the example sketch
This example will read the board temperature from the onboard thermometer and send it to KPN Things every 60 seconds.
From the File menu, click on Examples. Now find ThingsML, then select sodaq, and within that choose sara_aff_temperature.
Fill device identifiers in example code
Look for the following part in the example code and fill in the missing values:
Device URN should be completed with the IMEI of your Device.
Make sure you leave the trailing colon
:
in place in theDEVICE_URN
variable!
Device Key should be filled with the shared secret of your Device.
APN should be filled with the following value:
kpnthings.iot
, since this developer kit is distributed with KPN Things M2M SIM cards.
Run the sketch
Upload the sketch to your Device and open the Serial Monitor. The device will report some of the setup steps it will perform:
This means your Device is trying to connect to our LTE-M network. After some seconds the following lines will appear:
This means your Device has join our network and has sent its first uplink message to KPN Things!
Check incoming data in the Portal
Now your Device has connected to the network and is sending data, you should visit the Device Detail Page in the Portal of the Device you created in step 4.
In the connectivity block, you should see that the last message time indicates that KPN Things just received a message from your Device!
6. Setup data flow in KPN Things
You now successfully connected your M2M device to KPN Things! To further setup your data flow in KPN Things, you should pick up the general Getting Started from step 3:
More information
Interested in expanding the example sketch to make the Device do exactly what you want? Use the following references to find more information on Things code and SODAQ code:
The ThingsML library contains another SODAQ example that reads out the GPS module and sends latitude and longitude to KPN Things.
The SODAQ Support pages contain several examples to read out the sensors you can find on the SODAQ boards: https://support.sodaq.com/Boards/Sara_SFF/examples/.
Additional documentation on the ThingsML library can be found in Github: https://kpn-iot.github.io/thingsml-c-library/
Last updated