1NCE FreeRTOS BluePrint demonstrates the usage of various IoT protocols inculuding CoAP, LwM2M, and UDP with cellular connectivity. In combination with 1NCE SDK for the integration of 1NCE OS tools.

1NCE FreeRTOS BluePrint release integrates 1NCE SDK to benefit from different 1NCE OS tools including device Authentication and Energy Saver, with the addition of a static library for CoAP Protocol (Lobaro CoAP) and LwM2M (Wakaama).

This Repository present examples of simple code:

• CoAP protocol
• CoAPs protocol (with DTLS security using Pre-shared key)
• UDP Demo
• LwM2M with Bootstrap
• LwM2M without Bootstrap

Additionally, All the Demos have the Energy Saver feature as a Flag that can be enabled to test this feature.

• B-L475E-IOT01A2 STM32 Discovery kit IoT node connected to BG96 (LTE Cat M1/Cat NB1/EGPRS modem) through X-NUCLEO-STMODA1 expansion board.
• 1NCE SIM Card.
• STM32CubeIDE from https://www.st.com/content/st_com/en/products/development-tools/software-development-tools/stm32-software-development-tools/stm32-ides/stm32cubeide.html
• STM32 ST-LINK utility from https://www.st.com/en/development-tools/stsw-link004.html
• Upgrade the modem BG96 to the latest firmware. (https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW) Note: Download the modem FW flasher tool (QFlash) from this url: https://github.com/1NCE-GmbH/blueprint-freertos/tree/master/Utilities/Modem_FW this tools taked from quectel from the web site listed in the official documentation.

After navigating to your workspace Clone the repository using HTTPS:

$ git clone https://github.com/1NCE-GmbH/blueprint-freertos.git --recurse-submodules

Using SSH:

$ git clone [email protected]:1NCE-GmbH/blueprint-freertos.git --recurse-submodules

If you have downloaded the repo without using the --recurse-submodules argument, you need to run:

git submodule update --init --recursive

• Import the project in STM32Cube.

Setup your demo want to use by going to config_files/aws_demo_config.h define one of three demos exist (by default CONFIG_COAP_DEMO_ENABLED)

CONFIG_COAP_DEMO_ENABLED
CONFIG_UDP_DEMO_ENABLED
CONFIG_LwM2M_DEMO_ENABLED

1NCE FreeRTOS BluePrint allows customers to communicate with 1NCE endpoints via CoAP and use of all features as part of the 1NCE OS.

COAP POST request: In this Section, the following steps are executed:

• Register to the Network.

• Perform a DNS Resolution.

• Create a socket and connect to Server

• Create Confirmable CoAP POST with Query option

• Create Client Interaction and analyze the response (ACK)

• Validate the response.

• Setup the Demo runner in file (config_files/aws_demo_config.h)

#define CONFIG_COAP_DEMO_ENABLED

• The onboarding script configuration can be found in blueprint-freertos\vendors\st\boards\stm32l475_discovery\aws_demos\config_files\nce_demo_config.h in the root folder of the blueprint or /aws_demos/config_files/nce_demo_config.h in IDE.

#define PUBLISH_PAYLOAD_FORMAT                   "Welcome to 1NCE's Solution"
#define democonfigCLIENT_ICCID "<ICCID>"
#define COAP_ENDPOINT           "coap.os.1nce.com"
#define configCOAP_PORT         5683
#define democonfigCLIENT_IDENTIFIER    "t=test"
#if ( configCOAP_PORT == 5684 )
  #define ENABLE_DTLS
#endif
/* Enable send the Information to 1NCE's client support */
#if  defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 )
    #ifndef ENABLE_DTLS
        #define ENABLE_DTLS
    #endif
#endif

For the DTLS Support the default Port is 5684 and automatically defines the ENABLE_DTLS as an additional define

The CoAP DTLS performs 3 main tasks from the 1NCE IoT C SDK :

