GitHub - aws/Jobs-for-AWS-IoT-embedded-sdk: Client library for using AWS IoT Jobs service on embedded devices (original) (raw)

AWS IoT Jobs library

API Documentation Pages for current and previous releases of this library can be found here

The AWS IoT Jobs library helps you notify connected IoT devices of a pendingJob. A Job can be used to manage your fleet of devices, update firmware and security certificates on your devices, or perform administrative tasks such as restarting devices and performing diagnostics. It interacts with theAWS IoT Jobs serviceusing MQTT, a lightweight publish-subscribe protocol. This library provides a convenience API to compose and recognize the MQTT topic strings used by the Jobs service. The library is written in C compliant with ISO C90 and MISRA C:2012, and is distributed under the MIT Open Source License.

This library has gone through code quality checks including verification that no function has aGNU Complexityscore over 10, and checks against deviations from mandatory rules in theMISRA coding standard. Deviations from the MISRA C:2012 guidelines are documented under MISRA Deviations. This library has also undergone both static code analysis fromCoverity, and validation of memory safety with theCBMC bounded model checker.

See memory requirements for this libraryhere.

AWS IoT Jobs v1.5.1source codeis part of theFreeRTOS 202406.00 LTSrelease.

Building the Jobs library

A compiler that supports C99 or later such as gcc is required to build the library.

Additionally, coreJSON is required for parsing. To build the library, first run:

git clone https://github.com/FreeRTOS/coreJSON.git --depth 1 --branch v3.2.0

Given an application in a file named example.c, gcc can be used like so:

gcc -I source/include -I coreJSON/source/include example.c coreJSON/source/core_json.c source/jobs.c -o example

gcc can also produce an object file to be linked later:

gcc -I source/include -I coreJSON/source/include -c source/jobs.c

CBMC

To learn more about CBMC and proofs specifically, review the training materialhere.

The test/cbmc directory contains CBMC proofs.

In order to run these proofs you will need to install CBMC and other tools by following the instructionshere.

Reference example

The AWS IoT Device SDK for Embedded C repository contains a demo using the jobs library on a POSIX platform.https://github.com/aws/aws-iot-device-sdk-embedded-C/tree/main/demos/jobs/jobs_demo_mosquitto

Documentation

Existing Documentation

For pre-generated documentation, please see the documentation linked in the locations below:

Location
AWS IoT Device SDK for Embedded C
FreeRTOS.org

Note that the latest included version of the AWS IoT Jobs library may differ across repositories.

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:

doxygen docs/doxygen/config.doxyfile

Building unit tests

Platform Prerequisites

For running unit tests
- C99 compiler like gcc
- CMake 3.13.0 or later
- Ruby 2.0.0 or later is additionally required for the Unity test framework (that we use).
For running the coverage target, lcov is additionally required.

Steps to build Unit Tests

Create build directory: mkdir build
Run cmake while inside build directory: cmake -S test/ -B build/
Change to build directory: cd build
Run this command to build the library and unit tests: make all
The generated test executables will be present in build/bin/tests folder.
Run ctest to execute all tests and view the test run summary.

Contributing

See CONTRIBUTING.md for information on contributing.