FreeRTOS: FreeRTOS Cellular Library v1.3.0
FreeRTOS Cellular Library
cellular_common.h File Reference
#include <stdbool.h>
#include "cellular_config.h"
#include "cellular_config_defaults.h"
#include "cellular_platform.h"
#include "cellular_comm_interface.h"
#include "cellular_types.h"
#include "cellular_at_core.h"

Go to the source code of this file.

Data Structures

struct  CellularAtReq_t
 The AT command request structure. More...
 
struct  CellularAtDataReq_t
 The data command request structure. More...
 
struct  CellularAtParseTokenMap_t
 the URC token and URC handler mapping structure used by pkthanlder. More...
 
struct  CellularSocketContext_t
 Parameters involved in sending/receiving data through sockets. More...
 
struct  CellularTokenTable_t
 Parameters to setup pktio and pkthandler token tables. More...
 

Typedefs

typedef void(* CellularAtParseTokenHandler_t) (CellularContext_t *pContext, char *pInputStr)
 URC handler function. More...
 
typedef CellularPktStatus_t(* CellularATCommandDataPrefixCallback_t) (void *pCallbackContext, char *pLine, uint32_t lineLength, char **pDataStart, uint32_t *pDataLength)
 Callback used to inform pktio the data start and the length of the data. More...
 
typedef CellularPktStatus_t(* CellularATCommandDataSendPrefixCallback_t) (void *pCallbackContext, char *pLine, uint32_t *pBytesRead)
 Callback used to fix the stream before the send data. More...
 
typedef CellularPktStatus_t(* CellularUndefinedRespCallback_t) (void *pCallbackContext, const char *pLine)
 Undefined response callback function. More...
 

Enumerations

enum  CellularSocketState_t { SOCKETSTATE_ALLOCATED = 0 , SOCKETSTATE_CONNECTING , SOCKETSTATE_CONNECTED , SOCKETSTATE_DISCONNECTED }
 enum representing different Socket State. More...
 

Functions

CellularError_t _Cellular_LibInit (CellularHandle_t *pCellularHandle, const CellularCommInterface_t *pCommInterface, const CellularTokenTable_t *pTokenTable)
 One time initialization function. More...
 
CellularError_t _Cellular_LibCleanup (CellularHandle_t cellularHandle)
 One time deinitialization function. More...
 
void _Cellular_NetworkRegistrationCallback (const CellularContext_t *pContext, CellularUrcEvent_t urcEvent, const CellularServiceStatus_t *pServiceStatus)
 Call the network registration callback if the callback is previously set by Cellular_CommonRegisterUrcNetworkRegistrationEventCallback. More...
 
void _Cellular_PdnEventCallback (const CellularContext_t *pContext, CellularUrcEvent_t urcEvent, uint8_t contextId)
 Call the network registration callback if the callback is previously set by Cellular_RegisterUrcPdnEventCallback. More...
 
void _Cellular_SignalStrengthChangedCallback (const CellularContext_t *pContext, CellularUrcEvent_t urcEvent, const CellularSignalInfo_t *pSignalInfo)
 Call the network registration callback if the callback is previously set by Cellular_RegisterUrcSignalStrengthChangedCallback. More...
 
void _Cellular_GenericCallback (const CellularContext_t *pContext, const char *pRawData)
 Call the network registration callback if the callback is previously set by Cellular_RegisterUrcGenericCallback. More...
 
void _Cellular_ModemEventCallback (const CellularContext_t *pContext, CellularModemEvent_t modemEvent)
 Call the network registration callback if the callback is previously set by Cellular_RegisterModemEventCallback. More...
 
CellularError_t _Cellular_CheckLibraryStatus (CellularContext_t *pContext)
 Check Library Status. More...
 
CellularError_t _Cellular_TranslatePktStatus (CellularPktStatus_t status)
 Translate error code packet status to cellular Status. More...
 
CellularPktStatus_t _Cellular_TranslateAtCoreStatus (CellularATError_t status)
 Translate Error Code AT Core status to Packet Status. More...
 
CellularError_t _Cellular_CreateSocketData (CellularContext_t *pContext, uint8_t contextId, CellularSocketDomain_t socketDomain, CellularSocketType_t socketType, CellularSocketProtocol_t socketProtocol, CellularSocketHandle_t *pSocketHandle)
 Create a socket. More...
 
