Modem Driver

Driver API for LTE-FDD, LTE-TDD, and GPRS modules from Quectel (such as EG915, EC21, etc.) Based on the ARM CMSIS-Driver, which can work on various ARM-based MCUs.

This is a C library that provides an interface to communicate with a modem device using AT commands. The library supports various modem operations, such as power control, network registration, TCP/IP connection, and HTTP requests.

The GSM library:

provides callback functions to handle asynchronous events and data from the modem.
consists of two main components: the modem driver and the modem API. The modem driver is responsible for sending and receiving AT commands to and from the modem device using a serial interface. The modem API is responsible for providing high-level functions to perform common modem tasks, such as activating a PDP context, sending an HTTP request, or receiving an SMS message.
designed to be portable and easy to use. It can be integrated with any embedded system that has a serial interface and a modem device. The library can be configured using various macros and structures to suit different applications and modem models.
includes some examples to demonstrate how to use the library functions and features. The examples show how to perform basic modem operations, such as initializing the modem driver, powering on the modem device, sending an HTTP GET request. The tests show how to verify the functionality and performance of the library using different scenarios and parameters.

The GSM library documentation provides detailed information about the library components, functions, structures, macros, and constants, It also explains how to use the library in different contexts and situations.

Figure 2 Block Diagram of the modem interface

The following header files define the Application Programming Interface (API) for the Modem interface:

Driver_Modem.h : Driver API for Modem

The driver Modem provides access to the following interfaces:

Control interface : setup and control the Modem module.
Management interface : allows you to configure and manage the data connectivity on LTE-FDD, LTE-TDD, and GPRS networks.
Socket interface : provides the interface to an IP stack that is running on the Modem module. This IP stack handles data communication. (Reserved for the next releases)
HTTP interface : The HTTP interface is a lightweight Application Programming Interface (API) that is hosted in the Modem. The HTTP interface provides access to table data in the Modem through a structured URI format that uses HTTP POST, and GET requests.

The Modem interface usually requires CMSIS-RTOS features (i.e., mutex) and is often implemented with a peripheral device that is connected to the system using the SPI or UART interface.

Usage

HTTP GET Request:

This example shows how to send an HTTP GET request to a web server and receive the response using the modem driver. The steps are as follows:

Define the maximum size of the HTTP response buffer and declare an array to store the HTTP response.
Specify the HTTP URL to request and declare variables to store the status, socket and PDP context.
Declare a pointer to the modem driver and a struct to store the HTTP configuration.
Initialize the modem driver with no callback function and power on the modem driver with full power mode.
Set the context ID and type for TCP/IP connection and the APN for the network provider.
Activate the PDP context and get the socket and PDP information. Check if the activation was successful and the PDP context is activated.
Set the HTTP method to GET, the HTTP URL to request, the pointer to the response buffer, the maximum length of the response buffer, and the timeouts for inputting and receiving HTTP data.
Send the HTTP GET request and get the status code. Check if the status code is positive and do something with the http_response_buffer.

// Define the maximum size of the HTTP response buffer
#define MODEM_FRAME_SIZE 1000

// Declare a char array to store the HTTP response
char http_response_buffer[MODEM_FRAME_SIZE];

// Specify the HTTP URL to request
const char HTTP_URL[] = "http://foo.bar";

// Declare variables to store the status, socket and PDP context
int32_t status;
int32_t socket = -1;
MOD_CONTEXT_CONFIG tcp;
MOD_PDP_CONTEXT pdp;

// Declare a pointer to the modem driver
MOD_DRIVER *modem = &MOD_DRIVER0;

// Declare a struct to store the HTTP configuration
MOD_HTTP_t httpd ={0};

// Initialize the modem driver with no callback function
modem->Initialize(NULL);

// Power on the modem driver with full power mode
modem->PowerControl (MOD_POWER_FULL);

// Set the context ID and type for TCP/IP connection
tcp.contextID = MOD_DEFAULT_CONTEXT;
tcp.context_type = MOD_PDP_CONTEXT_TYPE_IPV4;

// Set the APN for the network provider
tcp.APN = (uint8_t *)"mtnirancell";

// Activate the PDP context and get the socket and PDP information
socket = modem->Activate(&tcp, &pdp);

