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:

• LogError
• LogWarn
• LogInfo
• LogDebug

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.

• CellularCommInterfaceOpen_t Open a connection to the comm interface.
• CellularCommInterfaceSend_t Send data to the comm interface.
• CellularCommInterfaceRecv_t Receive data from the comm interface.
• CellularCommInterfaceClose_t Close the connection to the comm interface.

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 ) )