CellularError_t _Cellular_RemoveSocketData (CellularContext_t *pContext, CellularSocketHandle_t socketHandle)
 Remove the socket. More...
 
CellularError_t _Cellular_IsValidSocket (const CellularContext_t *pContext, uint32_t sockIndex)
 Check socket index validity. More...
 
CellularSocketContext_t_Cellular_GetSocketData (const CellularContext_t *pContext, uint32_t sockIndex)
 Get the socket data structure with socket index. More...
 
CellularError_t _Cellular_IsValidPdn (uint8_t contextId)
 Check PDN context index validity. More...
 
CellularError_t _Cellular_ConvertCsqSignalRssi (int16_t csqRssi, int16_t *pRssiValue)
 Convert CSQ command returned RSSI value. More...
 
CellularError_t _Cellular_ConvertCsqSignalBer (int16_t csqBer, int16_t *pBerValue)
 Convert CSQ command retruned BER value. More...
 
CellularError_t _Cellular_GetModuleContext (const CellularContext_t *pContext, void **ppModuleContext)
 Get the socket data structure with socket index. More...
 
CellularError_t _Cellular_ComputeSignalBars (CellularRat_t rat, CellularSignalInfo_t *pSignalInfo)
 Convert the signal to bar. More...
 
CellularError_t _Cellular_GetCurrentRat (CellularContext_t *pContext, CellularRat_t *pRat)
 Return the current RAT if previously received with 3GPP AT command. More...
 
CellularPktStatus_t _Cellular_AtcmdRequestWithCallback (CellularContext_t *pContext, CellularAtReq_t atReq)
 Send the AT command to cellular modem with default timeout. More...
 
CellularPktStatus_t _Cellular_TimeoutAtcmdRequestWithCallback (CellularContext_t *pContext, CellularAtReq_t atReq, uint32_t timeoutMS)
 Send the AT command to cellular modem. More...
 
CellularPktStatus_t _Cellular_AtcmdRequestSuccessToken (CellularContext_t *pContext, CellularAtReq_t atReq, uint32_t atTimeoutMS, const char **pCellularSrcTokenSuccessTable, uint32_t cellularSrcTokenSuccessTableSize)
 Send the AT command to cellular modem with extra success token table. More...
 
CellularPktStatus_t _Cellular_TimeoutAtcmdDataRecvRequestWithCallback (CellularContext_t *pContext, CellularAtReq_t atReq, uint32_t timeoutMS, CellularATCommandDataPrefixCallback_t pktDataPrefixCallback, void *pCallbackContext)
 Send the AT command to cellular modem with data buffer response. More...
 
CellularPktStatus_t _Cellular_TimeoutAtcmdDataSendRequestWithCallback (CellularContext_t *pContext, CellularAtReq_t atReq, CellularAtDataReq_t dataReq, uint32_t atTimeoutMS, uint32_t dataTimeoutMS)
 Send the AT command to cellular modem with send data. More...
 
CellularPktStatus_t _Cellular_AtcmdDataSend (CellularContext_t *pContext, CellularAtReq_t atReq, CellularAtDataReq_t dataReq, CellularATCommandDataSendPrefixCallback_t pktDataSendPrefixCallback, void *pCallbackContext, uint32_t atTimeoutMS, uint32_t dataTimeoutMS, uint32_t interDelayMS)
 Send the AT command to cellular modem with send data. More...
 
CellularPktStatus_t _Cellular_TimeoutAtcmdDataSendSuccessToken (CellularContext_t *pContext, CellularAtReq_t atReq, CellularAtDataReq_t dataReq, uint32_t atTimeoutMS, uint32_t dataTimeoutMS, const char **pCellularSrcTokenSuccessTable, uint32_t cellularSrcTokenSuccessTableSize)
 Send the AT command to cellular modem with send data and extra success token table. More...
 
CellularError_t _Cellular_RegisterUndefinedRespCallback (CellularContext_t *pContext, CellularUndefinedRespCallback_t undefinedRespCallback, void *pCallbackContext)
 Register undefined response callback. More...
 

