/** @page cellular_porting_module_guide Porting Module Guide @brief FreeRTOS Cellular Common Library
FreeRTOS Cellular Common Library provides the following functions to help cellular module implementing FreeRTOS Cellular Library APIs.
- FreeRTOS Cellular Library APIs implementation with 3GPP TS v27.007 AT commands. - AT command functions to help implementing FreeRTOS Cellular Library APIs with vendor specific AT commands.
The following diagram illustrates the relation between cellular common and cellular module porting.
Reference @subpage porting_cellular_module for detail porting information and implemented @subpage cellular_common_functions. @image html cellular_common_module.png width=70%
*/ /** @page porting_cellular_module Porting cellular module @brief Introduction to cellular module porting
Cellular common library provides APIS and URC handler implemented with 3GPP v27.007 AT commands.
These APIs and URC handler can be reused when porting cellular module.
Reference the following pages for detail information. - @subpage cellular_common_APIs - @subpage cellular_common_URC_handlers Porting cellular module with cellular common portable with the following steps.
-# Create a folder in modules with the following files. - modules/(module_name)/cellular_(module_name).c - modules/(module_name)/cellular_(module_name)_api.c - modules/(module_name)/cellular_(module_name)_urc_handler.c - modules/(module_name)/cellular_(module_name)_wrapper.c -# Implement cellular module porting interface @ref cellular_common_portable.h in cellular_(module_name).c
Reference @subpage cellular_module for detail information. -# Implement FreeRTOS Cellular Library API with cellular module specific AT commands in cellular_(module_name)_api.c
Reference @subpage cellular_module_api for detail information. -# Implement URC handler to handle URC event and call the corresponding callback function in cellular_(module_name)_urc_handler.c
Reference @subpage cellular_module_urc_handler for detail information. -# Create FreeRTOS Cellular Library APIs implemented with 3GPP TS v27.007 AT commands ( @ref cellular_common_api.h ) in cellular_(module_name)_wrapper.c
Cellular module porting examples
Three cellular module portings can be referenced.
It is recommended that you start by cloning the implementation of one of the existing modems,
then make modifications where your modem's vendor-specific (non-3GPP) AT commands are different.
- BG96 - HL7802 - SARA R4 series */ /** @page cellular_common_APIs Cellular common APIs @brief Cellular common supported APIs Cellular common supported APIs
Cellular common library has 3GPP AT command implemented APIs.
They can be used to minimize porting efforts when implement FreeRTOS Cellular Library APIs.
| FreeRTOS Cellular Library APIs | Cellular common supported | | :-------------------------------------------------------| :-----------------------: | | Cellular_Init | O | | Cellular_Cleanup | O | | Cellular_SetRatPriority | | | Cellular_GetRatPriority | | | Cellular_RfOn | O | | Cellular_RfOff | O | | Cellular_GetSimCardStatus | | | Cellular_GetSimCardInfo | O | | Cellular_GetModemInfo | O | | Cellular_GetRegisteredNetwork | O | | Cellular_GetNetworkTime | O | | Cellular_GetSignalInfo | | | Cellular_GetServiceStatus | O | | Cellular_SetPdnConfig | O | | Cellular_GetPdnStatus | | | Cellular_ActivatePdn | | | Cellular_DeactivatePdn | | | Cellular_GetIPAddress | O | | Cellular_SetDns | | | Cellular_RegisterUrcNetworkRegistrationEventCallback | O | | Cellular_RegisterUrcPdnEventCallback | O | | Cellular_RegisterUrcSignalStrengthChangedCallback | | | Cellular_RegisterModemEventCallback | O | | Cellular_RegisterUrcGenericCallback | O | | Cellular_GetPsmSettings | O | | Cellular_SetPsmSettings | O | | Cellular_GetEidrxSettings | O | | Cellular_SetEidrxSettings | O | | Cellular_ATCommandRaw | O | | Cellular_CreateSocket | O | | Cellular_SocketConnect | | | Cellular_SocketSend | | | Cellular_SocketRecv | | | Cellular_SocketClose | | | Cellular_GetHostByName | | | Cellular_SocketSetSockOpt | O | | Cellular_SocketRegisterSocketOpenCallback | O | | Cellular_SocketRegisterDataReadyCallback | O | | Cellular_SocketRegisterClosedCallback | O | */ /** @page cellular_common_URC_handlers Cellular common URC handlers @brief Cellular common supported URC handlers Cellular common supported URC handler
FreeRTOS Cellular Library APIs callback function is called in URC handler.
3GPP URC handlers are also provided by cellular common library.
They can be used to reduce porting effort.
| FreeRTOS Cellular Library callback functions | Event | Cellular common supported | | :----------------------------------------------------| :----------------------------------------- | :-----------------------: | | Cellular_RegisterUrcNetworkRegistrationEventCallback | CELLULAR_URC_EVENT_NETWORK_CS_REGISTRATION | O | | Cellular_RegisterUrcNetworkRegistrationEventCallback | CELLULAR_URC_EVENT_NETWORK_PS_REGISTRATION | O | | Cellular_RegisterUrcPdnEventCallback | CELLULAR_URC_EVENT_PDN_ACTIVATED | | | Cellular_RegisterUrcPdnEventCallback | CELLULAR_URC_EVENT_PDN_DEACTIVATED | | | Cellular_RegisterUrcSignalStrengthChangedCallback | CELLULAR_URC_EVENT_SIGNAL_CHANGED | | | Cellular_RegisterModemEventCallback | CELLULAR_MODEM_EVENT_BOOTUP_OR_REBOOT | | | Cellular_RegisterModemEventCallback | CELLULAR_MODEM_EVENT_POWERED_DOWN | | | Cellular_RegisterModemEventCallback | CELLULAR_MODEM_EVENT_PSM_ENTER | | | Cellular_SocketRegisterSocketOpenCallback | CELLULAR_URC_SOCKET_OPENED | | | Cellular_SocketRegisterSocketOpenCallback | CELLULAR_URC_SOCKET_OPEN_FAILED | | | Cellular_SocketRegisterDataReadyCallback | None | | | Cellular_SocketRegisterClosedCallback | None | | */ /** @page cellular_module cellular_module @brief Implement cellular module porting interface.
- Implement functions defined cellular_common_portable.h - @ref Cellular_ModuleInit - @ref Cellular_ModuleCleanUp - @ref Cellular_ModuleEnableUE - @ref Cellular_ModuleEnableUrc @image html cellular_module_porting_functions.png width=80% - Create variable instance defined in cellular_common_portable.h - AT command response token tables. - \ref CellularTokenTable_t.pCellularSrcTokenErrorTable : indicate AT command is success - @ref CellularTokenTable_t.cellularSrcTokenErrorTableSize - @ref CellularTokenTable_t.pCellularSrcTokenSuccessTable : indicat AT command fails - @ref CellularTokenTable_t.cellularSrcTokenSuccessTableSize - URC handler table - @ref CellularTokenTable_t.pCellularUrcTokenWoPrefixTable : URC token without prefix "+". These tokens are used in URC handler tables.
( E.X "APP READY", "POWER ON" ) - @ref CellularTokenTable_t.cellularUrcTokenWoPrefixTableSize */ /** @page cellular_module_api cellular_module_api @brief Implement FreeRTOS Cellular Library API with cellular module specific AT commands.
- Create FreeRTOS Cellular Library APIs implemented with module specific AT commands with cellular_common.h and cellular_at_core.h - AT command related data structure - @ref CellularAtReq_t : AT command request data structure - @ref CellularAtDataReq_t : Data send data structure - Send AT command APIs - @ref _Cellular_AtcmdRequestWithCallback : Default timeout - @ref _Cellular_TimeoutAtcmdRequestWithCallback : Custom timeout - Send AT command APIs for data receive ( E.X socket data receive ) - @ref _Cellular_TimeoutAtcmdDataRecvRequestWithCallback - Send AT command APIS for data send ( E.X socket data send ) - @ref _Cellular_TimeoutAtcmdDataSendRequestWithCallback : Basic data send API - @ref _Cellular_AtcmdDataSend : Prefix callback function to indicate data mode start - @ref _Cellular_TimeoutAtcmdDataSendSuccessToken : Extra success token to indicate AT commnad success @image html cellular_API_implementation.png width=80% */ /** @page cellular_module_urc_handler cellular_module_urc_handler @brief Implement URC handler to handle URC event and call the corresponding callback function.
- @ref CellularTokenTable_t.pCellularUrcHandlerTable : URC handler table of @ref CellularAtParseTokenHandler_t - @ref CellularTokenTable_t.cellularPrefixToParserMapSize Example URC handler table. ``` CellularAtParseTokenMap_t CellularUrcHandlerTable[] = { { "CEREG", Cellular_CommonUrcProcessCereg }, { "CGREG", Cellular_CommonUrcProcessCgreg }, { "CREG", Cellular_CommonUrcProcessCreg }, { "NORMAL POWER DOWN", _Cellular_ProcessPowerDown }, } uint32_t CellularUrcHandlerTableSize = 4; ``` @image html cellular_URC_handler_implementation.png width=80% */ /** @paramstructs_group{cellular_common,Cellular_common} @paramstructs_brief{cellular_common,cellular_common} */ /** @functionpointers_group{cellular_common,Cellular_common} @functionpointers_brief{cellular_common library} */ /** @enums_group{cellular_common,Cellular_common} @enums_brief{cellular_common library} */ /** @functions_page{cellular_common,cellular_common} @functions_brief{cellular_common} The following APIs are 3GPP v27.007 AT command implemented FreeRTOS Cellular Library APIs.
- @function_name{Cellular_CommonInit} @function_brief{Cellular_CommonInit} - @function_name{Cellular_CommonCleanup} @function_brief{Cellular_CommonCleanup} - @function_name{Cellular_CommonRegisterUrcNetworkRegistrationEventCallback} @function_brief{Cellular_CommonRegisterUrcNetworkRegistrationEventCallback} - @function_name{Cellular_CommonRegisterUrcPdnEventCallback} @function_brief{Cellular_CommonRegisterUrcPdnEventCallback} - @function_name{Cellular_CommonRegisterUrcSignalStrengthChangedCallback} @function_brief{Cellular_CommonRegisterUrcSignalStrengthChangedCallback} - @function_name{Cellular_CommonRegisterUrcGenericCallback} @function_brief{Cellular_CommonRegisterUrcGenericCallback} - @function_name{Cellular_CommonRegisterModemEventCallback} @function_brief{Cellular_CommonRegisterModemEventCallback} - @function_name{Cellular_CommonATCommandRaw} @function_brief{Cellular_CommonATCommandRaw} - @function_name{Cellular_CommonCreateSocket} @function_brief{Cellular_CommonCreateSocket} - @function_name{Cellular_CommonSocketSetSockOpt} @function_brief{Cellular_CommonSocketSetSockOpt} - @function_name{Cellular_CommonSocketRegisterDataReadyCallback} @function_brief{Cellular_CommonSocketRegisterDataReadyCallback} - @function_name{Cellular_CommonSocketRegisterSocketOpenCallback} @function_brief{Cellular_CommonSocketRegisterSocketOpenCallback} - @function_name{Cellular_CommonSocketRegisterClosedCallback} @function_brief{Cellular_CommonSocketRegisterClosedCallback} - @function_name{Cellular_CommonRfOn} @function_brief{Cellular_CommonRfOn} - @function_name{Cellular_CommonRfOff} @function_brief{Cellular_CommonRfOff} - @function_name{Cellular_CommonGetIPAddress} @function_brief{Cellular_CommonGetIPAddress} - @function_name{Cellular_CommonGetModemInfo} @function_brief{Cellular_CommonGetModemInfo} - @function_name{Cellular_CommonGetEidrxSettings} @function_brief{Cellular_CommonGetEidrxSettings} - @function_name{Cellular_CommonSetEidrxSettings} @function_brief{Cellular_CommonSetEidrxSettings} - @function_name{Cellular_CommonGetRegisteredNetwork} @function_brief{Cellular_CommonGetRegisteredNetwork} - @function_name{Cellular_CommonGetNetworkTime} @function_brief{Cellular_CommonGetNetworkTime} - @function_name{Cellular_CommonGetServiceStatus} @function_brief{Cellular_CommonGetServiceStatus} - @function_name{Cellular_CommonSetPdnConfig} @function_brief{Cellular_CommonSetPdnConfig} - @function_name{Cellular_CommonGetPsmSettings} @function_brief{Cellular_CommonGetPsmSettings} - @function_name{Cellular_CommonSetPsmSettings} @function_brief{Cellular_CommonSetPsmSettings} - @function_name{Cellular_CommonGetSimCardInfo} @function_brief{Cellular_CommonGetSimCardInfo} - @function_name{Cellular_CommonGetSimCardLockStatus} @function_brief{Cellular_CommonGetSimCardLockStatus} The following APIs can be used when implementating FreeRTOS Cellular Library APIs with module specific AT command.
AT command parsing functions
- @function_name{Cellular_ATRemovePrefix} @function_brief{Cellular_ATRemovePrefix} - @function_name{Cellular_ATRemoveLeadingWhiteSpaces} @function_brief{Cellular_ATRemoveLeadingWhiteSpaces} - @function_name{Cellular_ATRemoveTrailingWhiteSpaces} @function_brief{Cellular_ATRemoveTrailingWhiteSpaces} - @function_name{Cellular_ATRemoveAllWhiteSpaces} @function_brief{Cellular_ATRemoveAllWhiteSpaces} - @function_name{Cellular_ATRemoveOutermostDoubleQuote} @function_brief{Cellular_ATRemoveOutermostDoubleQuote} - @function_name{Cellular_ATRemoveAllDoubleQuote} @function_brief{Cellular_ATRemoveAllDoubleQuote} - @function_name{Cellular_ATGetNextTok} @function_brief{Cellular_ATGetNextTok} - @function_name{Cellular_ATGetSpecificNextTok} @function_brief{Cellular_ATGetSpecificNextTok} - @function_name{Cellular_ATHexStrToHex} @function_brief{Cellular_ATHexStrToHex} - @function_name{Cellular_ATIsStrDigit} @function_brief{Cellular_ATIsStrDigit} - @function_name{Cellular_ATIsPrefixPresent} @function_brief{Cellular_ATIsPrefixPresent} - @function_name{Cellular_ATStrDup} @function_brief{Cellular_ATStrDup} - @function_name{Cellular_ATStrStartWith} @function_brief{Cellular_ATStrStartWith} - @function_name{Cellular_ATcheckErrorCode} @function_brief{Cellular_ATcheckErrorCode} - @function_name{Cellular_ATStrtoi} @function_brief{Cellular_ATStrtoi} Cellular common library helper functions
- @function_name{_Cellular_LibInit} @function_brief{_Cellular_LibInit} - @function_name{_Cellular_LibCleanup} @function_brief{_Cellular_LibCleanup} - @function_name{_Cellular_CheckLibraryStatus} @function_brief{_Cellular_CheckLibraryStatus} - @function_name{_Cellular_TranslatePktStatus} @function_brief{_Cellular_TranslatePktStatus} - @function_name{_Cellular_CreateSocketData} @function_brief{_Cellular_CreateSocketData} - @function_name{_Cellular_RemoveSocketData} @function_brief{_Cellular_RemoveSocketData} - @function_name{_Cellular_IsValidSocket} @function_brief{_Cellular_IsValidSocket} - @function_name{_Cellular_IsValidPdn} @function_brief{_Cellular_IsValidPdn} - @function_name{_Cellular_ConvertCsqSignalRssi} @function_brief{_Cellular_ConvertCsqSignalRssi} - @function_name{_Cellular_ConvertCsqSignalBer} @function_brief{_Cellular_ConvertCsqSignalBer} - @function_name{_Cellular_GetModuleContext} @function_brief{_Cellular_GetModuleContext} - @function_name{_Cellular_ComputeSignalBars} @function_brief{_Cellular_ComputeSignalBars} - @function_name{_Cellular_GetCurrentRat} @function_brief{_Cellular_GetCurrentRat} - @function_name{_Cellular_TranslatePktStatus} @function_brief{_Cellular_TranslatePktStatus} - @function_name{_Cellular_TranslateAtCoreStatus} @function_brief{_Cellular_TranslateAtCoreStatus} - @function_name{_Cellular_AtcmdRequestWithCallback} @function_brief{_Cellular_AtcmdRequestWithCallback} - @function_name{_Cellular_TimeoutAtcmdRequestWithCallback} @function_brief{_Cellular_TimeoutAtcmdRequestWithCallback} - @function_name{_Cellular_TimeoutAtcmdDataRecvRequestWithCallback} @function_brief{_Cellular_TimeoutAtcmdDataRecvRequestWithCallback} - @function_name{_Cellular_TimeoutAtcmdDataSendRequestWithCallback} @function_brief{_Cellular_TimeoutAtcmdDataSendRequestWithCallback} - @function_name{_Cellular_AtcmdDataSend} @function_brief{_Cellular_AtcmdDataSend} - @function_name{_Cellular_TimeoutAtcmdDataSendSuccessToken} @function_brief{_Cellular_TimeoutAtcmdDataSendSuccessToken} */