// Check if the activation was successful and the PDP context is activated
if(socket < 0){
  // Handle the activation error
  return -1;
} else if(pdp.state == MOD_PDP_CONTEXT_ACTIVATED){
  // Set the HTTP method to GET
  httpd.method = MOD_HTTP_GET;

  // Set the HTTP URL to request
  httpd.url = (uint8_t *)HTTP_URL;

  // Set the pointer to the response buffer
  httpd.response = (uint8_t *)http_response_buffer;

  /* 
   * Due to the limitations of the AT-Command protocol and for 
   * stability improvements, the length of the content should 
   * be retrieved from the header of the server response.
   * 
   * For the server response without content-length, 
   * response_length is used as the reference.
   * 
   */

  // Set the maximum length of the response buffer
  httpd.response_length = MODEM_FRAME_SIZE;

  // Set the timeout for inputting HTTP GET request information in seconds
  httpd.timeout = 80;

  // Set the timeout for receiving HTTP response in seconds
  httpd.resptime = 80;

  // Send the HTTP GET request and wait for the response and the status code
  status = modem->HTTP(socket, &httpd);

  // Check if the status code is positive
  if(status > 0){
    // Do something with the http_response_buffer
  }
}

HTTP GET Response Callback:

This code snippet shows how to use a callback function to handle the HTTP response data when sending an HTTP GET request to a web server.

The code performs the following steps:

Define the maximum size of the HTTP response buffer and declare an array to store the HTTP response.
Specify the HTTP URL to request and declare variables to store the status, socket and PDP context.
Declare a pointer to the modem driver and a struct to store the HTTP configuration.
Initialize the modem driver with no callback function and power on the modem driver with full power mode.
Set the context ID and type for TCP/IP connection and the APN for the network provider.
Activate the PDP context and get the socket and PDP information. Check if the activation was successful and the PDP context is activated.
Set the HTTP method to GET, the HTTP URL to request, the pointer to the response buffer, the maximum length of the response buffer, and the timeouts for inputting and receiving HTTP data.
Set the callback function to handle the fragmented response data.
Send the HTTP GET request and get the status code. Check if the status code is positive and do something with the http_response_buffer.

#include "Driver_Modem.h"
#include <stdio.h>


// define the number of HTTP header fields to be sent
#define HEADER_NFIELDS	2
// define the maximum size of data frame for modem communication
#define MODEM_MAX_FRAME_SIZE 1000
// define the size of buffer for HTTP header fields
#define HTTP_HEADER_BUFFER_SIZE 500


// declare the modem driver structure from external source
extern MOD_DRIVER MOD_DRIVER0;


// allocate memory for HTTP header buffer
char HTTP_Header_Buffer[HTTP_HEADER_BUFFER_SIZE];
// It allocates memory for the HTTP response buffer, which must be twice the size of the response length in case there is a response callback
char HTTP_Response_Buffer[MODEM_MAX_FRAME_SIZE * 2U ]; 
// define the HTTP URL to send the request to
const char HTTP_URL[]="http://foo.bar";

// initialize an array of HTTP header fields with key-value pairs
HTTP_HeaderField header_fields[HEADER_NFIELDS] = {
	{"Cookie", "__cfduid=d187bc66b10ad8d45a48801d6b470c3491595316310"},
	{"Content-Type", "application/json"},
};


/**
 * \brief modem main thread
 */