Function Documentation

◆ _Cellular_LibInit()

CellularError_t _Cellular_LibInit ( CellularHandle_t pCellularHandle,
const CellularCommInterface_t pCommInterface,
const CellularTokenTable_t pTokenTable 
)

One time initialization function.

This function initializes and returns the supplied context. It must be called once (and only once) before calling any other function of this library.

Parameters
[in,out]pCellularHandleThe handle pointer to store the cellular handle.
[in]pCommInterfaceComm interface for communicating with the module.
[in]pTokenTableToken tables for pkthandler and pktio.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_LibCleanup()

CellularError_t _Cellular_LibCleanup ( CellularHandle_t  cellularHandle)

One time deinitialization function.

This function frees resources taken in Cellular_Init. After this function returns, Cellular_Init must be called again before calling any other function of this library.

Parameters
[in]cellularHandleThe opaque cellular context pointer created by Cellular_Init.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_NetworkRegistrationCallback()

void _Cellular_NetworkRegistrationCallback ( const CellularContext_t pContext,
CellularUrcEvent_t  urcEvent,
const CellularServiceStatus_t pServiceStatus 
)

Call the network registration callback if the callback is previously set by Cellular_CommonRegisterUrcNetworkRegistrationEventCallback.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]urcEventURC Event that happened.
[in]pServiceStatusThe status of the network service.

◆ _Cellular_PdnEventCallback()

void _Cellular_PdnEventCallback ( const CellularContext_t pContext,
CellularUrcEvent_t  urcEvent,
uint8_t  contextId 
)

Call the network registration callback if the callback is previously set by Cellular_RegisterUrcPdnEventCallback.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]urcEventURC Event that happened.
[in]contextIdContext ID of the PDN context.

◆ _Cellular_SignalStrengthChangedCallback()

void _Cellular_SignalStrengthChangedCallback ( const CellularContext_t pContext,
CellularUrcEvent_t  urcEvent,
const CellularSignalInfo_t pSignalInfo 
)

Call the network registration callback if the callback is previously set by Cellular_RegisterUrcSignalStrengthChangedCallback.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]urcEventURC Event that happened.
[in]pSignalInfoThe new signal information.

◆ _Cellular_GenericCallback()

void _Cellular_GenericCallback ( const CellularContext_t pContext,
const char *  pRawData 
)

Call the network registration callback if the callback is previously set by Cellular_RegisterUrcGenericCallback.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]pRawDataRaw data received in the URC event.

◆ _Cellular_ModemEventCallback()

void _Cellular_ModemEventCallback ( const CellularContext_t pContext,
CellularModemEvent_t  modemEvent 
)

Call the network registration callback if the callback is previously set by Cellular_RegisterModemEventCallback.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]modemEventThe modem event.

◆ _Cellular_CheckLibraryStatus()

CellularError_t _Cellular_CheckLibraryStatus ( CellularContext_t pContext)

Check Library Status.

This Functions checks if the FreeRTOS Cellular Library is already opened and set up for cellular modem operation for control and data plane function.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
Returns
CELLULAR_SUCCESS if the operation is successful , otherwise return error code.

◆ _Cellular_TranslatePktStatus()

CellularError_t _Cellular_TranslatePktStatus ( CellularPktStatus_t  status)

Translate error code packet status to cellular Status.

This Functions translates packet status to cellular Status.

Parameters
[in]statusThe packet status to translate.
Returns
The corresponding CellularError_t.

◆ _Cellular_TranslateAtCoreStatus()

CellularPktStatus_t _Cellular_TranslateAtCoreStatus ( CellularATError_t  status)

Translate Error Code AT Core status to Packet Status.

This Functions translates AT Core status to Packet Status.

Parameters
[in]statusThe AT Core status to translate.
Returns
The corresponding CellularPktStatus_t.

◆ _Cellular_CreateSocketData()

CellularError_t _Cellular_CreateSocketData ( CellularContext_t pContext,
uint8_t  contextId,
CellularSocketDomain_t  socketDomain,
CellularSocketType_t  socketType,
CellularSocketProtocol_t  socketProtocol,
CellularSocketHandle_t pSocketHandle 
)

