/**
@mainpage Overview
@anchor cellular
@brief FreeRTOS Cellular library

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

<b>FreeRTOS Cellular Library</b>
- <b>Repository structure</b><br>
This library contains the following three components in three folders.
| FreeRTOS Cellular Library folders | High Level Description |
| :--------------------| :--------------------- |
| source               | Reusable common code that implements the standard AT commands defined by 3GPP TS v27.007. |
| docs                 | Documentations. |
| test                 | Unit test and cbmc. |
| tools                | tools for Coverity static analysis and CMock. |

- <b>Supported cellular modules</b><br>
Three cellular modules are supported in this library.
| Cellular module |
| :--------------------|
| [Quectel BG96](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-Quectel-BG96)         |
| [Sierra HL7802](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-Sierra-Wireless-HL7802)        |
| [Ublox SARA R4 series](https://github.com/FreeRTOS/FreeRTOS-Cellular-Interface-Reference-ublox-SARA-R4) |
New cellular module can reference these module porting to be integrated into FreeRTOS Cellular Library.<br>
Please reference [Porting module Guide](https://www.freertos.org/Documentation/api-ref/cellular/cellular_porting_module_guide.html) document for detail information about porting new cellular module.
- <b>Currently Supported Features in FreeRTOS Cellular Library</b>
 - User of FreeRTOS Cellular Library is able to use Cat-M1 cellular technology to connect to network.
 - User of FreeRTOS Cellular Library is able to perform control plane operations like (initialize modem, register on a network etc.) in a vendor agnostic way.
 - User of FreeRTOS Cellular Library is able to send and receive data using TCP/IP in a vendor agnostic way given that TCP/IP stack is running on the cellular modem.
 - User of FreeRTOS Cellular Library is able to put the modem in different low power modes (PSM and eDRX) in a vendor agnostic way.
 - User of FreeRTOS Cellular Library is able to receive asynchronous notifications about various events like "disconnected", "signal strength changed" etc. to enable them to take appropriate action as desired.
 - User of FreeRTOS Cellular Library is able to use the existing application protocol clients (MQTT, HTTP) over cellular seamlessly. i.e. any existing user application using MQTT which works over WiFi/Ethernet shall work over Cellular given the underlying cellular technology permits that.<br>


@section cellular_memory_requirements Memory Requirements
@brief Memory requirements of the Cellular library.

@include{doc} size_table.md
 */

/**
@page Design

@section FreeRTOS_Cellular_Library_Design Cellular Interface Design

FreeRTOS Cellular Library uses communication interface to communicate with cellular modules.<br>
Users of FreeRTOS Cellular Library should create a instance of CellularCommInterface and pass it
to Cellular_Init function as paremeters.

\image html comm_interaction.png "Cellular library interacts with comm interface" width=800px

The following communication interface implementation can be used as reference.
- <a href="https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/pc/boards/windows/ports/comm_if/comm_if_windows.c">FreeRTOS windows simulator comm interface </a>
- <a href="https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/st/boards/stm32l475_discovery/ports/comm_if/comm_if_st.c"> STM32 L475 discovery board comm interface </a>
- <a href="https://github.com/aws/amazon-freertos/blob/feature/cellular/vendors/sierra/boards/sensorhub/ports/comm_if/comm_if_sierra.c"> Sierra sensorhub board comm interface </a>
<b></b>

@section cellular_socket_api_desing Cellular Socket API Design

FreeRTOS Cellular Interface offloads the TCP/IP stacks to cellular module. The implementation
of the socket APIs use module specific AT commands. Cellular socket APIs abstract the differences
between different cellular module. The following are cellular socket APIs:
- @ref Cellular_CreateSocket
- @ref Cellular_SocketSetSockOpt
- @ref Cellular_SocketSend
- @ref Cellular_SocketRecv
- @ref Cellular_SocketClose
- @ref Cellular_GetHostByName
- @ref Cellular_SocketRegisterDataReadyCallback
- @ref Cellular_SocketRegisterClosedCallback
- @ref Cellular_SocketRegisterSocketOpenCallback

Cellular socket APIs and cellular modem events change cellular socket state.
See the below graph for the socket state transitions:
@image html cellular_socket_state.png width=70%
*/

