Skip to content

Latest commit

 

History

History
138 lines (92 loc) · 7.99 KB

README.md

File metadata and controls

138 lines (92 loc) · 7.99 KB
Raw

Omnicore Device SDK for Embedded C

Note: Ported From GCP Iot Core Embedded C SDK GCP IoT Device SDK for Embedded C GitHub repository

The Omnicore Device SDK for Embedded C is an easy-to-port, open-source C library that connects low-end IoT devices to Omnicore.

The Device SDK supports concurrent Pub/Sub traffic on a non-blocking socket implementation that runs on POSIX, RTOS, and no-OS devices. A Board Support Package (BSP) facilitates portability and provides platform-specific implementations through a set of functions and directories. The BSP helps implement crypto and time functions, networking, Transport Layer Security (TLS), memory management, and random number generation—without working through MQTT internals.

For more details, see the user guide in the docs directory.

Changes From GCP IOT Core

Observation:

The base64 jwt encoded token generated by the iot core c sdk was having extra padding (=) characters which is against RFC 7515, Page 6(https://www.rfc-editor.org/rfc/rfc7515) .Our systems expect a token following rfc 7515 and rfc 7519 so the padding characters were illegal. 

Changes:

Changed the iotc_jwt.c file to remove trailing padding (=) characters before signing. 

Usage:

Same as before , also the example  iot_core_mqtt_client has an added parameter -i for specifying host name for mqtt connections.

Source

To get the source, clone from the master branch of the Omnicore IoT Device SDK for Embedded C GitHub repository:

git clone https://github.com/korewireless/Omnicore-C-Device-SDK.git --recurse-submodules

Directory structure

  • bin: Executables and libraries produced by a build.
  • doc: Documentation: Doxygen references, user guide, and porting guide.
  • examples: Example source with makefiles. After you build with make, this directory will also contain the example executables.
  • include: Header files of the Device SDK API. You must add this directory to the header include path when compiling your application against the source.
  • include/bsp: Header files of the Board Support Package (BSP). Functions declared here must be defined in a device-specific BSP implementation. When compiling your BSP source, make sure this directory is on the include path.
  • make: Build system configuration files.
  • obj: Object files generated during a build.
  • res: Resource files (for example, trusted root CA certificates.)
  • src: The source files of the Device SDK. A BSP implementation is provided for POSIX.
  • third_party: Third-party open-source components.
  • tools: Scripts used by the maintainers of the repository.

Building

The default build tool for the Device SDK is make. It invokes GCC to produce a native build on a POSIX host. This serves as the default development environment on Ubuntu.

Run the following command to build the Device SDK:

make

The source can be cross-compiled to other target platforms via custom toolchains and the makefile, or with a specific device SDK’s IDE. For more information, see the porting guide.

Building a TLS static library

By default, the Device SDK is built with secure connection support and thus requires a third-party TLS implementation to link against. When executing make, the build system defaults to mbedTLS.

As a result, the make and make IOTC_BSP_TLS=mbedtls commands are synonymous.

You can also configure the make system to build a library that uses wolfSSL.

make clean
make IOTC_BSP_TLS=wolfssl

The value of IOTC_BSP_TLS determines which script is run.

The mbedTLS build script includes a git clone and branch checkout of the mbedTLS source (upon confirmation of the license agreement). However, the wolfSSL build script requires you to clone the repository yourself. When you run make IOTC_BSP_TLS=wolfSSL, instructions are provided for cloning the repository.

For more details on running the scripts, see Security.

Building and executing tests

To build and execute all tests:

  1. Run git submodule init from the project's root directory to initialize all test dependencies.
  2. Run git submodule update from the project's root directory to clone all submodules.
  3. Run make tests.

By default, test execution is the final step of the tests build process. You can also execute the tests manually.

cd bin/{host_os}/tests
./iotc_utests
./iotc_gtests
./iotc_itests

Building the examples

Before building the examples, build both the Device SDK static library and a TLS library, as described in the preceding sections. Then, complete the steps below to run the examples.

  1. Create a project, registry and device in Omnicore.
  2. Create Omnicore device credentials.
  3. Follow the steps in the examples README.md files to provision the device credentials and build the client applications.
  4. Run make in the examples folder. The make process automatically downloads the Omnicore Root CA PEM file to the example directories. The file enables TLS when communicating with Omnicore.

To securely connect to Omnicore, a root CA .pem file must be in the current working directory of the example executables. By default, the file is in res/trusted_RootCA_certs/roots.pem and contains two certificates that validate Omnicore credentials. The make process automatically moves this file from res/trusted_RootCA_certs/roots.pem to the correct location.

To maintain a secure connection with Omnicore, we strongly recommend that you perform frequent security-related firmware updates.

Cross-compilation

Follow the steps below to perform the cross-compilation process.

  • Extend the build system with a new cross-compilation preset in the file make/mt-config/mt-presets.mk.
  • Create a set of files that represent the Board Support Package (BSP) implementation you've written for your platform. Store these in the directory src/bsp/platform/TARGET_PLATFORM.
  • Build a TLS BSP implementation to invoke the TLS SDK for your platform. Store these in a new directory src/bsp/tls/TARGET_TLS_SOLUTION.
  • Build a Cryptography BSP implementation to handle key signatures of JWTs on your target platform in the directory src/bsp/crypto/TARGET_CRYPTO_SOLUCTION.

For more details on the cross-compilation process, see the porting guide.

Security

The Device SDK supports secure connection through a third-party TLS library. The Device SDK is tested against mbedTLS and wolfSSL.

This repository does not directly include TLS libraries; you can clone the TLS git repositories and place them in the third_party/tls/mbedtls and third_party/tls/wolfssl directories, respectively. Running make without any parameters will start a build that includes git checkout, build configuration, and compilation of the mbedTLS library.

The Device SDK supports other TLS libraries through the BSP TLS API. For information about configuring the build process to work with your preferred library, see the porting guide in doc/porting_guide.md. Additionally, check the user guide doc/user_guide.md to make sure your TLS implementation meets the security requirements to connect to Omnicore.

Learn more

Review the following documentation:

License

Copyright 2023 KORE Wireless

Licensed under the BSD 3-Clause license.

For more information, see LICENSE.md.