Create a socket.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]contextIdPdn context id on which this socket needs to be created.
[in]socketDomainSocket domain.
[in]socketTypeSocket Type.
[in]socketProtocolSocket Protocol.
[out]pSocketHandleOut parameter to provide the created handle.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_RemoveSocketData()

CellularError_t _Cellular_RemoveSocketData ( CellularContext_t pContext,
CellularSocketHandle_t  socketHandle 
)

Remove the socket.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]socketHandleSocket handle returned from the Cellular_CreateSocket call.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_IsValidSocket()

CellularError_t _Cellular_IsValidSocket ( const CellularContext_t pContext,
uint32_t  sockIndex 
)

Check socket index validity.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]sockIndexSocket index returned from cellular modem.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_GetSocketData()

CellularSocketContext_t * _Cellular_GetSocketData ( const CellularContext_t pContext,
uint32_t  sockIndex 
)

Get the socket data structure with socket index.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]sockIndexSocket index returned from cellular modem.
Returns
The socket data pointer if the socket index is valid, otherwise NULL is returned.

◆ _Cellular_IsValidPdn()

CellularError_t _Cellular_IsValidPdn ( uint8_t  contextId)

Check PDN context index validity.

Parameters
[in]contextIdThe PDN context index to check.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_ConvertCsqSignalRssi()

CellularError_t _Cellular_ConvertCsqSignalRssi ( int16_t  csqRssi,
int16_t *  pRssiValue 
)

Convert CSQ command returned RSSI value.

Parameters
[in]csqRssiThe CSQ command returned RSSI index.
[out]pRssiValueThe output parameter to return the converted RSSI value in dBm.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_ConvertCsqSignalBer()

CellularError_t _Cellular_ConvertCsqSignalBer ( int16_t  csqBer,
int16_t *  pBerValue 
)

Convert CSQ command retruned BER value.

Parameters
[in]csqBerThe CSQ command returned BER index.
[out]pBerValueThe output parameter to return the converted BER value in 0.01%.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_GetModuleContext()

CellularError_t _Cellular_GetModuleContext ( const CellularContext_t pContext,
void **  ppModuleContext 
)

Get the socket data structure with socket index.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[out]ppModuleContextThe module context set in Cellular_ModuleInit function.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_ComputeSignalBars()

CellularError_t _Cellular_ComputeSignalBars ( CellularRat_t  rat,
CellularSignalInfo_t pSignalInfo 
)

Convert the signal to bar.

Parameters
[in]ratCurrent RAT of the registered network.
[in,out]pSignalInfoThe signal value of current RAT. The result bar value is assigned in this structure.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_GetCurrentRat()

CellularError_t _Cellular_GetCurrentRat ( CellularContext_t pContext,
CellularRat_t pRat 
)

Return the current RAT if previously received with 3GPP AT command.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[out]pRatCurrent RAT of the registered network.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_AtcmdRequestWithCallback()

CellularPktStatus_t _Cellular_AtcmdRequestWithCallback ( CellularContext_t pContext,
CellularAtReq_t  atReq 
)

Send the AT command to cellular modem with default timeout.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_TimeoutAtcmdRequestWithCallback()

CellularPktStatus_t _Cellular_TimeoutAtcmdRequestWithCallback ( CellularContext_t pContext,
CellularAtReq_t  atReq,
uint32_t  timeoutMS 
)

Send the AT command to cellular modem.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]timeoutMSThe timeout value to wait for the response from cellular modem.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_AtcmdRequestSuccessToken()

CellularPktStatus_t _Cellular_AtcmdRequestSuccessToken ( CellularContext_t pContext,
CellularAtReq_t  atReq,
uint32_t  atTimeoutMS,
const char **  pCellularSrcTokenSuccessTable,
uint32_t  cellularSrcTokenSuccessTableSize 
)

Send the AT command to cellular modem with extra success token table.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]atTimeoutMSThe timeout value to wait for the AT command response from cellular modem.
[in]pCellularSrcTokenSuccessTableThe extra success token table to indicate the send AT command success.
[in]cellularSrcTokenSuccessTableSizeThe size of extra success token table.
Note
AT command request makes use of cellularSrcTokenSuccessTableSize to obtain the response status. Some AT commands don't have fixed success token. This function make use of a temporary table, pCellularSrcTokenSuccessTable, to obtain the response status.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_TimeoutAtcmdDataRecvRequestWithCallback()