/**
@page cellular_config Configurations
@brief Configurations of the Cellular Library.

Some configuration settings are C pre-processor constants, and some are function-like macros for logging. They can be set with a `#define` in the config file (**cellular_config.h**) or by using a compiler option such as -D in gcc.

@section CELLULAR_DO_NOT_USE_CUSTOM_CONFIG
@copydoc CELLULAR_DO_NOT_USE_CUSTOM_CONFIG

@section CELLULAR_MCC_MAX_SIZE
@copydoc CELLULAR_MCC_MAX_SIZE

@section CELLULAR_MNC_MAX_SIZE
@copydoc CELLULAR_MNC_MAX_SIZE

@section CELLULAR_ICCID_MAX_SIZE
@copydoc CELLULAR_ICCID_MAX_SIZE

@section CELLULAR_IMSI_MAX_SIZE
@copydoc CELLULAR_IMSI_MAX_SIZE

@section CELLULAR_FW_VERSION_MAX_SIZE
@copydoc CELLULAR_FW_VERSION_MAX_SIZE

@section CELLULAR_HW_VERSION_MAX_SIZE
@copydoc CELLULAR_HW_VERSION_MAX_SIZE

@section CELLULAR_SERIAL_NUM_MAX_SIZE
@copydoc CELLULAR_SERIAL_NUM_MAX_SIZE

@section CELLULAR_IMEI_MAX_SIZE
@copydoc CELLULAR_IMEI_MAX_SIZE

@section CELLULAR_NETWORK_NAME_MAX_SIZE
@copydoc CELLULAR_NETWORK_NAME_MAX_SIZE

@section CELLULAR_APN_MAX_SIZE
@copydoc CELLULAR_APN_MAX_SIZE

@section CELLULAR_PDN_USERNAME_MAX_SIZE
@copydoc CELLULAR_PDN_USERNAME_MAX_SIZE

@section CELLULAR_PDN_PASSWORD_MAX_SIZE
@copydoc CELLULAR_PDN_PASSWORD_MAX_SIZE

@section CELLULAR_IP_ADDRESS_MAX_SIZE
@copydoc CELLULAR_IP_ADDRESS_MAX_SIZE

@section CELLULAR_AT_CMD_MAX_SIZE
@copydoc CELLULAR_AT_CMD_MAX_SIZE

@section CELLULAR_NUM_SOCKET_MAX
@copydoc CELLULAR_NUM_SOCKET_MAX

@section CELLULAR_MANUFACTURE_ID_MAX_SIZE
@copydoc CELLULAR_MANUFACTURE_ID_MAX_SIZE

@section CELLULAR_MODEL_ID_MAX_SIZE
@copydoc CELLULAR_MODEL_ID_MAX_SIZE

@section CELLULAR_EDRX_LIST_MAX_SIZE
@copydoc CELLULAR_EDRX_LIST_MAX_SIZE

@section CELLULAR_PDN_CONTEXT_ID_MIN
@copydoc CELLULAR_PDN_CONTEXT_ID_MIN

@section CELLULAR_PDN_CONTEXT_ID_MAX
@copydoc CELLULAR_PDN_CONTEXT_ID_MAX

@section CELLULAR_MAX_RAT_PRIORITY_COUNT
@copydoc CELLULAR_MAX_RAT_PRIORITY_COUNT

@section CELLULAR_MAX_SEND_DATA_LEN
@copydoc CELLULAR_MAX_SEND_DATA_LEN

@section CELLULAR_MAX_RECV_DATA_LEN
@copydoc CELLULAR_MAX_RECV_DATA_LEN

@section CELLULAR_SUPPORT_GETHOSTBYNAME
@copydoc CELLULAR_SUPPORT_GETHOSTBYNAME

@section CELLULAR_COMM_IF_SEND_TIMEOUT_MS
@copydoc CELLULAR_COMM_IF_SEND_TIMEOUT_MS

@section CELLULAR_COMM_IF_RECV_TIMEOUT_MS
@copydoc CELLULAR_COMM_IF_RECV_TIMEOUT_MS

@section CELLULAR_CONFIG_STATIC_ALLOCATION_CONTEXT
@copydoc CELLULAR_CONFIG_STATIC_ALLOCATION_CONTEXT

@section CELLULAR_CONFIG_STATIC_COMM_CONTEXT_ALLOCATION
@copydoc CELLULAR_CONFIG_STATIC_COMM_CONTEXT_ALLOCATION

@section CELLULAR_CONFIG_DEFAULT_RAT
@copydoc CELLULAR_CONFIG_DEFAULT_RAT

@section CELLULAR_CONFIG_STATIC_SOCKET_CONTEXT_ALLOCATION
@copydoc CELLULAR_CONFIG_STATIC_SOCKET_CONTEXT_ALLOCATION

@section cellular_logerror LogError
@copydoc LogError

@section cellular_logwarn LogWarn
@copydoc LogWarn

@section cellular_loginfo LogInfo
@copydoc LogInfo

@section cellular_logdebug LogDebug
@copydoc LogDebug

@section CELLULAR_MODEM_NO_EPS_NETWORK
@brief Macro to disable querying evolved packet system (EPS) network registration status in Cellular_CommonGetServiceStatus.<br>
@note Cellular modem porting can define this macro in cellular_config.h to disable this function.<br>

<b>Default value:</b> undefined

*/