• Send the Device Authenticator Request
• Get the Response
• Process the Response and give the DTLS identity and PSK to the application code.

1NCE FreeRTOS BluePrint allows customers to communicate with 1NCE endpoints via UDP and use all features as part of the 1NCE OS.

• Setup the Demo runner in file (config_files/aws_demo_config.h)

#define CONFIG_UDP_DEMO_ENABLED

• The onboarding script configuration can be found in blueprint-freertos\vendors\st\boards\stm32l475_discovery\aws_demos\config_files\nce_demo_config.h in the root folder of the blueprint or /aws_demos/config_files/nce_demo_config.h in IDE.

#define UDP_ENDPOINT "udp.os.1nce.com"
#define UDP_PORT 4445
#define CONFIG_NCE_ENERGY_SAVER
//the message you want to publish in IoT Core
#define PUBLISH_PAYLOAD_FORMAT                   "Welcome to 1NCE's Solution"
#define democonfigCLIENT_ICCID "<ICCID>"

The LWM2M support is provided using Eclipse Wakaama library communicating with a Leshan LWM2M server

• Setup the Demo runner in file (config_files/aws_demo_config.h)

#define CONFIG_LwM2M_DEMO_ENABLED

• The client that has registered on the LwM2M server, can send data by doing the Send operation. More specifically, it is used by the Client to report values for Resources and Resource Instances of known LwM2M Object Instance(s) to the LwM2M Server. To use this feature in our Blueprint: remove/ comment #define LWM2M_PASSIVE_REPORTING and define sending object (e.g. /4/0 here). The LWM2M endpoint and the client name can be configured in config_files/nce_demo_config.h as follows:

#define LWM2M_ENDPOINT    "lwm2m.os.1nce.com"
#define ENABLE_DTLS
#define LWM2M_CLIENT_MODE
#define LWM2M_BOOTSTRAP
#ifdef ENABLE_DTLS
char lwm2m_psk[30];
char lwm2m_psk_id[30];
#endif
#define LWM2M_SUPPORT_SENML_JSON
#define LWM2M_LITTLE_ENDIAN
#define LWM2M_SUPPORT_TLV
#define LWM2M_COAP_DEFAULT_BLOCK_SIZE 1024
#define LWM2M_VERSION_1_1
#define LWM2M_SINGLE_SERVER_REGISTERATION
//#define LWM2M_PASSIVE_REPORTING
#if defined(LWM2M_PASSIVE_REPORTING)
#define LWM2M_1NCE_LIFETIME   30000
#else
  #define LWM2M_OBJECT_SEND "/4/0"
#endif

This feature is limited to Users and Accounts who have already accepted our 1NCEOS Addendum to the 1NCE T&Cs. It is a one-time action per 1NCE Customer Account. Please log into the 1NCE Customer Portal as Owner or Admin, navigate to the 1NCEOS, and accept the Terms. If you don't see anything to accept and get directly to the Dashboard of the 1NCEOS, you are ready to go!

N.B: The SMS and Data Consumed for the Troubleshooting are counted against the Customers own Volume of the SIM Card.

This initial version's main target is to allow customers to connect their Things and automate the network debugging faster and more reliably. This will also reduce the workload on our Customer facing support teams and will also allow us to focus on further common issues.

• Go to config_files/nce_demo_config.h --> enable the flag TROUBLESHOOTING (Troubleshooting Example with/without DTLS in primary Flow and SMS as an alternative)

#define COAP_ENDPOINT           "coap.os.1nce.com"
#define configCOAP_PORT         5684
#define democonfigCLIENT_IDENTIFIER    "t=test"
#if ( configCOAP_PORT == 5684 )
  #define ENABLE_DTLS
#endif
/* Enable send the Information to 1NCE's client support */
#define TROUBLESHOOTING
#if  defined( TROUBLESHOOTING ) && ( configCOAP_PORT == 5684 )
    #ifndef ENABLE_DTLS
        #define ENABLE_DTLS
    #endif
#endif

