/** @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
Sending and receiving binary data with cellular common APIs
Cellular common APIs supports send/receive binary data. These APIs can be used to implement socket send or socket receive functions. The following page provides example and description about how to use these APIs to interact with cellular modem: - @subpage cellular_sending_binary_data - @subpage cellular_receiving_binary_data 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 : The size of the URC handler table
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; ```
There are two types of URC strings can be handled with this table: - URC with prefix
This type of URC string is of the following format:
> \\":"\
The logic to check the URC prefix can be referenced in @ref Cellular_ATIsPrefixPresent
Example of URC with prefix: "+CREG:2,0"
In this example,
URC_leading_char is "+"
URC_prefix is "CREG"
URC_payload is "2,0"
The URC callback function, @ref CellularAtParseTokenHandler_t, will be called with parameter pInputStr point to string URC_payload, "2,0" in this example. > The default prefix leading char can be referenced in this config @ref CELLULAR_CHECK_IS_PREFIX_LEADING_CHAR.
> The default valid prefix string chars can be referenced in this config @ref CELLULAR_CHECK_IS_PREFIX_CHAR.
> Reference @subpage cellular_prefix_string_customize_config for more information. - URC without prefix
This type of URC string is of fixed format.
Example of URC without prefix : "NORMAL POWER DOWN"
The URC callback function, @ref CellularAtParseTokenHandler_t, will be called with parameter pInputStr point to URC string, "NORMAL POWER DOWN" in this example.
@image html cellular_URC_handler_implementation.png width=80% */ /** @page cellular_prefix_string_customize_config Customization config for prefix string. @brief The config can be redefined in cellular_config.h to support different modem prefix string format.
@section CELLULAR_CHECK_IS_PREFIX_CHAR @copydoc CELLULAR_CHECK_IS_PREFIX_CHAR @section CELLULAR_CHECK_IS_PREFIX_LEADING_CHAR @copydoc CELLULAR_CHECK_IS_PREFIX_LEADING_CHAR */ /** @page cellular_common_functions Functions @brief Functions of the cellular_common library.

The following APIs are 3GPP v27.007 AT command implemented FreeRTOS Cellular Library APIs.
- @ref Cellular_CommonInit - @ref Cellular_CommonCleanup - @ref Cellular_CommonRegisterUrcNetworkRegistrationEventCallback - @ref Cellular_CommonRegisterUrcPdnEventCallback - @ref Cellular_CommonRegisterUrcSignalStrengthChangedCallback - @ref Cellular_CommonRegisterUrcGenericCallback - @ref Cellular_CommonRegisterModemEventCallback - @ref Cellular_CommonATCommandRaw - @ref Cellular_CommonCreateSocket - @ref Cellular_CommonSocketSetSockOpt - @ref Cellular_CommonSocketRegisterDataReadyCallback - @ref Cellular_CommonSocketRegisterSocketOpenCallback - @ref Cellular_CommonSocketRegisterClosedCallback - @ref Cellular_CommonRfOn - @ref Cellular_CommonRfOff - @ref Cellular_CommonGetIPAddress - @ref Cellular_CommonGetModemInfo - @ref Cellular_CommonGetEidrxSettings - @ref Cellular_CommonSetEidrxSettings - @ref Cellular_CommonGetRegisteredNetwork - @ref Cellular_CommonGetNetworkTime - @ref Cellular_CommonGetServiceStatus - @ref Cellular_CommonSetPdnConfig - @ref Cellular_CommonGetPsmSettings - @ref Cellular_CommonSetPsmSettings - @ref Cellular_CommonGetSimCardInfo - @ref Cellular_CommonGetSimCardLockStatus The following APIs can be used when implementating FreeRTOS Cellular Library APIs with module specific AT command.
AT command parsing functions
- @ref Cellular_ATRemovePrefix - @ref Cellular_ATRemoveLeadingWhiteSpaces - @ref Cellular_ATRemoveTrailingWhiteSpaces - @ref Cellular_ATRemoveAllWhiteSpaces - @ref Cellular_ATRemoveOutermostDoubleQuote - @ref Cellular_ATRemoveAllDoubleQuote - @ref Cellular_ATGetNextTok - @ref Cellular_ATGetSpecificNextTok - @ref Cellular_ATHexStrToHex - @ref Cellular_ATIsStrDigit - @ref Cellular_ATIsPrefixPresent - @ref Cellular_ATStrDup - @ref Cellular_ATStrStartWith - @ref Cellular_ATcheckErrorCode - @ref Cellular_ATStrtoi Cellular common library helper functions
- @ref _Cellular_LibInit - @ref _Cellular_LibCleanup - @ref _Cellular_CheckLibraryStatus - @ref _Cellular_TranslatePktStatus - @ref _Cellular_CreateSocketData - @ref _Cellular_RemoveSocketData - @ref _Cellular_IsValidSocket - @ref _Cellular_IsValidPdn - @ref _Cellular_ConvertCsqSignalRssi - @ref _Cellular_ConvertCsqSignalBer - @ref _Cellular_GetModuleContext - @ref _Cellular_ComputeSignalBars - @ref _Cellular_GetCurrentRat - @ref _Cellular_TranslatePktStatus - @ref _Cellular_TranslateAtCoreStatus - @ref _Cellular_AtcmdRequestWithCallback - @ref _Cellular_TimeoutAtcmdRequestWithCallback - @ref _Cellular_TimeoutAtcmdDataRecvRequestWithCallback - @ref _Cellular_TimeoutAtcmdDataSendRequestWithCallback - @ref _Cellular_AtcmdDataSend - @ref _Cellular_TimeoutAtcmdDataSendSuccessToken */ /** @page cellular_sending_binary_data Sending binary data with Cellular Common APIs Send binary data command is split into two steps: - **Send the AT command** - **Send the binary data** Take the socket send command of reference port BG96 for example: ``` AT+QISEND=0,5 //Send fixed length data and the data length is 5 bytes > test2 SEND OK ``` The first step sends the command "AT+QISEND=0,5" and waiting for the response "> ". ``` AT+QISEND=0,5 > ``` ">" is a result code in the port to indicate that modem is ready to accept the binary data. The second step send the binary data "test2" to the modem and waits for the response "SEND OK". ``` test2 SEND OK ``` "SEND OK" is a result code in the port to indicate the modem successfully receives the data. > One thing to mentioned in the example is that cellular interface processes the response > in line. The respone "> " does not contain line ending char. Cellular interface passes the response > to the port through data send prefix callback function. The port may fix the input stream > in the callback function. In this example, the response is fixed to ">\n" in the callback. > Cellular interface can process the fixed input stream. _Cellular_AtcmdDataSend is the general cellular common API to send binary data to cellular modem. BG96 port make use of this API to send binary data with the following parameters: ``` /* The structure to send the AT command. Mapping to the first step of send binary data. */ CellularAtReq_t atReqSocketSend = { .pAtCmd = cmdBuf, /* In this example, "AT+QISEND=0,5". */ .atCmdType = CELLULAR_AT_NO_RESULT, /* The command expects only result code to indicate status from modem. */ .pAtRspPrefix = NULL, /* No prefix for the result since the type is CELLULAR_AT_NO_RESULT. */ .respCallback = NULL, /* No response callback since the type is CELLULAR_AT_NO_RESULT. */ .pData = NULL, /* No data since the type is CELLULAR_AT_NO_RESULT. */ .dataLen = 0, /* Data length is 0. */ }; /* The structure to send the binary data. Mapping to the second step of send binary data. */ CellularAtDataReq_t atDataReqSocketSend = { .pData = pData, /* Point to the data to send. */ .dataLen = dataLength, /* The length of the data to send. */ .pSentDataLength = pSentDataLength, /* The actual data sent to the modem. */ .pEndPattern = NULL, /* The end pattern to send after the binary data. */ .endPatternLen = 0 /* The length of the end pattern. */ }; /* The send binary data send API in cellular common layer. */ pktStatus = _Cellular_AtcmdDataSend( pContext, /* The cellular context. */ atReqSocketSend, /* Send AT command request. */ atDataReqSocketSend, /* Send binary data. */ socketSendDataPrefix, /* Data prefix callback. BG96 port fix the input stream "> " in this function. */ NULL, /* Data prefix callback context. Not used in this example. */ PACKET_REQ_TIMEOUT_MS, /* AT command send timeout. */ sendTimeout, /* Binary data send timeout. */ 0U ); /* The delay between AT command and binary data. */ ``` To adapt with various cellular modems AT command, cellular interface provides the following APIs in common layer to send binary stream to modem: - @ref _Cellular_AtcmdDataSend : The general API to send the binary stream. - @ref _Cellular_TimeoutAtcmdDataSendRequestWithCallback : A compact version of _Cellular_AtcmdDataSend without pktDataSendPrefixCallback and interDelayMS parameters. - @ref _Cellular_TimeoutAtcmdDataSendSuccessToken : An extension of _Cellular_TimeoutAtcmdDataSendRequestWithCallback with extra success token. HL7802 socket send command reference port example ``` AT+KTCPSND=1,18 CONNECT // CONNECT is considered a success result code only when sending the AT+KTCPSND command // _Cellular_TimeoutAtcmdDataSendSuccessToken can be used in this case. ...Data send... --EOF--Pattern-- // Modem required the end pattern sent after the binary data. // The pEndPattern of CellularAtDataReq_t can be used in this case. OK ``` SARA-R4 socket send command reference port example ``` AT+USOWR=3,16 @16 bytes of data // "@" is not a new line. SARA-R4 port fixes the input stream in the callback. // SARA-R4 requires to wait for a minimum of 50 ms before sending data. // The interDelayMS parameter of _Cellular_AtcmdDataSend can be used in this case. +USOWR: 3,16 OK ``` */ /** @page cellular_receiving_binary_data Receiving binary data with Cellular Common APIs Receive binary data command relies on the port to indicate start and length of the binary data in the input stream. Take the socket receive command of reference port BG96 for example: ``` AT+QIRD=11,1500 // Read data received from incoming connection. +QIRD: 4 // Actual data length is 4 bytes. test // The binary data returns from the modem OK // The success result code ``` The binary data "test" should not be parsed by cellular interface. The port needs to indicate the start of binary data and the length in data prefix callback function. _Cellular_TimeoutAtcmdDataRecvRequestWithCallback is cellular common API to receive binary data from modem. BG96 port make use of this API to receive binary data with the following parameters: ``` static CellularPktStatus_t socketRecvDataPrefix( void * pCallbackContext, /* Not used in this example. */ char * pLine, /* The input buffer with response from cellular modem. */ uint32_t lineLength, /* The length of pLine. */ char ** ppDataStart, /* Start address of the binary data in pLine. */ uint32_t * pDataLength ); /* The length of the binary data. */ static CellularPktStatus_t _Cellular_RecvFuncData( CellularContext_t * pContext, /* The cellular module context. */ const CellularATCommandResponse_t * pAtResp, /* The response from cellular modem. */ void * pData, /* Point to dataRecv in this example. */ uint16_t dataLen ); /* The length of the buffer pointed by &pData. */ CellularAtReq_t atReqSocketRecv = { .pAtCmd = cmdBuf, /* In this example, AT+QIRD=11,1500. */ .atCmdType = CELLULAR_AT_MULTI_DATA_WO_PREFIX, /* The command expects multiple line or data received. */ .pAtRspPrefix = "+QIRD", /* The response prefix for this command. */ .respCallback = _Cellular_RecvFuncData, /* The callback function to parse the response from modem. */ .pData = ( void * ) &dataRecv, /* The data pointer in the callback function. */ .dataLen = bufferLength /* The length of the data pointer. */ }; pktStatus = _Cellular_TimeoutAtcmdDataRecvRequestWithCallback( pContext, /* The cellular context pointer. */ atReqSocketRecv, /* The AT command structure. */ recvTimeout, /* Timeout value for this AT command. */ socketRecvDataPrefix, /* The data prefix callback function. */ NULL ); /* The context of the data prefix callback. */ ``` The data receive callback @ref CellularATCommandDataPrefixCallback_t, socketRecvDataPrefix in this example, can return the following value to cellular interface library: - **CELLULAR_PKT_STATUS_OK** : Cellular interface libary should keep process the input buffer. The following data in the input buffer will be regarded as binary data when ppDataStart and pDataLength is set in the function.
pLine
012345678910111213141516171819
+QIRD:  4\\r\\ntest\\r\\nOK\\r\\n
^ ppDataStart point to this address in pLine
with pDataLength is set to 4.
The binary data will be stored in the response and passed to the AT command response callback function. - **CELLULAR_PKT_STATUS_SIZE_MISMATCH** : The callback function needs more data to decide the start and length of the binary data. - **Other error** : Indicate that the moden returns unexpected response. Cellular interface library calls the response callback function, _Cellular_RecvFuncData in this example, when it successfully receives the binary data from cellular modem. The @ref CellularATCommandResponse_t pAtResp parameter of _Cellular_RecvFuncData contains the following list in this example: ``` Structure | CellularATCommandResponse_t CellularATCommandLine_t CellularATCommandLine_t Name | pAtResp pAtResp->pItm pAtResp->pNext->pItm -------------| --------------------------- ------------------------- ------------------------- Member | pItm -> pNext -> pNext | pLine = "+QIRD: 4" pLine = "test" ``` */