void modem_main(){
	// status variable for error checking
	int32_t status; 
	// socket variable for modem activation
	int32_t socket = -1; 
	// pointer to modem driver structure
	MOD_DRIVER *modem = &MOD_DRIVER0; 
	// structure for TCP context configuration
	MOD_CONTEXT_CONFIG tcp; 
	// structure for PDP context information
	MOD_PDP_CONTEXT pdp; 
	// structure for HTTP request parameters
	MOD_HTTP_t httpd ={0}; 
	// structure for HTTP header fields
	MOD_Header_t header = {0}; 


	// power up the modem serial interface
	// Modem_Serial_PowerUp(); 

	// initialize the modem driver
	status = modem->Initialize(NULL); 
	if (status != MOD_DRIVER_OK){
		// handle initialization error
	}

	// set the modem power to full
	status = modem->PowerControl (MOD_POWER_FULL); 
	if (status != MOD_DRIVER_OK){
		// handle power control error
	}

	// set the TCP context configuration parameters
	// use the default context ID
	// use IPv4 protocol type
	// tcp.authentication set the authentication type (see MOD_PDPContextAuthentication_t structure)
	// tcp.username set the username (optional)
	// tcp.password set the password (optional)
	tcp.contextID = MOD_DEFAULT_CONTEXT; 
	tcp.context_type = MOD_PDP_CONTEXT_TYPE_IPV4; 
	tcp.APN = (uint8_t *)"mtnirancell"; // use the specified APN name

	// activate the modem using the default mode and get the PDP context information
	socket = modem->Activate(MOD_ACTIVATE_DEFAULT, &pdp); 
	// check if the activation was successful
	if(socket < 0){ 
		// handle activation error
	}	else {

		// get the PDP context information from pdp structure
		// pdp.type;            protocol type (integer)
		// pdp.remote_ip4[4];   remote IP address (IPv4)
		// pdp.remote_ip6[6];   remote IP address (IPv6)
		
		// set the HTTP header fields from header_fields array
		header.fields = header_fields;
		header.nfield = HEADER_NFIELDS;
		header.buffer = HTTP_Header_Buffer;
		
		// set the HTTP request parameters from httpd structure
		httpd.header = &header; // pointer to header structure
		httpd.method = MOD_HTTP_GET; // HTTP method (GET)
		httpd.url = (uint8_t *)HTTP_URL; // URL to send the request to
		httpd.response = (uint8_t *)HTTP_Response_Buffer; // buffer to store the response data
		httpd.response_length = MODEM_MAX_FRAME_SIZE; // maximum size of response data
		httpd.response_callback = &HTTP_Response_Fetch; // callback function to handle fragmented response data
		httpd.timeout = 80; // timeout value for HTTP request (in seconds)
		httpd.resptime = 80; // response time value for HTTP request (in seconds)
		
		status = modem->HTTP(socket, &httpd); // send the HTTP request using the socket and get the status
		
		if(status > 0){
			// handle successful HTTP request
		} else {
			// handle HTTP request error
		}
		
	}
}


/**
 * \brief HTTP Response callback that is used to receive fragmented HTTP content.
 * \param data: pointer to response buffer
 * \param counter: the number of data chunks received so far
 * \param pending_size: the remaining size of the data to be received
 * \param data_size: the size of the current data chunk
 */
void HTTP_Response_Fetch (uint8_t *data, uint32_t counter, uint32_t pending_size, uint32_t data_size){
    static FILE *fp; // file pointer to write data to a file
    if(counter == 0){ // start of data
        fp = fopen("foo.bar","w"); // open a file named sample.txt in write mode
        if(fp == NULL){ // check if the file is opened successfully
            printf("Error opening file\n");
            return;
        }
    }
    if(pending_size == 0){ // end of data
        fclose(fp); // close the file
    } else{
        fwrite(data, 1, data_size, fp); // write the current data chunk to the file
    }
}

GetVersion: can be called at any time to obtain version information of the driver interface.
GetCapabilities: can be called at any time to obtain capabilities of the driver interface.
Initialize: must be called before powering the peripheral using PowerControl. This function performs the following:
- allocate I/O resources.
  - register an optional SignalEvent callback function.
SignalEvent: is an optional callback function that is registered with the Initialize function. This callback function is initiated from interrupt service routines and indicates hardware events or the completion of a data block transfer operation.
PowerControl: Controls the power profile of the peripheral and needs to be called after Initialize. Typically, three power options are available:
- MOD_POWER_FULL: Peripheral is turned on and fully operational. The driver initializes the peripheral registers, interrupts, and (optionally) DMA.
- MOD_POWER_LOW: (optional) Peripheral is in low power mode and partially operational; usually, it can detect external events and wake-up.
- MOD_POWER_OFF: Peripheral is turned off and not operational (pending operations are terminated). This is the state after device reset.
Uninitialize: Complementary function to Initialize. Releases the I/O pin resources used by the interface.
Control: Several drivers provide a control function to configure communication parameters or execute miscellaneous control functions.

Cortex-M Processor Mode

The driver functions access peripherals and interrupts and are designed to execute in Privileged mode. When calling driver functions from RTOS threads, it should be ensured that these threads execute in Privileged mode.

Function Call Sequence

For normal operation of the driver, the API functions GetVersion , GetCapabilities , Initialize , PowerControl , Uninitialize are called in the following order:

The functions GetVersion and GetCapabilities can be called any time to obtain the required information from the driver. These functions return always the same information.

Start Sequence

To start working with a peripheral the functions Initialize and PowerControl need to be called in this order:

drv-\>Initialize (...); // Allocate I/O pins

drv-\>PowerControl (MOD\_POWER\_FULL); // Power up peripheral, setup IRQ/DMA

Initialize typically allocates the I/O resources (pins) for the peripheral. The function can be called multiple times; if the I/O resources are already initialized it performs no operation and just returns with MOD_DRIVER_OK.
PowerControl (MOD_POWER_FULL) sets the peripheral registers including interrupt (NVIC) and optionally DMA. The function can be called multiple times; if the registers are already set it performs no operation and just returns with MOD_DRIVER_OK.

Stop Sequence

To stop working with a peripheral the functions PowerControl and Uninitialize need to be called in this order:

// Terminate any pending transfers, reset IRQ/DMA, power off peripheral
 drv-\>PowerControl (MOD\_POWER\_OFF);
 drv-\>Uninitialize (...); // Release I/O pins

The functions PowerControl and Uninitialize always execute and can be used to put the peripheral into a Safe State , for example after any data transmission errors. To restart the peripheral in an error condition, you should first execute the Stop Sequence and then the Start Sequence.

PowerControl (MOD_POWER_OFF) terminates any pending data transfers with the peripheral, disables the peripheral and leaves it in a defined mode (typically the reset state).
- when DMA is used it is disabled (including the interrupts)
- peripheral interrupts are disabled on NVIC level
- the peripheral is reset using a dedicated reset mechanism (if available) or by clearing the peripheral registers
- pending peripheral interrupts are cleared on NVIC level
- driver variables are cleared
Uninitialize always releases I/O pin resources.

Access Struct:

The Modem Driver as a semi-standard CMSIS-Driver publishes an Access Struct with the data type name MOD_DRIVER_xxxx that gives to access the driver functions. (Driver_Modem.h)

/* Exported MOD_DRIVER# */
MOD_DRIVER MOD_DRIVER_(MOD_DRIVER_NUMBER) = {
  MOD_GetVersion,
  MOD_GetCapabilities,
  MOD_Initialize,
  MOD_Uninitialize,
  MOD_PowerControl,
  MOD_Activate,
  MOD_Deactivate,
  MOD_Context,
  MOD_HTTP_SetOption,
  MOD_HTTP_GetOption,
  MOD_SetURL,
  MOD_HTTP,
  MOD_Release,
  MOD_SSL_SetOption,
};

Note: socket related methods reserved for the next releases.

Modem Control:

Control functions for the Modem module.

Typedef Documentation:

MOD_SignalEvent_t:

Pointer to MOD_SignalEvent: Signal Modem Event (description below).
Provides the typedef for the callback function MOD_SignalEvent.
Parameter for:
- MOD_Initialize

Function Documentation:

MOD_GetVersion

•	MOD_DRIVER_VERSION MOD_GetVersion (void)

Get driver version .

Returns

MOD_DRIVER_VERSION

Notes:

The function returns version information of the driver implementation in MOD_DRIVER_VERSION .
API version is the version of the driver specification used to implement this driver .
Driver version is source code version of the actual driver implementation .

Example :

extern MOD_DRIVER MOD_DRIVER0;

void get_version (void)  {
  MOD_DRIVER *modem = &MOD_DRIVER0;
  MOD_DRIVER_VERSION version;

  version = modem->GetVersion ();
  if (version.api < 0x100U) {        // requires at minimum API version 1.0 or higher
    // error handling
    return;
  }
}

MOD_Initialize

•	int32_t MOD_Initialize (MOD_SignalEvent_t cb_event)

Initialize Modem Module .

Parameters

[in] cb_event: Pointer to MOD_SignalEvent

Returns

execution status
- MOD_DRIVER_OK : Operation successful
- MOD_DRIVER_ERROR : Operation failed

This function is called when the RTOS starts operation and performs the following operations :

Initializes the resources and peripherals required for the module .
Registers the MOD_SignalEvent_t callback function .

The parameter cb_event is a pointer to the MOD_SignalEvent callback function ; use a NULL pointer when no callback signals are required .

Example :

extern MOD_DRIVER MOD_DRIVER0;
 
