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 Connectivity Suite. it contains MQTT Onboarding, CoAP Onboarding, and translation service. 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 Connectivity Suite. 1NCE IoT C SDK contains the following services:

The connection to AWS IoT core is mainly done through MQTT, and Devices are created as "Things" that can have various attributes to define their functionality. After creating a representation of the “thing” in AWS IoT Core, a certificate, private key, and public key are generated for the device to enable secure communication to the cloud. In addition, policy configuration is needed to determine what are the permissions granted for the device. In the MQTT context, this can for example determine the topics that the device can Publish and/or Subscribe to.

The 1NCE IoT c SDK also provides onboarding credentials 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 onboarding are available at 1NCE Developer Hub (SIM-as-an-Identity).

The translation service 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 (Translation service) for further explantion of the translation template creation.

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.

This section shows you:

• How to get a certificate using 1nce onboarding endpoint.
• How to process the certificate to make it usable for AWS services.
• How to get the identity and pre-shared key using 1nce onboarding endpoint. (for CoAP application).
• How to use 1NCE Translation Service 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.

This Example includes two cases:

• Offload certificates.
• Unload certificates.

The Examples used FreeRTOS as First Version.

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-sdk.git --recurse-submodules

Using SSH

git clone [email protected]:1NCE-GmbH/1nce-sdk.git --recurse-submodules

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

git submodule update --init --recursive

You need to implement your four TLS functions how you want to access our endpoint onload or offload and also depending on your modem.

• nce_TLS_Connect
• nce_TLS_send
• nce_TLS_recv
• nce_TLS_Disconnect

To implement your functions, we recommand to follow the examples.

for the Implementation we use the psuedo code:

TlsTransportStatus_t TLS_Connect_impl(NetworkContext_t *pNetworkContext,
			                          const char *pHostName, uint16_t port,
			                          const NetworkCredentials_t *pNetworkCredentials,
			                          uint32_t receiveTimeoutMs, 
			                          uint32_t sendTimeoutMs)

1. configure the onboarding socket
2. Create TCP Socket.
3. Connect the socket with the endpoint ONBOARDING_ENDPOINT in port ONBOARDING_PORT

int32_t TLS_send_impl(NetworkContext_t *pNetworkContext,
			          const void *pBuffer,
			          size_t bytesToSend)

Create send via TLS for Quectel BG96 we can call At command AT+QSSLSEND

int32_t TLS_recv_impl(NetworkContext_t *pNetworkContext,
                      void *pBuffer,
			          size_t bytesToRecv)

Create Recv function via TLS for Quectel BG96 we can call At command AT+QSSLRECV

void TLS_Disconnect_impl(NetworkContext_t *pNetworkContext)

1. Call socket shutdown function to close the connection
2. Free mbedTLS contexts.

For the Onload Certificate, we can refer to using_mbedtls in FreeRTOS Demo

1NCE SDK is simple to integrate into every Embedded App written with C. To begin, you need to define an object type tls_api and the affect to their variable the networkContext and implemented functions as shown in the example below.

    tls_api xtls_api;
    xtls_api.pNetworkContext= &xNetworkContext;
    xtls_api.conn=TLS_Connect_impl;
    xtls_api.disconn=TLS_Disconnect_impl;
    xtls_api.tlssend=TLS_send_impl;
    xtls_api.tlsrecv=TLS_recv_impl;

The object can then be passed to nce_sdk function as follows:

   nce_sdk(&xtls_api,1);

then you have the Root certificate stored in rootCA , Client certificate in clientCert , device private Key in prvKey Thingname, endpoint and topic name also stored in nceThingName ,nceEndpoint,nceExampleTopic respectively.

With CoAP protocol (using DTLS) you need just to change the 1 to 0

    nce_sdk(&xtls_api,0);

then we can have the pre-shared key and identity stored in psk and pskIdentity

nce_generate_BCL_payload 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 */
	uint8_t battery_level = 99;
	uint8_t signal_strength = 84;
	char software_version[] = "2.2.1";
	
    /* Template information */
	char type[] = "UUS"; 
	int bytelength[]={1,1,5};


    uint8_t selector = 1  /* select case 1 */;
	int location=1;
	uint8_t packet[8];

    /* Add battery level */
	location = nce_generate_BCL_payload( type, 0,packet, selector,&battery_level,location,bytelength );
    
    /* Add signal strength */
	location = nce_generate_BCL_payload( type, 1,packet, selector,&signal_strength,location,bytelength );
    
    /* Add software version */
	location = nce_generate_BCL_payload( type, 2,packet, selector,software_version,location,bytelength );

The resulting packet can then be sent to the translation service for further processing

Run your code in ISO C99

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

See CONTRIBUTING.md for information on contributing