• run the demo : the demo will send the information to the coap endpoint as a first step if No ACK comes then an SMS to 1NCE portal with the required pieces of information.

**** Primary case ****

Figure 16. Troubleshooting from the coap endpoint

**** Fallback ****

Figure 17. Troubleshooting from Portal

for more information on the troubleshooting

Table 1. Key Feature of Troubleshooting Message

Table 2. Network Registration Status

The Device Controller is an API that allows you to interact with devices integrated into the 1NCE API. You can use this API to send requests to devices, and the devices will respond accordingly. For more details you can visit our DevHub

To send a request to a specific device, you can use the following curl command:

curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices/<ICCID>/actions/UDP' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your Access Token >' \
-H 'Content-Type: application/json' \
-d '{
  "payload": "enable_sensor",
  "payloadType": "STRING",
  "port": 3000,
  "requestMode": "SEND_WHEN_ACTIVE"
}'

Replace <ICCID> with the ICCID (International Mobile Subscriber Identity) of the target device and <your Access Token> with the authentication token from Obtain Access Token.

curl -X 'POST' 'https://api.1nce.com/management-api/v1/integrate/devices/<ICCID>/actions/COAP' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <your Access Token >' \
-H 'Content-Type: application/json' \
-d '{
  "payload": "Data to send to the device",
  "payloadType": "STRING",
  "port": <NCE_RECV_PORT>,
  "path": "/example?param1=query_example1",
  "requestType": "POST",
  "requestMode": "SEND_NOW"
}'

Replace <ICCID> with the ICCID (International Mobile Subscriber Identity) of the target device and <your Access Token> with the authentication token from Obtain Access Token.

• payload: The data you want to send to the device. This should be provided as a string.
• payloadType: The type of the payload. In this example, it is set to "STRING".
• port: The port number on which the device will receive the request. In the code, this is defined as NCE_RECV_PORT.
• path: The path of the request. It can include query parameters as well. In this example, it is set to "/example?param1=query_example1".
• requestType: The type of request, such as "POST", "GET", etc.
• requestMode: The mode of the request. In this example, it is set to "SEND_NOW". There are other possible value like SEND_WHEN_ACTIVE.

To handle the incoming request from the 1NCE API, the configuration of certain parameters needed

/* C2D Parameters */
#define NCE_RECV_PORT 3000
#define NCE_RECEIVE_BUFFER_SIZE 200

• NCE_RECV_PORT: This is the port number where your device will listen for incoming requests. It should match the port parameter used in the request.
• NCE_RECEIVE_BUFFER_SIZE : This is the size of the buffer that will be used to receive the incoming data from the 1NCE API.

When the FreeRTOS application receives a request from the 1NCE API, it will produce output similar to the following:

[ListeningTask] [INFO ][LwM2M][9777] Token (len 8) [0xDCB86446841F78AC]
[ListeningTask] [INFO ][LwM2M][9785] OPTION 11 (delta 11, len 7): 
[ListeningTask] [INFO ][LwM2M][9792] Uri-Path [example]
[ListeningTask] [INFO ][LwM2M][9798] OPTION 12 (delta 1, len 0): 
[ListeningTask] [INFO ][LwM2M][9805] Content-Format [0]
[ListeningTask] [INFO ][LwM2M][9811] OPTION 15 (delta 3, len 21): 
[ListeningTask] [INFO ][LwM2M][9818] Uri-Query [param1=query_example1]
[ListeningTask] [INFO ][LwM2M][9825] Payload [Data to send to the device]
[ListeningTask] [INFO ][LwM2M][9833] -Done parsing-------

 [ListeningTask] [INFO ][DEMO][8652] Listening on UDP port 3000...
 [ListeningTask] [INFO ][DEMO][9520] Received 13 bytes:
                                                               enable_sensor

The most effective communication with our team is through GitHub. Simply create a new issue and select from a range of templates covering bug reports, feature requests, documentation issue, or Gerneral Question.