void initialize_modem (void) {
  MOD_DRIVER *modem = &MOD_DRIVER0;

  // Initialize and Power-on Module
  modem->Initialize (NULL);
  modem->PowerControl (MOD_POWER_FULL);
 
}

MOD_Uninitialize

•	int32_t  MOD_Uninitialize 	(void)

De - initialize Modem Module .

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed

The function de - initializes the resources of the Modem module.

The MOD_Uninitialize dunction is called when the middleware component stops operation and releases the software resources used by the module .

Example :

extern MOD_DRIVER MOD_DRIVER0;

void uninitialize_modem (void) {
  MOD_DRIVER *modem = &MOD_DRIVER0;
 
  // Power off and De-initialize Module
  modem->PowerControl (MOD_POWER_OFF);
  modem->Uninitialize ();
}

MOD_PowerControl

•	int32_t 	MOD_PowerControl 	(MOD_POWER_STATE	 state)

Control Modem Module Power .

Parameters

[in] state: Power state
- MOD_POWER_OFF: Power off : no operation possible
- MOD_POWER_LOW: Low - power sleep mode ;
- MOD_POWER_FULL: Power on : full operation at maximum performance

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_UNSUPPORTED: Operation not supported
- MOD_DRIVER_ERROR_PARAMETER: Parameter error (invalid state)

The function allows you to configure the power modes of the Modem module and the parameter state specifies the MOD_POWER_STATE .

Notes:

In sleep mode waking up the main UART by AT command is supported.
In sleep mode, if the flow control of the main UART is not enabled , too much data (more than 127 bytes) cannot be sent to the module through the main UART directly . You need to exit from the sleep mode before sending too much data , otherwise , the data may be lost .
If power state specifies an unsupported mode , the function returns MOD_DRIVER_ERROR_UNSUPPORTED as status information and the previous power state of the peripheral is unchanged . Multiple calls with the same state generate no error .

MOD_SignalEvent

•	void 	MOD_SignalEvent (uint32_t    event,
                              void *  arg 
                             )

Signal Modem Events .

Parameters

[in] event: Modem Events notification mask
[in] arg: Pointer to argument of signaled event

Returns

none

The function MOD_SignalEvent is a callback function registered by the function MOD_Initialize .

It is called by the Modem driver to notify the application about Modem Events occurred during operation .

Notes:

The parameter event indicates the event that occurred during driver operation .
The parameter arg provides additional information about the event .

The following events can be generated :

MOD_EVENT_CONNECT reserved .
MOD_EVENT_DISCONNECT reserved .
MOD_EVENT_ETH_RX_FRAME reserved .
MOD_EVENT_READY Occurs after RF failures and modem soft reset .

Modem Management:

The Modem Management functions are used to configure and manage the connection to an access point (AP). They are also used to configure and manage the access point (AP) itself.

Data Structure Documentation:

MOD_PDP_CONTEXT

Provides information about the network that the PDP context is connected to.

Used in:
- MOD_Activate
Data Fields:
- uint8_t id :
  - PDP connection ID
- MOD_PDPContextState_t state :
  - current PDP context state:
    - MOD_PDP_CONTEXT_ACTIVATED
    - MOD_PDP_CONTEXT_DEACTIVATED
- MOD_PDPContextType_t type :
  - The protocol types
    - MOD_PDP_CONTEXT_TYPE_IPV4
    - MOD_PDP_CONTEXT_TYPE_IPV6
    - MOD_PDP_CONTEXT_TYPE_IPV4V6
- uint8_t remote_ip4 [4]:
  - Remote IP address
- uint16_t remote_ip6 [6]:
  - Remote IP6 address

MOD_CONTEXT_CONFIG

AP context configuration. Provides information needed to configure a PDP context.

Used in:
- MOD_Activate
Data Fields:
- uint8_t contextID:
  - Integer type. The context ID.
  - Range: MOD_CONTEXT_CONFIG_IDMIN – MOD_CONTEXT_CONFIG_IDMAX
- MOD_PDPContextType_t context_type:
  - Integer type. The protocol types
    - MOD_PDP_CONTEXT_TYPE_IPV4
    - MOD_PDP_CONTEXT_TYPE_IPV6
    - MOD_PDP_CONTEXT_TYPE_IPV4V6
- uint8_t * APN:
  - access point name
- uint8_t * username:
  - String type. The username. The maximum length: 127 bytes
