Skip to content

Commit

Permalink
Update documentation V2.0.0
Browse files Browse the repository at this point in the history
  • Loading branch information
@jamali005
jamali005 committed Sep 14, 2022
1 parent ecdca63 commit be8230e
Show file tree
Hide file tree
Showing 9 changed files with 164 additions and 172 deletions.
186 changes: 90 additions & 96 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,39 +3,34 @@
# 1NCE IoT C SDK

## Overview
**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.
**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.

## License
The 1NCE IoT C-SDK is licensed under the [MIT](./LICENSE) open source license.

## Features
1NCE IoT C SDK allows customers a seamless setup and use of all features as part of 1NCE Connectivity Suite.
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:

<p align="center"><img src="./docs/doxygen/images/overview.png"><br>
</p>

### MQTT Onboarding
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.

<p align="center"><img src="./docs/doxygen/images/mqtt_onboarding.png" width="70%"><br>
</p>

### CoAP Onboarding
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.
### Device Authenticator (CoAP)
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.

<p align="center"><img src="./docs/doxygen/images/coap_onboarding.png" width="70%"><br>
<p align="center"><img src="./docs/doxygen/images/coap_device_authenticator.png" width="70%"><br>
</p>

More details about device onboarding are available at [1NCE Developer Hub (SIM-as-an-Identity)](https://help.1nce.com/dev-hub/docs/connectivity-suite-sim-identity).
More details about device authentification are available at [1NCE Developer Hub (SIM-as-an-Identity)](https://help.1nce.com/dev-hub/docs/connectivity-suite-sim-identity).

### Translation Service (Binary conversion language)
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.
### Energy Saver (Binary conversion language)
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.

<p align="center"><img src="./docs/doxygen/images/translation_service.png"><br>
<p align="center"><img src="./docs/doxygen/images/energy_saver.png"><br>
</p>

Check [1NCE Developer Hub (Translation service)](https://help.1nce.com/dev-hub/docs/connectivity-suite-translation-service) for further explantion of the translation template creation.
Check [1NCE Developer Hub (Energy Saver)](https://help.1nce.com/dev-hub/docs/connectivity-suite-translation-service) for further explantion of the translation template creation.

## Versioning
1NCE IoT C SDK releases will follow a [Semantic versioning](https://en.wikipedia.org/wiki/Software_versioning#Semantic_versioning)
Expand All @@ -48,40 +43,33 @@ Given a version number MAJOR.MINOR.PATCH, increment the:

**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.
* 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 Scenario

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 Example shows how to set up and integrate 1nce SDK in Embedded Application written in C.

The Examples used FreeRTOS as First Version.


### Prerequisite Tasks

The SDK requires using a 1NCE SIM card with a connected AWS account configured through [1NCE Portal](https://portal.1nce.com/). 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.

#### Contents
* [Step 1: Clone Repository](#Step1_Clone_Repository)
* [Step 2: Implement abstract functions](#Step2_Implement_abstract_functions)
* [Step 3: Integrate SDK in your Application](#Step3_Integrate_SDK_in_your_Application)
* [Step 4: Run your Application](#Step4_Run_your_Application)
* [Step 1: Clone Repository](#Step1_Clone_Repository)
* [Step 2: Implement abstract functions](#Step2_Implement_abstract_functions)
* [Step 3: Integrate SDK in your Application](#Step3_Integrate_SDK_in_your_Application)
* [Step 4: Run your Application](#Step4_Run_your_Application)
### Step 1: Clone Repository
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
git clone https://github.com/1NCE-GmbH/1nce-iot-c-sdk.git --recurse-submodules
```
Using SSH
```
git clone [email protected]:1NCE-GmbH/1nce-sdk.git --recurse-submodules
git clone [email protected]:1NCE-GmbH/1nce-iot-c-sdk.git --recurse-submodules
```
If you have downloaded the repo without using the ```--recurse-submodules``` argument, you need to run:
```
Expand All @@ -90,74 +78,80 @@ git submodule update --init --recursive
### Step 2: Implement abstract functions
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
* nce_os_tls_connect
* nce_os_tls_send
* nce_os_tls_recv
* nce_os_tls_disconnect

To implement your functions, we recommand to follow the examples.
#### Examples Quectel BG96
#### 1. Offload Certificate:
for the Implementation we use the psuedo code:
To implement your functions, we recommend following the example.

#### Example Quectel BG96

For the Implementation, we use the pseudocode:
```
TlsTransportStatus_t TLS_Connect_impl(NetworkContext_t *pNetworkContext,
const char *pHostName, uint16_t port,
const NetworkCredentials_t *pNetworkCredentials,
uint32_t receiveTimeoutMs,
uint32_t sendTimeoutMs)
int tls_connect_impl(OSNetwork_t osnetwork,OSEndPoint_t nce_oboarding)
```
1. [configure the onboarding socket](https://github.com/1NCE-GmbH/blueprint-freertos/blob/94b2f0a364c958df57fe75e969aeef674fece6ba/libraries/3rdparty/NCE_SDK/nce_bg96_configuration.c#L41)
2. Create TCP Socket.
3. Connect the socket with the endpoint ```ONBOARDING_ENDPOINT``` in port ```ONBOARDING_PORT```
3. Connect the socket with the endpoint
```
int32_t TLS_send_impl(NetworkContext_t *pNetworkContext,
const void *pBuffer,
size_t bytesToSend)
int32_t tls_send_impl(OSNetwork_t osnetwork,
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)
int32_t tls_recv_impl( OSNetwork_t osnetwork,
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)
int tls_disconnect(OSNetwork_t osnetwork)
```
1. Call socket shutdown function to close the connection
2. Free mbedTLS contexts.
#### 2. Onload Certificate:
For the Onload Certificate, we can refer to [using_mbedtls in FreeRTOS Demo](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo/blob/main/source/coreMQTT/using_mbedtls.c)

### Step 3: Integrate SDK in your Application

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;
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.

```
#### 1. MQTT
The object can then be passed to ```nce_sdk``` function as follows:
OSNetwork_t xOSNetwork= { 0 };
```
nce_sdk(&xtls_api,1);
os_network_ops_t osNetwork={.os_socket=&xOSNetwork,
.nce_os_tls_connect=tls_connect_impl,
.nce_os_tls_send=tls_send_impl,
.nce_os_tls_recv=tls_recv_impl,
.nce_os_tls_disconnect=tls_disconnect_impl};
```
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.

#### 2. CoAP
With CoAP protocol (using DTLS) you need just to change the 1 to 0
#### 1. CoAP
With CoAP protocol (using DTLS) you can call ```os_auth```
```
nce_sdk(&xtls_api,0);
static int prvInitializeClientCredential( TLSContext_t * pxCtx )
{
DEVICE_ONBOARDED=false;
DtlsKey_t nceKey={0};
int result= os_auth(&osNetwork,&nceKey);
BaseType_t xResult = CKR_OK;
/* Attach the client PSK the DTLS configuration. */
if( 0 == xResult )
{
/*Use PSK */
size_t psk_len = strlen(nceKey.Psk);
size_t psk_identity_len = strlen(nceKey.PskIdentity);
xResult = mbedtls_ssl_conf_psk( &pxCtx->xMbedSslConfig,
&(nceKey.Psk),strlen(nceKey.Psk),&(nceKey.PskIdentity),psk_identity_len);
}
DEVICE_ONBOARDED=true;
return xResult;
}
```
then we can have the pre-shared key and identity stored in ```psk``` and ```pskIdentity```
then we can have ```psk``` and ```pskIdentity``` stored in ```DtlsKey_t``` struct.

#### 3. Translation service
#### 2. Energy Saver

```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:
```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:

<p align="center"><img src="./docs/doxygen/images/translation_template_1.png"><br>
</p>
Expand All @@ -170,33 +164,33 @@ 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";
/* 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 faild */
status=os_energy_save(pcTransmittedString,selector, 3,battery_level,signal_strength,software_version);
/* Template information */
char type[] = "UUS";
int bytelength[]={1,1,5};
```
The resulting packet can then be sent to the energy saver for further processing

uint8_t selector = 1 /* select case 1 */;
int location=1;
uint8_t packet[8];
#### 3. LOG Interface

/* 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 );
Complete the following macros in ```log_interface.h```
```
#define NceOSLogInfo( format, ... )
#define NceOSLogDebug( format, ... )
#define NceOSLogError( format, ... )
#define NceOSLogWarn( format, ... )
```
The resulting packet can then be sent to the translation service for further processing
If you are using FreeRTOS you can just use the macro ```#define FREERTOS```

### Step 4: Run your Application
Run your code in ISO C99
Run your code in ISO C90

## Generating documentation
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:
Expand Down
9 changes: 4 additions & 5 deletions docs/doxygen/Doxyfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ PROJECT_NAME = "1NCE IoT C-SDK"
# could be handy for archiving the generated documentation or if some version
# control system is used.

PROJECT_NUMBER = 1.0.0
PROJECT_NUMBER = 2.0.0

# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
Expand Down Expand Up @@ -1020,10 +1020,9 @@ EXAMPLE_RECURSIVE = NO
# that contain images that are to be included in the documentation (see the
# \image command).

IMAGE_PATH = ./docs/doxygen/images/mqtt_onboarding.png \
./docs/doxygen/images/overview.png \
./docs/doxygen/images/translation_service.png \
./docs/doxygen/images/coap_onboarding.png
IMAGE_PATH = ./docs/doxygen/images/overview.png \
./docs/doxygen/images/energy_saver.png \
./docs/doxygen/images/coap_device_authenticator.png

# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
Expand Down
Binary file removed docs/doxygen/images/coap_onboarding.png
View file
Binary file not shown.
Binary file added docs/doxygen/images/energy_saver.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/doxygen/images/mqtt_onboarding.png
View file
Binary file not shown.
Binary file modified docs/doxygen/images/overview.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed docs/doxygen/images/translation_service.png
View file
Binary file not shown.
27 changes: 10 additions & 17 deletions docs/doxygen/pages.dox
View file
Original file line number Diff line number Diff line change
@@ -1,34 +1,27 @@
/**
@mainpage Overview
@brief The 1NCE IoT SDK for Embedded C provides demonstration code for different functionality of 1NCE Connectivity Suite.
@brief The 1NCE IoT SDK for Embedded C provides demonstration code for different functionality of 1NCE OS.

> 1NCE IoT SDK allow customers a seamless setup and use of all features as part of 1NCE Connectivity Suite.
> 1NCE IoT SDK allow customers a seamless setup and use of all features as part of 1NCE OS.

@section features Features
The following services are part of this SDK:
- [Use 1NCE Data Broker] - [Data Broker](https://help.1nce.com/dev-hub/docs/connectivity-suite-data-broker)
- [SIM as an Identity] - [SIM-as-Identity](https://help.1nce.com/dev-hub/docs/connectivity-suite-sim-identity)
- [Translation Service] - [Translation Service](https://help.1nce.com/dev-hub/docs/connectivity-suite-translation-service)
- [Energy Saver] - [Energy saver](https://help.1nce.com/dev-hub/docs/connectivity-suite-translation-service)

@image html overview.png 1NCE IoT C SDK Overview width=50%

@section MQTT_onboarding MQTT Onboarding
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 MQTT context, this can for example determine the topics that the device can Publish and/or Subscribe to.
@image html mqtt_onboarding.png MQTT Device Onboarding Flow width=50%
@section coap_onboarding CoAP Onboarding
The 1NCE IoT c SDK also provides onboarding credentials for IoT devices communicating

@section coap_Device_Authenticator CoAP device Authenticator
The 1NCE IoT c SDK 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 secure connection
to the CoAP endpoint of 1NCE Data Broker
@image html coap_onboarding.png CoAP DTLS Onboarding Flow width=50%
@section translation_service Translation Service (Binary conversion language)
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.
@image html coap_device_authenticator.png CoAP DTLS Authentication Flow width=50%
@section Energy_saver Energy Saver (Binary conversion language)
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.
@image html translation_service.png translation service width=50%
@image html energy_saver.png Energy Saver width=50%

*/
Loading

0 comments on commit be8230e

Please sign in to comment.