-
Notifications
You must be signed in to change notification settings - Fork 61
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Cellular] Use FreeRTOS Cellular Interface to replace the prefix Lab-…
…Project (#39) * [Cellular] Use FreeRTOS Cellular Interface to replace Lab-Project-FreeRTOS-Cellular-Library * [Cellular] Update the description. * Add CHANGELOG.md
- Loading branch information
1 parent
cefe8c6
commit 07521b6
Showing
2 changed files
with
71 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| # Change Log for FreeRTOS Cellular Interface Library | ||
|
|
||
| ## v1.0.0 (September 2021) | ||
|
|
||
| This is the first release of the FreeRTOS Cellular Interface library in this repository. | ||
|
|
||
| The FreeRTOS Cellular Interface library provides an implementation of the standard AT commands for the [3GPP TS v27.007](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1515) and support for the 3 cellular modems [Quectel BG96](https://www.quectel.com/product/bg96.htm), [Sierra Wireless HL7802](https://www.sierrawireless.com/products-and-solutions/embedded-solutions/products/hl7802/) and [U-Blox Sara-R4](https://www.u-blox.com/en/product/sara-r4-series). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,29 @@ | ||
| # FreeRTOS Labs - FreeRTOS Cellular Interface Library | ||
| # FreeRTOS Cellular Interface | ||
|
|
||
| ## On this page: | ||
| * [Introduction](#Introduction) | ||
| * [Getting Started](#Getting-Started) | ||
| * [Download the source code](#Download-the-source-code) | ||
| * [Folder Structure](#Folder-Structure) | ||
| * [API documentation](#API-documentation) | ||
| * [Configure and Build](#Configure-and-build-the-libraries) | ||
| * [Integrate Cellular Interface with MCU platforms](#Integrate-FreeRTOS-Cellular-Library-with-MCU-platforms) | ||
| * [Integrate FreeRTOS Cellular Interface with MCU platforms](#Integrate-FreeRTOS-Cellular-Interface-with-MCU-platforms) | ||
| * [Adding support for new cellular modems](#Adding-support-for-new-cellular-modems) | ||
| * [Building Unit Tests](#Building-Unit-Tests) | ||
| * [Generating documentation](#Generating-documentation) | ||
| * [Contributing](#Contributing) | ||
|
|
||
| ## Introduction | ||
|
|
||
| The FreeRTOS Cellular Library exposes the capability of a few popular cellular modems through a uniform API. Currently, this Labs project contains libraries for these three cellular modems. | ||
| The FreeRTOS Cellular Interface exposes the capability of a few popular cellular modems through a uniform API. Currently, this repository contains libraries for these three cellular modems. | ||
|
|
||
| * [Quectel BG96](https://www.quectel.com/product/lte-bg96-cat-m1-nb1-egprs/) | ||
| * [Sierra Wireless HL7802](https://www.sierrawireless.com/products-and-solutions/embedded-solutions/products/hl7802/) | ||
| * [U-Blox Sara-R4](https://www.u-blox.com/en/product/sara-r4-series) | ||
|
|
||
| The current version of the FreeRTOS Cellular Library encapsulates the TCP stack offered by those cellular modems. They all implement the same uniform [Cellular Library API](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/raw/main/doc/document/cellular.zip). That API hides the complexity of AT commands, and exposes a socket-like interface to C programmers. | ||
| The current version of the FreeRTOS Cellular Interface encapsulates the TCP stack offered by those cellular modems. They all implement the same uniform [Cellular Library API](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/cellular_api.h). That API hides the complexity of AT commands, and exposes a socket-like interface to C programmers. | ||
|
|
||
| Even though applications can choose to use the FreeRTOS Cellular Library API directly, the API is not designed for such a purpose. In a typical FreeRTOS system, applications use high level libraries, such as the [coreMQTT](https://github.com/FreeRTOS/coreMQTT) library and the [coreHTTP](https://github.com/FreeRTOS/coreHTTP) library, to communicate with other end points. Those high level libraries use an abstract interface, the [Transport Interface](https://github.com/FreeRTOS/coreMQTT/blob/main/source/interface/transport_interface.h), to send and receive data. A Transport Interface can be implemented on top of the FreeRTOS Cellular Library. The [FreeRTOS Cellular Demo](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo) project uses such an implementation. | ||
| Even though applications can choose to use the FreeRTOS Cellular Interface API directly, the API is not designed for such a purpose. In a typical FreeRTOS system, applications use high level libraries, such as the [coreMQTT](https://github.com/FreeRTOS/coreMQTT) library and the [coreHTTP](https://github.com/FreeRTOS/coreHTTP) library, to communicate with other end points. Those high level libraries use an abstract interface, the [Transport Interface](https://github.com/FreeRTOS/coreMQTT/blob/main/source/interface/transport_interface.h), to send and receive data. A Transport Interface can be implemented on top of the FreeRTOS Cellular Interface. | ||
|
|
||
| Most cellular modems implement more or less the AT commands defined by the [3GPP TS v27.007](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1515) standard. This project provides an [implementation](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/main/common) of such standard AT commands in a [reusable common component](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/master/common). The three Cellular libraries in this project all take advantage of that common code. The library for each modem only implements the vendor-specific AT commands, then exposes the complete Cellular API. | ||
| Most cellular modems implement more or less the AT commands defined by the [3GPP TS v27.007](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1515) standard. This project provides an implementation of such standard AT commands in a [reusable common component](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common). The three Cellular libraries in this project all take advantage of that common code. The library for each modem only implements the vendor-specific AT commands, then exposes the complete Cellular API. | ||
|
|
||
| The common component that implements the 3GPP TS v27.007 standard has been written in compliance of the following code quality criteria: | ||
|
|
||
|
|
@@ -33,61 +34,45 @@ The common component that implements the 3GPP TS v27.007 standard has been writt | |
|
|
||
| ### Download the source code | ||
|
|
||
| The source code can be downloaded from the FreeRTOS labs or by itself. | ||
|
|
||
| To clone using HTTPS: | ||
|
|
||
| ``` | ||
| git clone https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library.git | ||
| git clone https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface.git | ||
| ``` | ||
|
|
||
| Using SSH: | ||
|
|
||
| ``` | ||
| git clone [email protected]/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library.git | ||
| git clone [email protected]/FreeRTOS/FreeRTOS-Cellular-Interface.git | ||
| ``` | ||
|
|
||
| ### Folder structure | ||
|
|
||
| At the root of this repository are these folders: | ||
|
|
||
| * include : Cellular API definitions | ||
| * common : reusable common code that implements the standard AT commands defined by 3GPP TS v27.007 | ||
| * source/include : Cellular API definitions | ||
| * source/include/common : reusable common code that implements the standard AT commands defined by 3GPP TS v27.007 | ||
| * modules : vendor-specific code that implements non-3GPP AT commands for each cellular modem | ||
| * doc : documentations | ||
|
|
||
| ### API documentation | ||
|
|
||
| The pre-generated doxygen documents can be found in [**“doc/document/cellular.zip"**](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/raw/main/doc/document/cellular.zip). After unzipping it, the **“celluar/index.html”** file is the entry page. | ||
|
|
||
| There is dedicated documentation for the common component that implements the standard AT commands defined by 3GPP TS v27.007. Find that documentation in [**“doc/document/cellular_common.zip”**](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/raw/main/doc/document/cellular_common.zip). | ||
|
|
||
| ### Configure and build the libraries | ||
|
|
||
| The FreeRTOS Cellular Library should be built as part of an application. In order to build a library as part of an application, certain configurations must be provided. The [Lab-Project-FreeRTOS-Cellular-Demo](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo) project provides an [example](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo/blob/master/source/cellular/bg96/cellular_config.h) of how to configure the build. More information can be found within the [Cellular API References](https://www.freertos.org/Documentation/api-ref/cellular/cellular_config.html). | ||
|
|
||
| Please refer to the README of [Lab-Project-FreeRTOS-Cellular-Demo](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo) project for more information. | ||
| * docs : documentations | ||
|
|
||
| ## Integrate FreeRTOS Cellular Library with MCU platforms | ||
| ## Integrate FreeRTOS Cellular Interface with MCU platforms | ||
|
|
||
| The FreeRTOS Cellular Library runs on MCUs. It use an abstracted interface - the [Comm Interface](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/blob/master/include/cellular_comm_interface.h), to communicate with cellular modems. A Comm Interface must be implemented as well on the MCU platform. The most common implementations of the Comm Interface are over UART hardware, but it can be implemented over other physical interfaces such as SPI as well. The documentation of the Comm Interface is found within the [Cellular API References](https://www.freertos.org/Documentation/api-ref/cellular/comm_if.html). These are example implementations of the Comm Interface: | ||
| The FreeRTOS Cellular Interface runs on MCUs. It uses an abstracted interface - the [Comm Interface](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/interface/cellular_comm_interface.h), to communicate with cellular modems. A Comm Interface must be implemented as well on the MCU platform. The most common implementations of the Comm Interface are over UART hardware, but it can be implemented over other physical interfaces such as SPI as well. The documentation of the Comm Interface is found within the [Cellular API References](https://www.freertos.org/Documentation/api-ref/cellular/comm_if.html). These are example implementations of the Comm Interface: | ||
|
|
||
| * [FreeRTOS windows simulator comm interface](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo/blob/master/source/cellular/comm_if_windows.c) | ||
| * FreeRTOS windows simulator comm interface | ||
| * [FreeRTOS Common IO UART comm interface](https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/st/boards/stm32l475_discovery/ports/comm_if/comm_if_uart.c) | ||
| * [STM32 L475 discovery board comm interface](https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/st/boards/stm32l475_discovery/ports/comm_if/comm_if_st.c) | ||
| * [Sierra Sensor Hub board comm interface](https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/sierra/boards/sensorhub/ports/comm_if/comm_if_sierra.c) | ||
|
|
||
| The FreeRTOS Cellular Library uses kernel APIs for task synchronization and memory management. Please refer to "cellular/cellular_platform.html" after unzipping the doc to see the needed API. | ||
|
|
||
| The [Lab-Project-FreeRTOS-Cellular-Demo](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo) project has implemented such kernel APIs by using FreeRTOS primitives. If the target platform is FreeRTOS, [this implementation](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo/blob/master/source/cellular/cellular_platform.c) provides a pre-integrated interface. If your platform is not FreeRTOS, you need to re-implement the APIs contained in [this file](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Demo/blob/master/source/cellular/cellular_platform.c). | ||
| The FreeRTOS Cellular Interface uses kernel APIs for task synchronization and memory management. | ||
|
|
||
| ## Adding support for new cellular modems | ||
|
|
||
| FreeRTOS Labs now supports AT commands, TCP offloaded Cellular abstraction Layer. In order to add support for a new cellular modem, the developer can use the [common component](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/master/common) that has already implemented the 3GPP standard AT commands. | ||
| FreeRTOS Cellular Interface now supports AT commands, TCP offloaded Cellular abstraction Layer. In order to add support for a new cellular modem, the developer can use the [common component](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common) that has already implemented the 3GPP standard AT commands. | ||
|
|
||
| In order to port the [common component](https://www.freertos.org/Documentation/api-ref/cellular_common/index.html): | ||
|
|
||
| 1. Implement the cellular modem porting interface defined in [cellular_common_portable.h](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/blob/main/common/include/cellular_common_portable.h). ([Documentation](https://www.freertos.org/Documentation/api-ref/cellular_common/cellular__common__portable_8h.html)) | ||
| 1. Implement the cellular modem porting interface defined in [cellular_common_portable.h](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common/cellular_common_portable.h). | ||
| 2. Implement the subset of Cellular Library APIs that use vendor-specific (non-3GPP) AT commands. The APIs to be implemented are the ones not marked with an “o” in [this table](https://www.freertos.org/Documentation/api-ref/cellular_common/cellular_common_APIs.html). | ||
| 3. Implement Cellular Library callback functions that handle vendor-specific (non-3GPP) Unsolicited Result Code (URC). The URC handlers to be implemented are the ones not marked with an “o” in [this table](https://www.freertos.org/Documentation/api-ref/cellular_common/cellular_common_URC_handlers.html). | ||
|
|
||
|
|
@@ -96,7 +81,48 @@ It is recommended that you start by cloning the implementation of one of the exi | |
|
|
||
| Current Example Implementations: | ||
|
|
||
| * [Quectel BG96](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/master/modules/bg96) | ||
| * [Sierra Wireless HL7802](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/main/modules/hl7802) | ||
| * [U-Blox Sara-R4](https://github.com/FreeRTOS/Lab-Project-FreeRTOS-Cellular-Library/tree/main/modules/sara_r4) | ||
| * [Quectel BG96](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/modules/bg96) | ||
| * [Sierra Wireless HL7802](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/modules/hl7802) | ||
| * [U-Blox Sara-R4](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/modules/sara_r4) | ||
|
|
||
| ## Building Unit Tests | ||
|
|
||
| ### Checkout CMock 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 (like [amazon-freertos](https://github.com/aws/amazon-freertos) that submodules this repository). | ||
|
|
||
|
|
||
| To build unit tests, the submodule dependency of CMock is required. Use the following command to clone the submodule: | ||
| ``` | ||
| git submodule update --checkout --init --recursive --test/unit-test/CMock | ||
| ``` | ||
|
|
||
| ### Platform Prerequisites | ||
|
|
||
| - For building the unit tests, **CMake 3.13.0** or later and a **C90 compiler**. | ||
| - For running unit tests, **Ruby 2.0.0** or later is additionally required for the CMock test framework (that we use). | ||
| - For running the coverage target, **gcov** and **lcov** are additionally required. | ||
|
|
||
| ### Steps to build unit tests | ||
|
|
||
| 1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule).) | ||
|
|
||
| 1. Run the *cmake* command: `cmake -S test -B build` | ||
|
|
||
| 1. Run this command to build the library and unit tests: `make -C build all` | ||
|
|
||
| 1. The generated test executables will be present in `build/bin/tests` folder. | ||
|
|
||
| 1. Run `cd build && ctest` to execute all tests and view the test run summary. | ||
|
|
||
| ## 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: | ||
|
|
||
| ```shell | ||
| doxygen docs/doxygen/config.doxyfile | ||
| ``` | ||
|
|
||
| ## Contributing | ||
|
|
||
| See [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on contributing. | ||