CellularPktStatus_t _Cellular_TimeoutAtcmdDataRecvRequestWithCallback ( CellularContext_t pContext,
CellularAtReq_t  atReq,
uint32_t  timeoutMS,
CellularATCommandDataPrefixCallback_t  pktDataPrefixCallback,
void *  pCallbackContext 
)

Send the AT command to cellular modem with data buffer response.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]timeoutMSThe timeout value to wait for the response from cellular modem.
[in]pktDataPrefixCallbackThe callback function to indicate the start of data and the length of data.
[in]pCallbackContextThe pCallbackContext passed to the pktDataPrefixCallback callback function.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_TimeoutAtcmdDataSendRequestWithCallback()

CellularPktStatus_t _Cellular_TimeoutAtcmdDataSendRequestWithCallback ( CellularContext_t pContext,
CellularAtReq_t  atReq,
CellularAtDataReq_t  dataReq,
uint32_t  atTimeoutMS,
uint32_t  dataTimeoutMS 
)

Send the AT command to cellular modem with send data.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]dataReqThe following data request after the at request.
[in]atTimeoutMSThe timeout value to wait for the AT command response from cellular modem.
[in]dataTimeoutMSThe timeout value to wait for the data command response from cellular modem.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_AtcmdDataSend()

CellularPktStatus_t _Cellular_AtcmdDataSend ( CellularContext_t pContext,
CellularAtReq_t  atReq,
CellularAtDataReq_t  dataReq,
CellularATCommandDataSendPrefixCallback_t  pktDataSendPrefixCallback,
void *  pCallbackContext,
uint32_t  atTimeoutMS,
uint32_t  dataTimeoutMS,
uint32_t  interDelayMS 
)

Send the AT command to cellular modem with send data.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]dataReqThe following data request after the at request.
[in]pktDataSendPrefixCallbackThe callback function to inidcate the data sending start.
[in]pCallbackContextThe callback context pass to pktDataSendPrefixCallback function.
[in]atTimeoutMSThe timeout value to wait for the AT command response from cellular modem.
[in]dataTimeoutMSThe timeout value to wait for the data command response from cellular modem.
[in]interDelayMSThe delay between AT command and data send.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_TimeoutAtcmdDataSendSuccessToken()

CellularPktStatus_t _Cellular_TimeoutAtcmdDataSendSuccessToken ( CellularContext_t pContext,
CellularAtReq_t  atReq,
CellularAtDataReq_t  dataReq,
uint32_t  atTimeoutMS,
uint32_t  dataTimeoutMS,
const char **  pCellularSrcTokenSuccessTable,
uint32_t  cellularSrcTokenSuccessTableSize 
)

Send the AT command to cellular modem with send data and extra success token table.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]atReqThe AT command data structure with send command response callback.
[in]dataReqThe following data request after the at request.
[in]atTimeoutMSThe timeout value to wait for the AT command response from cellular modem.
[in]dataTimeoutMSThe timeout value to wait for the data command response from cellular modem.
[in]pCellularSrcTokenSuccessTableThe extra success token table to indicate the send AT command success.
[in]cellularSrcTokenSuccessTableSizeThe size of extra success token table.
Returns
CELLULAR_PKT_STATUS_OK if the operation is successful, otherwise an error code indicating the cause of the error.

◆ _Cellular_RegisterUndefinedRespCallback()

CellularError_t _Cellular_RegisterUndefinedRespCallback ( CellularContext_t pContext,
CellularUndefinedRespCallback_t  undefinedRespCallback,
void *  pCallbackContext 
)

Register undefined response callback.

Cellular module can register the callback function to handle AT_UNDEFINED response through this function.

Parameters
[in]pContextThe opaque cellular context pointer created by Cellular_Init.
[in]undefinedRespCallbackThe callback function to handle the undefined response.
[in]pCallbackContextThe pCallbackContext passed to the undefinedRespCallback callback function if undefinedRespCallback is not NULL.
Returns
CELLULAR_SUCCESS if the operation is successful, otherwise an error code indicating the cause of the error.