/**
@page cellular_functions Functions
@brief Functions of the cellular library.<br><br>

<b>Control plane APIs</b>

- @ref Cellular_Init
- @ref Cellular_Cleanup
- @ref Cellular_SetRatPriority
- @ref Cellular_GetRatPriority
- @ref Cellular_RfOn
- @ref Cellular_RfOff

<b>Hardware info</b>

- @ref Cellular_GetSimCardStatus
- @ref Cellular_GetSimCardInfo
- @ref Cellular_GetModemInfo

<b>Network registration</b>

- @ref Cellular_GetRegisteredNetwork
- @ref Cellular_GetNetworkTime
- @ref Cellular_GetSignalInfo
- @ref Cellular_GetServiceStatus

<b>Enable data network</b>

- @ref Cellular_SetPdnConfig
- @ref Cellular_GetPdnStatus
- @ref Cellular_ActivatePdn
- @ref Cellular_DeactivatePdn
- @ref Cellular_GetIPAddress
- @ref Cellular_SetDns

<b>Device and network status callback functions</b>

- @ref Cellular_RegisterUrcNetworkRegistrationEventCallback
- @ref Cellular_RegisterUrcPdnEventCallback
- @ref Cellular_RegisterUrcSignalStrengthChangedCallback
- @ref Cellular_RegisterModemEventCallback
- @ref Cellular_RegisterUrcGenericCallback

<b>Power saveing modes</b>

- @ref Cellular_GetPsmSettings
- @ref Cellular_SetPsmSettings
- @ref Cellular_GetEidrxSettings
- @ref Cellular_SetEidrxSettings

<b>Custom AT command</b>

- @ref Cellular_ATCommandRaw

<b>Data plan APIs</b>

- @ref Cellular_CreateSocket
- @ref Cellular_SocketConnect
- @ref Cellular_SocketSend
- @ref Cellular_SocketRecv
- @ref Cellular_SocketClose
- @ref Cellular_GetHostByName
- @ref Cellular_SocketSetSockOpt
- @ref Cellular_SocketRegisterSocketOpenCallback
- @ref Cellular_SocketRegisterDataReadyCallback
- @ref Cellular_SocketRegisterClosedCallback
*/

/**
@page cellular_porting Porting Guide
@brief Guide for porting Cellular library to a new platform.

To use the Cellular library, a platform must implement the following components:
1. [Configuration Macros](@ref cellular_porting_config)
2. [Cellular Communication Interface](@ref cellular_porting_comm_if)
3. [Cellular platform dependency](@ref cellular_platform_dependency)

@section cellular_porting_config Configuration Macros
@brief 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 @ref CELLULAR_DO_NOT_USE_CUSTOM_CONFIG macro must be defined.

@see [Configurations](@ref cellular_config)

In addition, the following logging macros are used throughout the library:
 - @ref LogError
 - @ref LogWarn
 - @ref LogInfo
 - @ref LogDebug

@section cellular_porting_comm_if Cellular Communication Interface
@brief FreeRTOS Cellular Library use communication interface to communicate with cellular modules.

CellularCommInterface includes the following four function pointers.
Reference the document page for prototype.
- @subpage CellularCommInterfaceOpen_t
@copybrief CellularCommInterfaceOpen_t
- @subpage CellularCommInterfaceSend_t
@copybrief CellularCommInterfaceSend_t
- @subpage CellularCommInterfaceRecv_t
@copybrief CellularCommInterfaceRecv_t
- @subpage CellularCommInterfaceClose_t
@copybrief CellularCommInterfaceClose_t

@section cellular_platform_dependency Cellular platform dependency
@brief Cellular platform depndency

FreeRTOS Cellular Library makes use of the following OS platform functions.<br>
<b>"cellular_platform.h"</b> is referenced during FreeRTOS Cellular Library compilation.<br>
User of FreeRTOS Cellular Library should provide these APIs and data structures in "cellular_platform.h".<br>
A default implementation with FreeRTOS is provided in FreeRTOS Labs cellular demo.
 - <b>Threads</b><br>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 )
```
 - <b>Mutex</b><br>The following APIs and data structure should be provided in cellular_platform.h.<br>
 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 );
```
 - <b>Memory</b><br>The following malloc/free style APIs should be provided in cellular_platform.h.<br>
 The <a href="https://www.freertos.org/a00111.html">FreeRTOS memory management document</a> can be referenced for these APIs.
```
// Example implementation of FreeRTOS malloc/free
#define Platform_Malloc    pvPortMalloc
#define Platform_Free      vPortFree
```
 - <b>EventGroup</b><br>The following APIs and handle should be provided in cellular_platform.h.<br>
 Please reference <a href="https://www.freertos.org/event-groups-API.html">FreeRTOS EvengGroup function prototypes</a>.
```
// 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

```
 - <b>Delay</b><br>The following API should be provided in cellular_platform.h.<br>
 Please reference <a href="https://www.freertos.org/a00127.html">FreeRTOS Task Control function prototypes</a>.
```
// Example implementation of FreeRTOS Task Control
#define Platform_Delay( delayMs )           vTaskDelay( pdMS_TO_TICKS( delayMs ) )
```
*/

/**
 * @paramstructs_group{cellular,Cellular}
 * @paramstructs_brief{cellular,cellular}
 */

/**
 * @handles_group{cellular,Cellular}
 * @handles_brief{cellular library}
 */

/**
 * @functionpointers_group{cellular,Cellular}
 * @functionpointers_brief{cellular library}
 */

/**
 * @enums_group{cellular,Cellular}
 * @enums_brief{cellular library}
 */