{"id":19775052,"url":"https://github.com/freertos/freertos-cellular-interface","last_synced_at":"2026-02-06T00:08:32.574Z","repository":{"id":37669805,"uuid":"313835816","full_name":"FreeRTOS/FreeRTOS-Cellular-Interface","owner":"FreeRTOS","description":"FreeRTOS Cellular Interface implementation of the 3GPP TS v27.007 standard.","archived":false,"fork":false,"pushed_at":"2025-04-22T07:28:29.000Z","size":4638,"stargazers_count":92,"open_issues_count":4,"forks_count":64,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-22T08:34:20.532Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FreeRTOS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-18T05:48:44.000Z","updated_at":"2025-04-22T07:28:34.000Z","dependencies_parsed_at":"2024-03-14T07:30:47.347Z","dependency_job_id":"3cc63584-3b1f-4ca0-888b-09fd3fd8f332","html_url":"https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FFreeRTOS-Cellular-Interface","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FFreeRTOS-Cellular-Interface/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FFreeRTOS-Cellular-Interface/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreeRTOS%2FFreeRTOS-Cellular-Interface/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreeRTOS","download_url":"https://codeload.github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251769159,"owners_count":21640847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T05:14:45.852Z","updated_at":"2026-02-06T00:08:32.507Z","avatar_url":"https://github.com/FreeRTOS.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FreeRTOS Cellular Interface\n\n## On this page:\n\n- [Introduction](#Introduction)\n- [Getting Started](#Getting-Started)\n  - [Download the Source Code](#Download-the-Source-Code)\n  - [Folder Structure](#Folder-Structure)\n- [Implement Comm Interface with MCU Platforms](#Implement-Comm-Interface-with-MCU-Platforms)\n- [Adding Support for New Cellular Modems](#Adding-Support-for-New-Cellular-Modems)\n- [Integrate FreeRTOS Cellular Interface with Application](#Integrate-FreeRTOS-Cellular-Interface-with-Application)\n- [Building Unit Tests](#Building-Unit-Tests)\n- [Generating Documentation](#Generating-Documentation)\n- [Contributing](#Contributing)\n\n## Introduction\n\nThe Cellular Interface library implement a simple unified\n[Application Programming Interfaces (APIs)](https://www.freertos.org/Documentation/api-ref/cellular/index.html)\nthat hide the complexity of AT commands. The cellular modems to be\ninterchangeable with the popular options built upon TCP stack and exposes a\nsocket-like interface to C programmers.\n\nMost cellular modems implement more or less the AT commands defined by the\n[3GPP TS v27.007](https://portal.3gpp.org/desktopmodules/Specifications/SpecificationDetails.aspx?specificationId=1515)\nstandard. This project provides an implementation of such standard AT commands\nin a\n[reusable common component](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common).\nThe three Cellular libraries in this project all take advantage of that common\ncode. The library for each modem only implements the vendor-specific AT\ncommands, then exposes the complete Cellular API.\n\nThe common component that implements the 3GPP TS v27.007 standard has been\nwritten in compliance of the following code quality criteria:\n\n- GNU Complexity scores are not over 8.\n- MISRA coding standard. Any deviations from the MISRA C:2012 guidelines are\n  documented in source code comments marked by \"`coverity`\".\n\n**FreeRTOS Cellular Interface v1.4.0\n[Source Code](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/v1.4.0/source)\nis part of the\n[FreeRTOS 202406.00 LTS](https://github.com/FreeRTOS/FreeRTOS-LTS/tree/202406.00-LTS)\nrelease.**\n\n## Getting Started\n\n### Download the source code\n\nTo clone using HTTPS:\n\n```\ngit clone https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface.git\n```\n\nUsing SSH:\n\n```\ngit clone git@github.com/FreeRTOS/FreeRTOS-Cellular-Interface.git\n```\n\n### Folder structure\n\nAt the root of this repository are these folders:\n\n- source : reusable common code that implements the standard AT commands defined\n  by 3GPP TS v27.007.\n- docs : documentations.\n- test : unit test and cbmc.\n- tools : tools for Coverity static analysis and CMock.\n\n## Implement Comm Interface with MCU platforms\n\nThe FreeRTOS Cellular Interface runs on MCUs. It uses an abstracted interface -\nthe\n[Comm Interface](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/interface/cellular_comm_interface.h),\nto communicate with cellular modems. A Comm Interface must be implemented as\nwell on the MCU platform. The most common implementations of the Comm Interface\nare over UART hardware, but it can be implemented over other physical interfaces\nsuch as SPI as well. The documentation of the Comm Interface is found within the\n[Cellular API References](https://www.freertos.org/Documentation/api-ref/cellular/cellular_porting.html#cellular_porting_comm_if).\nThese are example implementations of the Comm Interface:\n\n- [FreeRTOS Windows Simulator Comm Interface](https://github.com/FreeRTOS/FreeRTOS/blob/main/FreeRTOS-Plus/Demo/FreeRTOS_Cellular_Interface_Windows_Simulator/Common/comm_if_windows.c)\n- [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)\n- [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)\n- [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)\n\nThe FreeRTOS Cellular Interface uses kernel APIs for task synchronization and\nmemory management.\n\n## Adding Support for New Cellular Modems\n\nFreeRTOS Cellular Interface now supports AT commands, TCP offloaded Cellular\nabstraction Layer. In order to add support for a new cellular modem, the\ndeveloper can use the\n[common component](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common)\nthat has already implemented the 3GPP standard AT commands.\n\nIn order to port the\n[common component](https://www.freertos.org/Documentation/api-ref/cellular/cellular_porting_module_guide.html):\n\n1. Implement the cellular modem porting interface defined in\n   [cellular_common_portable.h](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface/tree/main/source/include/common/cellular_common_portable.h)\n   ([Document](https://www.freertos.org/Documentation/api-ref/cellular/cellular__common__portable_8h.html)).\n2. Implement the subset of Cellular Library APIs that use vendor-specific\n   (non-3GPP) AT commands. The APIs to be implemented are the ones not marked\n   with an \"o\" in\n   [this table](https://www.freertos.org/Documentation/api-ref/cellular/cellular_common__a_p_is.html).\n3. Implement Cellular Library callback functions that handle vendor-specific\n   (non-3GPP) Unsolicited Result Code (URC). The URC handlers to be implemented\n   are the ones not marked with an \"o\" in\n   [this table](https://www.freertos.org/Documentation/api-ref/cellular/cellular_common__u_r_c_handlers.html).\n\nThe\n[Cellular Common APIs document](https://www.freertos.org/Documentation/api-ref/cellular/cellular_porting_module_guide.html)\nprovides detail information required in each steps. It is recommended that you\nstart by cloning the implementation of one of the existing modems, then make\nmodifications where your modem's vendor-specific (non-3GPP) AT commands are\ndifferent.\n\nCurrent Example Implementations:\n\n- [Quectel BG96](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-Quectel-BG96)\n- [Sierra Wireless HL7802](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-Sierra-Wireless-HL7802)\n- [U-Blox Sara-R4](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-ublox-SARA-R4)\n\n## Integrate FreeRTOS Cellular Interface with Application\n\nOnce comm interface and cellular module implementation are ready, we can start\nto integrate FreeRTOS Cellular Interface. The following diagram depicts the\nrelationship of these software components:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"/docs/plantuml/images/cellular_components.svg\" width=\"50%\"\u003e\u003cbr\u003e\n\nFollow these steps to integrate FreeRTOS Cellular Interface into your project:\n\n1. Clone this repository into your project.\n2. Clone one of the reference cellular module implementations ( BG96 / HL7802 /\n   SARA-R4 ) or create your own cellular module implementation in your project.\n3. Implement comm interface.\n4. Build these software components with your application and execute.\n\nWe also provide\n[Demos for FreeRTOS-Cellular-Interface on Windows Simulator](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/FreeRTOS_Cellular_Interface_Windows_Simulator)\nas references for these three cellular modems example implementations.\n\n## Building Unit Tests\n\n### Checkout CMock Submodule\n\nBy default, the submodules in this repository are configured with `update=none`\nin [.gitmodules](.gitmodules) to avoid increasing clone time and disk space\nusage of other repositories (like\n[FreeRTOS](https://github.com/FreeRTOS/FreeRTOS) that submodules this\nrepository).\n\nTo build unit tests, the submodule dependency of CMock is required. Use the\nfollowing command to clone the submodule:\n\n```\ngit submodule update --checkout --init --recursive test/unit-test/CMock\n```\n\n### Platform Prerequisites\n\n- For building the unit tests, **CMake 3.13.0** or later and a **C90 compiler**.\n- For running unit tests, **Ruby 2.0.0** or later is additionally required for\n  the CMock test framework (that we use).\n- For running the coverage target, **gcov** and **lcov** are additionally\n  required.\n\n### Steps to build unit tests\n\n1. Go to the root directory of this repository. (Make sure that the **CMock**\n   submodule is cloned as described [above](#checkout-cmock-submodule).)\n\n1. Run the _cmake_ command: `cmake -S test -B build`\n\n1. Run this command to build the library and unit tests: `make -C build all`\n\n1. The generated test executables will be present in `build/bin/tests` folder.\n\n1. Run `cd build \u0026\u0026 ctest` to execute all tests and view the test run summary.\n\n## CBMC\n\nTo learn more about CBMC and proofs specifically, review the training material\n[here](https://model-checking.github.io/cbmc-training).\n\nThe `test/cbmc/proofs` directory contains CBMC proofs.\n\nIn order to run these proofs you will need to install CBMC and other tools by\nfollowing the instructions\n[here](https://model-checking.github.io/cbmc-training/installation.html).\n\n## Reference examples\n\nPlease refer to the demos of the Cellular Interface library\n[here](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/FreeRTOS_Cellular_Interface_Windows_Simulator)\nusing FreeRTOS on the Windows simulator platform. These can be used as reference\nexamples for the library API.\n\n## Generating documentation\n\nThe Doxygen references were created using Doxygen version 1.9.6. To generate the\nDoxygen pages, please run the following command from the root of this\nrepository:\n\n```shell\ndoxygen docs/doxygen/config.doxyfile\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](./.github/CONTRIBUTING.md) for information on\ncontributing.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Ffreertos-cellular-interface","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreertos%2Ffreertos-cellular-interface","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreertos%2Ffreertos-cellular-interface/lists"}