Skip to content

Commit

Permalink
Update the README file
Browse files Browse the repository at this point in the history
  • Loading branch information
@Skptak
Skptak committed Sep 2, 2023
1 parent 675c6ef commit 6bc6e06
Showing 1 changed file with 75 additions and 53 deletions.
128 changes: 75 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,76 +1,97 @@
## AWS IoT Jobs library

The AWS IoT Jobs library helps you notify connected IoT devices of a
pending [Job](https://freertos.org/jobs/jobs-terminology.html). 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 the
[AWS IoT Jobs service](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
using 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](LICENSE).

This library has gone through code quality checks
including verification that no function has a [GNU Complexity
](https://www.gnu.org/software/complexity/manual/complexity.html)
score over 8, and checks against deviations
from mandatory rules in the [MISRA coding standard
](https://www.misra.org.uk).
Deviations from the MISRA C:2012 guidelines are documented under [MISRA
Deviations](MISRA.md). This library has also undergone both static code
analysis from [Coverity](https://scan.coverity.com/), and validation of
memory safety with the [CBMC bounded model checker](https://www.cprover.org/cbmc/).

See memory requirements for this library [here](./docs/doxygen/include/size_table.md).
**[API Documentation Pages for current and previous releases of this library can be found here](https://aws.github.io/Jobs-for-AWS-IoT-embedded-sdk/)**

**AWS IoT Jobs v1.3.0 [source code](https://github.com/aws/Jobs-for-AWS-IoT-embedded-sdk/tree/v1.3.0/source) is part of the [FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS) release.**

**AWS IoT Jobs v1.1.0 [source code](https://github.com/aws/Jobs-for-AWS-IoT-embedded-sdk/tree/v1.1.0/source) is part of the [FreeRTOS 202012.01 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.01-LTS) release.**
The AWS IoT Jobs library helps you notify connected IoT devices of a pending
[Job](https://freertos.org/jobs/jobs-terminology.html). 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 the
[AWS IoT Jobs service](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
using 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](LICENSE).

This library has gone through code quality checks including verification that no
function has a
[GNU Complexity ](https://www.gnu.org/software/complexity/manual/complexity.html)
score over 8, and checks against deviations from mandatory rules in the
[MISRA coding standard ](https://www.misra.org.uk). Deviations from the MISRA
C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This
library has also undergone both static code analysis from
[Coverity](https://scan.coverity.com/), and validation of memory safety with the
[CBMC bounded model checker](https://www.cprover.org/cbmc/).

See memory requirements for this library
[here](./docs/doxygen/include/size_table.md).

**AWS IoT Jobs v1.3.0
[source code](https://github.com/aws/Jobs-for-AWS-IoT-embedded-sdk/tree/v1.3.0/source)
is part of the
[FreeRTOS 202210.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202210.00-LTS)
release.**

**AWS IoT Jobs v1.1.0
[source code](https://github.com/aws/Jobs-for-AWS-IoT-embedded-sdk/tree/v1.1.0/source)
is part of the
[FreeRTOS 202012.01 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202012.01-LTS)
release.**

## Building the Jobs library

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

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

Given an application in a file named `example.c`, *gcc* can be used like so:
```bash
gcc -I source/include example.c source/jobs.c -o example
```

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

```bash
gcc -I source/include -c source/jobs.c
```

## CBMC

To learn more about CBMC and proofs specifically, review the training material [here](https://model-checking.github.io/cbmc-training).
To learn more about CBMC and proofs specifically, review the training material
[here](https://model-checking.github.io/cbmc-training).

The `test/cbmc/proofs` directory contains CBMC proofs.

In order to run these proofs you will need to install CBMC and other tools by following the instructions [here](https://model-checking.github.io/cbmc-training/installation.html).
In order to run these proofs you will need to install CBMC and other tools by
following the instructions
[here](https://model-checking.github.io/cbmc-training/installation.html).

## Reference example

The AWS IoT Device SDK for Embedded C repository contains a demo using
the jobs library on a POSIX platform.
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](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) |
For pre-generated documentation, please see the documentation linked in the
locations below:

| Location |
| :--------------------------------------------------------------------------------------------------------------------------: |
| [AWS IoT Device SDK for Embedded C](https://github.com/aws/aws-iot-device-sdk-embedded-C#releases-and-documentation) |
| [FreeRTOS.org](https://freertos.org/Documentation/api-ref/jobs-for-aws-iot-embedded-sdk/docs/doxygen/output/html/index.html) |

Note that the latest included version of the AWS IoT Jobs library may differ across repositories.
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 pages, please run the following command from the root of this
repository:

```shell
doxygen docs/doxygen/config.doxyfile
Expand All @@ -80,34 +101,34 @@ doxygen docs/doxygen/config.doxyfile

### Checkout Unity Submodule

By default, the submodules in this repository are configured with
`update=none` in [.gitmodules](.gitmodules) to avoid increasing
clone time and disk space usage of other repositories that submodule
this repository.
By default, the submodules in this repository are configured with `update=none`
in [.gitmodules](.gitmodules) to avoid increasing clone time and disk space
usage of other repositories that submodule this repository.

To build unit tests, the submodule dependency of Unity is required. Use the
following command to clone the submodule:

To build unit tests, the submodule dependency of Unity is required. Use
the following command to clone the submodule:
```
git submodule update --checkout --init --recursive --test/unit-test/Unity
```

### Platform Prerequisites

- For running unit tests
- C90 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).
- C90 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

1. Go to the root directory of this repository. (Make
sure that the **Unity** submodule is cloned as described
[above](#checkout-unity-submodule).)
1. Go to the root directory of this repository. (Make sure that the **Unity**
submodule is cloned as described [above](#checkout-unity-submodule).)

1. Create build directory: `mkdir build && cd build`

1. Run *cmake* while inside build directory: `cmake -S ../test`
1. Run _cmake_ while inside build directory: `cmake -S ../test`

1. Run this command to build the library and unit tests: `make all`

Expand All @@ -117,4 +138,5 @@ sure that the **Unity** submodule is cloned as described

## Contributing

See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing.
See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on
contributing.

0 comments on commit 6bc6e06

Please sign in to comment.