- uint8_t * password:
  - String type. The password. The maximum length: 127 bytes.
- MOD_PDPContextAuthentication_t authentication:
  - Integer type. The authentication methods.
    - MOD_PDP_CONTEXT_AUTHENTICATION_CHAP
    - MOD_PDP_CONTEXT_AUTHENTICATION_PAP
    - MOD_PDP_CONTEXT_AUTHENTICATION_NONE

Function Documentation:

MOD_Activate

•	int32_t	MOD_Activate	(	MOD_TCPIP_CONTEXT *    context,
						MOD_PDP_CONTEXT   *    PDP)

Activate interface (PDP Context).

Parameters

[in] context:
- AP context configuration. Provides information needed to configure a PDP context.
- The value of MOD_ACTIVATE_DEFAULT, can used to activate default PDP context (specified by MOD_CONTEXT_CONFIG_DEFAULT macro).
[out] PDP:
- Provides information about the network that the PDP context is connected to.

Returns

status information
- Socket identification number (>=0)
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: parameter error

The function MOD_Activate activates a PDP context based on the context configuration parameter with type of MOD_TCPIP_CONTEXT.

Note for the EG915 modem:

When VoLTE is disabled or not supported, the range of <contextID> is 1–7.
when VoLTE is enabled, the range of <contextID> is 1–5, and the module supports a maximum of 5 PDP contexts activated.
The actual number of activated PDP contexts depends on the (U)SIM card.

Example :

extern MOD_DRIVER MOD_DRIVER0;
  void activate_modem (void) {
  MOD_DRIVER *modem = &MOD_DRIVER0;
  // Initialize and Power-on Module
  modem->Initialize (NULL);
  modem->PowerControl (MOD_POWER_FULL);
  socket = modem->Activate(MOD_ACTIVATE_DEFAULT, &pdp);
  printf("Context ID= %d", pdp.id);
  printf("Context IP4= %d, %d, %d, %d", 	pdp.remote_ip4[0], 
                                        		pdp.remote_ip4[1], 
                                        		pdp.remote_ip4[2], 
                                        		pdp.remote_ip4[3]);
}

MOD_Deactivate

•	int32_t MOD_Deactivate (int32_t socket)

Deactivate interface (PDP Context).

Parameters

[in] int32_t socket: PDP socket ID.

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error (invalid interface)

The function MOD_Deactivate deactivates a specific context and closes all TCP/IP connections set up in this context Depending on the network.

The argument socket specifies a PDP socket identification number returned from a previous call to MOD_Activate.

MOD_Context

•	int32_t MOD_Context (MOD_CONTEXT_CONFIG * context)

Get/Set PDP context status/configuration.

Parameters

[in/out] MOD_CONTEXT_CONFIG * context.

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error (invalid interface)

Note:

The contextID field in the context structured parameter is required in both getter/setter modes, but if the contextID has a NULL value, then the default value (MOD_CONTEXT_CONFIG_DEFAULT) is selected.
The argument context(in MOD_Context as a getter function) can be used to retrieve the current configurations of the specified PDP context (with the contextID field) of the Modem module.
The argument context in the MOD_Context as a setter function can be used to specify the PDP context settings.

HTTP Interface:

The HTTP Interface exposes a set of API endpoints that accept parameters & payloads and return the results. This document describes the API actions that can be used by HTTP requests, detailing their URLs, inputs and outputs.

Typedef Documentation:

HTTP_ResponseCallback_t

Pointer to HTTP_ResponseCallback function.
Provides the typedef for the callback function HTTP_ResponseCallback.

HTTP_RequestCallback_t

Pointer to HTTP_RequestCallback function.
Provides the typedef for the callback function HTTP_RequestCallback.

Data Structure Documentation:

MOD_HTTP_t

HTTP connection configuration profile.

Used in:

MOD_HTTP

Data Fields:

unsigned method: HTTP request method
- MOD_HTTP_POST
- MOD_HTTP_GET
uint8_t* url: The URL of an HTTP request.
uint32_t url_length: length of the URL
- optional : on an ASCII-based URL, the url_length parameter can be NULL.
uint8_t* data: Pointer to HTTP content buffer.
- optional: The HTTP content can be omitted with a NULL value.
- optional: if needed to send fragmented data. (Refer to the data_callback)
uint32_t data_length: Length of the request content.
- required if needed to send fragmented data.
- optional:
  - data length in an ASCII-based data type can have a NULL value.
  - the data_length can be omitted with a NULL value.
