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!
Before we start, you should check if everything is present in the box.
- 1.KPN Things SIM card
- 2.SODAQ SARA AFF R412M Board
- 3.PCB Antenna
- 4.LiPo Battery
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.
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!
With the Arduino IDE we will write our code and program it on the Device.
- Open your freshly installed Arduino IDE.
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:
http://downloads.sodaq.net/package_sodaq_samd_index.json
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.
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!
- 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.
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:
Verify XXX bytes of flash with checksum.
Verify successful
done in XXX seconds
CPU reset.
- Meanwhile, from the Tools menu, open the Serial Monitor
.png?alt=media&token=ad73b7f3-ee3e-42f9-a96b-d6c849f00ed5)
- 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+GSNto 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
ATI9you can check your firmware version.
The latest firmware version for the R412 is
M0.10.00,A.02.14 (as of November 2020)Command | Description | Expected response |
AT | Communication test | OK |
ATI9 | Firmware version | Some ID. |
AT+CSQ | Check signal quality | No connection: +CSQ: 99,99Good connection: value around 20 |
AT+GSN | 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.
- 1.Select the Own M2M device device type.
- 2.Enter a name for your SODAQ device.
- 3.Click Add Device to continue.
Now enter the M2M specific information of your Device.
- 1.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.
In this step we are going to flash the Device with a program to send data to KPN Things.
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.
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.
Look for the following part in the example code and fill in the missing values:
/*
* Configuration
*/
#define DEVICE_URN "urn:dev:IMEI:--fill-me--:"
#define DEVICE_KEY "--fill-me--"
/* ... */
#define APN "--fill-me--"
- Device URN should be completed with the IMEI of your Device.
- Make sure you leave the trailing colon
:in place in theDEVICE_URNvariable!
- 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.
- Upload the sketch to your Device and open the Serial Monitor. The device will report some of the setup steps it will perform:
Console open
Turning on modem...
Connecting to network...
This means your Device is trying to connect to our LTE-M network. After some seconds the following lines will appear:
Network connected
Sending message...
Receiving message...
Message response length: 97
Message response:
HTTP/1.1 202
Date: Tue, 03 Nov 2020 13:42:47 GMT
Content-Length: 0
Connection: keep-alive
Message sending finished.
Modem off
------------
This means your Device has join our network and has sent its first uplink message to KPN Things!
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!
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:
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/