1NCE IoT C SDK for Embedded C is a collection of C source files under the MIT Open source license that can be used in embedded applications to connect to benefit from different services in 1NCE OS. it contains CoAP Authentication, and energy saver features. This SDK is independent of the platform, can a customer use in any device work with standard C.
The 1NCE IoT C-SDK is licensed under the MIT open source license.
1NCE IoT C SDK allows customers a seamless setup and use of all features as part of 1NCE OS. 1NCE IoT C SDK contains the following services:
The 1NCE IoT c SDK also provides authentication for IoT devices communicating through DTLS. In this case, the device receives a DTLS Identity and a Pre-Shared Key (PSK) that can be used to establish a secure connection to the CoAP endpoint of 1NCE Data Broker.
More details about device authentification are available at 1NCE Developer Hub (Device Authenticator).
The Energy Saver aims to minimize the payload size sent from the device to a simple byte array that can be converted to JSON Format. The resulting message is then sent using MQTT via the Data broker. Translating the byte array is done using Binary Conversion language which splits the array into a sequence of values defined in a translation template.
Check 1NCE Developer Hub (Energy Saver) for further explantion of the translation template creation.
This interface can be used to send Memfault data chunks to 1NCE CoAP Proxy. Once received by the proxy, the chunks are forwarded to the Memfault API in the project that is associated with the 1NCE OS Memfault plugin.
1NCE IoT C SDK releases will follow a Semantic versioning Given a version number MAJOR.MINOR.PATCH, increment the:
- MAJOR version when you make incompatible SDK changes,
- MINOR version when you add functionality in a backward-compatible manner,
- PATCH version when you make backward-compatible bug fixes.
1NCE IoT C SDK can be imported as a Zephyr module which is integrated with nRF Connect SDK.
The following commands will import 1NCE IoT C SDK, Nordic nRF Connect SDK and 1NCE Zephyr blueprint which includes CoAP, UDP & LwM2M Demos.
west init -m https://github.com/1NCE-GmbH/1nce-iot-c-sdk
west update
Then, using the quickstart command, you can directly build and flash the demos to a connected nRF9160 Development Kit.
The Default demo establishes a secure connection to 1NCE endpoint via CoAP after receiving DTLS credentials from the Device Authenticator.
west quickstart
The command can also be used to run udp and lwm2m demos and to enable energy saving.
usage: west quickstart [-h] [-p PROTOCOL] [-e ENERGYSAVING]
Build and flash CoAP (With DTLS), LwM2M or UDP Demos, the payload reduction (using 1NCE Energy saver) can also be enabled.
options:
-h, --help show this help message and exit
-p PROTOCOL, --protocol PROTOCOL
Select the protocol: coap (Default), lwm2m or udp
-e ENERGYSAVING, --energysaving ENERGYSAVING
Set to "y" to enable energy saver
This section shows you:
- How to get the identity and pre-shared key using 1nce Device Authenticator. (for CoAP application).
- How to use 1NCE Energy Saver to reduce the data (and/ or Energy) consumption.
The Example shows how to set up and integrate 1nce SDK in Embedded Application written in C.
The SDK requires using a 1NCE SIM card with a connected AWS account configured through 1NCE Portal. GCC must also be installed to compile the project. For more information, see the https://gcc.gnu.org/install/index.html. you can find the downloads of the compiler.
- Step 1: Clone Repository
- Step 2: Implement abstract functions
- Step 3: Integrate SDK in your Application
- Step 4: Run your Application
you clone the SDK for Embedded C in your project using git clone To clone using HTTPS
git clone https://github.com/1NCE-GmbH/1nce-iot-c-sdk.git
Using SSH
git clone git@github.com:1NCE-GmbH/1nce-iot-c-sdk.git
You need to implement your four transport functions how you want to access our endpoint.
- nce_os_udp_connect
- nce_os_udp_send
- nce_os_udp_recv
- nce_os_udp_disconnect
To implement your functions, we recommend to see our Blueprints
1NCE SDK is simple to integrate in every Embedded App written with C, To begin, you need to define an object type OSNetwork_t and affect to their variable the network socket and implemented functions as shown in the example below. (Note: This is not required for Zephyr Memfault interface, as the network interface there is internally defined)
OSNetwork_t xOSNetwork= { 0 };
os_network_ops_t osNetwork={
.os_socket=&xOSNetwork,
.nce_os_udp_connect = nce_os_udp_connect_impl,
.nce_os_udp_send = nce_os_udp_send_impl,
.nce_os_udp_recv = nce_os_udp_recv_impl,
.nce_os_udp_disconnect = nce_os_udp_disconnect_impl };
With CoAP protocol (using DTLS) you can call os_auth
DtlsKey_t nceKey={0};
int result = os_auth(&osNetwork,&nceKey);
then we can have psk and pskIdentity stored in DtlsKey_t struct.
os_energy_save function can be used to convert payloads to binary format. The following figure shows a sample translation template that can be used to share GPS data and device information:
Considering case 1:
The binary payload for this case can be generated as follows
/* values to be sent conform to the template information*/
Element2byte_gen_t battery_level = {.type= E_INTEGER,.value.i=99,.template_length=1};
Element2byte_gen_t signal_strength = {.type= E_INTEGER,.value.i=84,.template_length=1};
Element2byte_gen_t software_version = {.type= E_STRING,.value.s="2.2.1",.template_length=5};
uint8_t selector = 1; /* select case 1 */
char pcTransmittedString[500];
int status=1;
/* if status=1 then the energy save failed */
status=os_energy_save(pcTransmittedString,selector, 3,battery_level,signal_strength,software_version);
The resulting packet can then be sent to the energy saver for further processing
Complete the following macros in log_interface.h
#define NceOSLogInfo( format, ... )
#define NceOSLogDebug( format, ... )
#define NceOSLogError( format, ... )
#define NceOSLogWarn( format, ... )
If you are using FreeRTOS you can just use the macro #define FREERTOS
To enable the Memfault interface, configure it in the prj.conf file of your Zephyr application:
CONFIG_NCE_MEMFAULT_INTERFACE=y
Once enabled, you can call the following function to send data to Memfault:
int err = os_memfault_send();
The function uses Zephyr Memfault SDK to collect diagnostic data, which it then transmits to the 1NCE OS CoAP Proxy using a predefined CoAP interface.
The configuration options for Memfault interface are:
CONFIG_NCE_SDK_MEMFAULT_BUFFER_SIZE_BYTES The maximum size of the Memfault data buffer (to be sent in a single CoAP packet payload). The default size is 512 bytes.
CONFIG_NCE_SDK_MEMFAULT_PROXY_URI The Proxy URI of Memfault Endpoint.Set by default to "https://chunks.memfault.com/api/v0/chunks/:iccid:", the ICCID is set by the CoAP Proxy.
CONFIG_NCE_SDK_MEMFAULT_ATTEMPTS The maximum number of attempts for sending Memfault data. Default is 3 attempts.
CONFIG_NCE_SDK_MEMFAULT_ATTEMPT_DELAY_SECONDS Delay between Memfault sending attempts (seconds). Default is 5 seconds.
CONFIG_NCE_SDK_ENABLE_DTLS Enable DTLS for COAP communication with the 1NCE endpoints.
CONFIG_NCE_SDK_SEND_TIMEOUT_SECONDS Network send Timeout (seconds). Default is 10 seconds.
CONFIG_NCE_SDK_RECV_TIMEOUT_SECONDS Network receive Timeout (seconds). Default is 10 seconds.
CONFIG_NCE_SDK_DTLS_HANDSHAKE_TIMEOUT_SECONDS DTLS Handshake Timeout (seconds). Default is 15 seconds.Accepted values for the option are: 1, 3, 7, 15, 31, 63, 123.
CONFIG_NCE_SDK_DTLS_SECURITY_TAG The DTLS security tag for communication with the 1NCE CoAP server.
The tag should contain a valid Identity and PSK for DTLS communication. These credentials can be obtained using os_auth function and stored in the modem.
Run your code in ISO C90
The Doxygen references were created using Doxygen version 1.9.2. To generate the Doxygen pages, please run the following command from the root of this repository:
doxygen docs/doxygen/Doxyfile
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.
See CONTRIBUTING.md for information on contributing