uint8_t* response: HTTP response buffer.
- optional: The HTTP response can be omitted with a NULL value.
uint32_t response_length: maximum length of the response content.
- required in a non-null response buffer.
- on the server response without content-length, response_length used as the reference.
HTTP_RequestCallback_t data_callback:
- HTTP request callback that used to send fragmented HTTP content.
- optional: The data_callback can be omitted when the data buffer exists.
- If taken, data_length indicates the total amount of data needed to send.
HTTP_ResponseCallback_t response_callback:
- HTTP response callback that is used to retrieve fragmented HTTP content.
- optional: response_callback can be removed when the total response size is less than the buffer size.
- If taken
  - The response_length indicates the maximum chunk size of the response data.
  - The response buffer size must be greater than 2 x response_length. (dual buffer data management)
MOD_Header_t * header: HTTP header configuration structure.
- simple field formatter that allows to format pair name/value fields as a header
unsigned response_header: Disable or enable to output HTTP(S) response header
- MOD_HTTP_ENABLE
- MOD_HTTP_NORESP
uint32_t timeout: The maximum time for inputting HTTP(S) POST body or HTTP(S) POST request information.
- optional: With the value NULL, the default modem timeout will be selected.
uint32_t resptime: It is used to configure the timeout for the HTTP(S) response (Range: 1–65535 for EG915)
- optional: With the value NULL, the default modem timeout will be selected.

MOD_Header_t

HTTP request header type.

Used in:

MOD_HTTP

Data Fields:

HTTP_HeaderField* fields: header fields.
uint32_t nfield: number of header fields
char* buffer: header formatter with minimum size of
- sizeof(fields)+sizeof(HTTP URL)+60

HTTP_HeaderField

HTTP header fields are a list of strings sent and received by both the client program and server on every HTTP request and response.
Note: The standard imposes no limits to the size of each header field name or value, or to the number of fields. However, most servers, clients, and proxy software impose some limits for practical and security reasons. For example, the Apache 2.3 server by default limits the size of each field to 8,190 bytes, and there can be at most 100 header fields in a single request.

Used in:

MOD_HTTP

Data Fields:

char* name: Header field name
- Header field names are case-insensitive. This is in contrast to HTTP method names (GET, POST, etc.), which are case-sensitive
char* value: Header field value

Function Documentation:

MOD_HTTP_SetOption

•	int32_t MOD_HTTP_SetOption (MOD_HTTPOption_t option, void *data)

Set HTTP options.

Parameters

[in] option: Option to set
[in] data: Pointer to data relevant to selected option

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error (invalid interface)

The function MOD_HTTP_SetOption configures the parameters for HTTP(S) server, including configuring a PDP context ID, customizing HTTP(S) request header, outputting HTTP(S) response header, and sets the value of the specified option of the HTTP interface in the modem module.

The argument option specifies the option that is to be set (see below).

The argument data points to a buffer containing the value of the option to be set and must be aligned to the data type of the corresponding option.

Option	Description	Data	Type/Length
HTTP_OPTION_CONTEXT_ID	PDP context ID (Range: 1–7 for EG915)	context ID	Unsigned
HTTP_OPTION_RESPONSEHEADER	Disable or enable to output HTTP(S) response header.	response_header	Unsigned
HTTP_OPTION_REQUESTHEADER	Disable or enable to customize HTTP(S) request header.	request_header	Unsigned
HTTP_OPTION_SSLCTXID	SSL context ID used for HTTP(S). (Range: 0–5 for EG915)	sslctxID	Unsigned
HTTP_OPTION_CONTENTTYPE	Data type of HTTP(S) body	content_type	Unsigned
HTTP_OPTION_RSPOUT_AUTO	Disable or enable auto output of HTTP(S) response data	auto_outrsp	Unsigned
HTTP_OPTION_CLOSED_IND	Disable or enable report indication of closed HTTP(S) session.	closedind	Unsigned
HTTP_OPTION_URL	The URL of HTTP(S)	url_value	Char *
HTTP_OPTION_HEADER	HTTP(S) request header line/header field name	header_value	Char *
HTTP_OPTION_AUTH	User name and password, the format is: "username:password"	user_pwd	Char *
HTTP_OPTION_FORM_DATA	Set the name, filename and the content-type of form-data.	form/data	Char *
HTTP_OPTION_RESET	Reset the modem module.	NULL	NULL

