FreeRTOS: FreeRTOS Cellular Library v1.2.0
FreeRTOS Cellular Library
Porting Guide

Guide for porting Cellular library to a new platform.

To use the Cellular library, a platform must implement the following components:

  1. Configuration Macros
  2. Cellular Communication Interface
  3. Cellular platform dependency

Configuration Macros

Settings that must be set as macros in the config header cellular_config.h, or passed in as compiler options.

Note
If a custom configuration header cellular_config.h is not provided, then the CELLULAR_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.
See also
Configurations

In addition, the following logging macros are used throughout the library:

Cellular Communication Interface

FreeRTOS Cellular Library use communication interface to communicate with cellular modules.

CellularCommInterface includes the following four function pointers. Reference the document page for prototype.

Cellular platform dependency

Cellular platform depndency

FreeRTOS Cellular Library makes use of the following OS platform functions.
"cellular_platform.h" is referenced during FreeRTOS Cellular Library compilation.
User of FreeRTOS Cellular Library should provide these APIs and data structures in "cellular_platform.h".
A default implementation with FreeRTOS is provided in FreeRTOS Labs cellular demo.

  • Threads
    The following APIs and macros should be provided in cellular_platform.h
    bool Platform_CreateDetachedThread( void ( * threadRoutine )( void * ),
    void * pArgument,
    int32_t priority,
    size_t stackSize );
    #define PLATFORM_THREAD_DEFAULT_STACK_SIZE ( 2048U )
    #define PLATFORM_THREAD_DEFAULT_PRIORITY ( 5U )
  • Mutex
    The following APIs and data structure should be provided in cellular_platform.h.
    FreeRTOS Cellular Library use static mutex allocation. Data fields in PlatformMutex can be defined by developers.
    typedef struct PlatformMutex
    {
    ...
    } PlatformMutex_t;
    bool PlatformMutex_Create( PlatformMutex_t * pNewMutex,
    bool recursive );
    void PlatformMutex_Destroy( PlatformMutex_t * pMutex );
    void PlatformMutex_Lock( PlatformMutex_t * pMutex );
    bool PlatformMutex_TryLock( PlatformMutex_t * pMutex );
    void PlatformMutex_Unlock( PlatformMutex_t * pMutex );
  • Memory
    The following malloc/free style APIs should be provided in cellular_platform.h.
    The FreeRTOS memory management document can be referenced for these APIs.
    // Example implementation of FreeRTOS malloc/free
    #define Platform_Malloc pvPortMalloc
    #define Platform_Free vPortFree
  • EventGroup
    The following APIs and handle should be provided in cellular_platform.h.
    Please reference FreeRTOS EvengGroup function prototypes.
    // Example implementation of FreeRTOS EvengGroup
    #define PlatformEventGroupHandle_t EventGroupHandle_t
    #define PlatformEventGroup_Delete vEventGroupDelete
    #define PlatformEventGroup_ClearBits xEventGroupClearBits
    #define PlatformEventGroup_Create xEventGroupCreate
    #define PlatformEventGroup_GetBits xEventGroupGetBits
    #define PlatformEventGroup_SetBits xEventGroupSetBits
    #define PlatformEventGroup_SetBitsFromISR xEventGroupSetBitsFromISR
    #define PlatformEventGroup_WaitBits xEventGroupWaitBits
  • Delay
    The following API should be provided in cellular_platform.h.
    Please reference FreeRTOS Task Control function prototypes.
    // Example implementation of FreeRTOS Task Control
    #define Platform_Delay( delayMs ) vTaskDelay( pdMS_TO_TICKS( delayMs ) )