Skip to content
/ GSM Public

Driver API for LTE-FDD, LTE-TDD, and GPRS modules

License

Notifications You must be signed in to change notification settings

mrzahaki/GSM

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

11 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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
    }
}

Table of Contents


Common Driver Functions

The modem driver is written to be compatible with standard CMSIS drivers, so each CMSIS API driver has the following functions:

  • 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

Releases

No releases published

Sponsor this project

Packages

No packages published

Languages