Table 1 HTTP option types.

For more info refer to the QHTTPCFG command from reference manual.

MOD_HTTP_GetOption

•	int32_t MOD_HTTP_GetOption(MOD_HTTPOption_t  option, char *resp, uint16_t length)

Get HTTP options and queries the parameters from HTTP(S) server, including current PDP context ID, customizing HTTP(S) request header, outputting HTTP(S) response header and querying SSL settings.

Parameters

[in] option: Option to get
[out] resp: Pointer to memory where data for selected option will be returned
[in] length: maximum length of data that can be returned (in bytes)

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error

MOD_SetURL

•	int32_t MOD_SetURL (char * url, uint32_t length, uint32_t timeout)

Set the URL of an HTTP request.

Parameters

[in] url: A Uniform Resource Locator (URL), colloquially termed a web address
[in] length: length of the URL
[in] timeout: (optional; can be NULL) The maximum time for inputting URL.

Returns

execution status
- MOD_DRIVER_OK: Operation successful
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error

Note:

URL must begin with http:// or https://, which indicates the access to an HTTP or HTTPS server.

•	int32_t MOD_HTTP (int32_t socket, MOD_HTTP_t * httpd)

HTTP client for STM32 devices that used to request data from a web server.

Parameters

[in] socket: PDP socket ID
[in/out] httpd: HTTP connection configuration structure.

Returns

status information
- HTTP status number (>=0)
- MOD_DRIVER_ERROR: Operation failed
- MOD_DRIVER_ERROR_PARAMETER: Parameter error

Notes:

this function is able to automatically calculate the length of the content / header (no need to add a Content-Length section in the header)
due to the limitations of the AT-Command protocol and for stability improvements, the length of the content must be retrieved from the server response header.
on the server response without content-length, httpd->response_length used as the reference.
URL must begin with http:// or https://, which indicates the access mode to an HTTP or HTTPS server

HTTP_ResponseCallback

•	void HTTP_ResponseCallback (  uint8_t * data, 
                              	          uint32_t counter, 
                             	          uint32_t residual, 
                              	          uint32_t size)

This callback used to retrieve fragmented HTTP content.

Parameters

[in] data: pointer to response buffer
[in] counter: loop counter (start from zero)
[in] residual: The remaining size of the received data
[in] size: size of current data in the response buffer

Note:

The last piece of data is returned with a residual size of zero.

HTTP_RequestCallback

•	uint32_t HTTP_RequestCallback ( uint8_t ** data, 
                                uint32_t counter, 
                                uint32_t residual)

This function used to send fragmented HTTP content.

Parameters

[out] data: pointer to the data buffer
[in] counter: loop counter (start from zero)
[in] residual: The remaining size of the sent data

Returns

Length of written data

Mr.Zahaki. mrzahaki@gmail .com

Name		Name	Last commit message	Last commit date
Latest commit History 10 Commits
img		img
src		src
LICENSE		LICENSE
README.md		README.md

License

MrZahaki/GSM

Folders and files

Latest commit

History

Repository files navigation

Modem Driver

Usage

Table of Contents

Common Driver Functions

Cortex-M Processor Mode

Function Call Sequence

Start Sequence

Stop Sequence

Access Struct:

Modem Control:

Typedef Documentation:

MOD_SignalEvent_t:

Function Documentation:

MOD_GetVersion

MOD_Initialize

MOD_Uninitialize

MOD_PowerControl

MOD_SignalEvent

Modem Management:

Data Structure Documentation:

MOD_PDP_CONTEXT

MOD_CONTEXT_CONFIG

Function Documentation:

MOD_Activate

MOD_Deactivate

MOD_Context

HTTP Interface:

Typedef Documentation:

HTTP_ResponseCallback_t

HTTP_RequestCallback_t

Data Structure Documentation:

MOD_HTTP_t

MOD_Header_t

HTTP_HeaderField

Function Documentation:

MOD_HTTP_SetOption

MOD_HTTP_GetOption

MOD_SetURL

HTTP_ResponseCallback

HTTP_RequestCallback

About

Topics

Resources

License

Stars

Watchers

Forks

Languages