On Chip HTTP Client on DA16XXX (rm_http_onchip_da16xxx)

Functions
fsp_err_t	RM_HTTP_DA16XXX_Open (http_onchip_da16xxx_instance_ctrl_t *p_ctrl, http_onchip_da16xxx_cfg_t const *const p_cfg)
fsp_err_t	RM_HTTP_DA16XXX_Send (http_onchip_da16xxx_instance_ctrl_t *p_ctrl, http_onchip_da16xxx_request_t *p_request, http_onchip_da16xxx_buffer_t *p_buffer)
fsp_err_t	RM_HTTP_DA16XXX_Close (http_onchip_da16xxx_instance_ctrl_t *p_ctrl)

Detailed Description

HTTP client implementation using the DA16XXX WiFi module on RA MCUs.

Overview

This Middleware module supplies an implementation for the HTTP Client on the DA16XXX module. The network stack is run on the DA16XXX and this module inherits and extends the core functionality from the DA16XXX WiFi driver. The DA16XXX HTTP module only supports FreeRTOS currently (Microsoft Azure support expected in future release).

The DA16XXX module supports the following modules:

• DA16200
• DA16600

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Features

The HTTP Onchip da16xxx Middleware driver supplies these features:

• Supports sending a request header (GET, PUT, and POST) to an HTTP server and receiving a response header
• Supports unsecure and secure connection via TLS encryption
• Supports parsing of the response header and returning to the user
• Supports other optional configurations such as Server Name Indication (SNI) and ALPNs

Configuration

Build Time Configurations for rm_http_onchip_da16xxx

The following build time configurations are defined in fsp_cfg/rm_http_onchip_da16xxx_cfg.h:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Interrupt Configuration

Refer to UART (r_sci_uart). R_SCI_UART_Open() is called by WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

Clock Configuration

Refer to UART (r_sci_uart).

Pin Configuration

Refer to UART (r_sci_uart). R_SCI_UART_Open() is called by WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx)

Usage Notes

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

• When the user intends to use secure TLS in their application, they need to provide certificates (root certificate authority, client certificate, and private key) in a header file
• The user must provide certificate macro names in the FSP Configurator properties, as well as the name of the header file (to link the module, certificates, and header together)
• If the user provides these credentials in the Configurator, they must create a new header file in their /src/ folder with the same name as they provided in the Configurator properties. When the code is generated, a build error will occur if the header file is not created

Limitations

Refer to WiFi Onchip DA16XXX Framework Driver (rm_wifi_da16xxx).

• This module is not a standalone module - ensure that the WiFi module APIs are invoked first to configure the DA16XXX module and connect to an Access Point before using the HTTP module
• Ensure that DA16XXX SDK version v3.2.6 or later is being used, where the default buffer size for incoming TLS is 6KB and outgoing TLS is 4KB. Using earlier versions may result in failure to connect to an HTTP server with TLS (unless buffer size settings are altered manually)

Examples

Basic Example

This is a basic example of minimal use of HTTP Middleware in an application.

void http_onchip_basic_example (void)
{
    WIFIReturnCode_t wifi_err;
    fsp_err_t        http_err;

    /* Setup Access Point connection parameters */
    WIFINetworkParams_t net_params =
    {
        .ucChannel                  = 0,
        .xPassword.xWPA.cPassphrase = WIFI_PWD,
        .ucSSID                     = WIFI_SSID,
        .xPassword.xWPA.ucLength = sizeof(WIFI_PWD),
        .ucSSIDLength            = sizeof(WIFI_SSID),
        .xSecurity               = eWiFiSecurityWPA2,
    };

    /* Open connection to the Wifi Module */
    wifi_err = WIFI_On();
    assert(eWiFiSuccess == wifi_err);

    /* Connect to the Access Point */
    wifi_err = WIFI_ConnectAP(&net_params);
    assert(eWiFiSuccess == wifi_err);

    /* Initialize the HTTP Client connection */
    http_err = RM_HTTP_DA16XXX_Open(&g_rm_http_onchip_da16xxx_instance, &g_http_onchip_da16xxx_cfg);
    assert(FSP_SUCCESS == http_err);

    /* Initialize the HTTP Client connection */
    http_err = RM_HTTP_DA16XXX_Send(&g_rm_http_onchip_da16xxx_instance, &test_req, &user_buf);
    assert(FSP_SUCCESS == http_err);

    /* Close the HTTP Client module */
    http_err = RM_HTTP_DA16XXX_Close(&g_rm_http_onchip_da16xxx_instance);
    assert(FSP_SUCCESS == http_err);
}

Data Structures
struct	http_onchip_da16xxx_request_t
struct	http_onchip_da16xxx_buffer_t
struct	http_onchip_da16xxx_cfg_t
struct	http_onchip_da16xxx_instance_ctrl_t

Macros
#define	HTTP_ONCHIP_DA16XXX_MAX_ALPN
	Maximum number of ALPNs supported by DA16XXX.
#define	HTTP_ONCHIP_DA16XXX_MAX_SNI_LEN
	Maximum length of SNI supported by DA16XXX.
#define	HTTP_ONCHIP_DA16XXX_MAX_GET_LEN
	Maximum length of HTTP GET request.

Enumerations
enum	http_onchip_da16xxx_method_t
enum	http_onchip_da16xxx_tls_auth_t

---

Data Structure Documentation

http_onchip_da16xxx_request_t

struct http_onchip_da16xxx_request_t

HTTP Request Buffer

Data Fields
const char *	p_http_endpoint	Defines the URL to send HTTP requests to.
const char *	p_request_body	Pointer to optional buffer for body.
http_onchip_da16xxx_method_t	method	Request method to be used.
uint32_t	length	Length of optional body buffer.

http_onchip_da16xxx_buffer_t

struct http_onchip_da16xxx_buffer_t

HTTP User Buffers

Data Fields
char *	p_request_buffer	User HTTP request buffer.
uint32_t	req_length	Size of HTTP request buffer.
char *	p_response_buffer	User HTTP request buffer.
uint32_t	resp_length	Size of HTTP request buffer.

http_onchip_da16xxx_cfg_t

struct http_onchip_da16xxx_cfg_t

HTTP Configuration

Data Fields
at_transport_da16xxx_instance_t const *	p_transport_instance
const char *	p_alpns[HTTP_ONCHIP_DA16XXX_MAX_ALPN]	Buffer for storing ALPN names.
uint8_t	alpn_count	ALPN Protocols count. Max value is 3.
const char *	p_sni_name	Pointer to Server Name Indication.
http_onchip_da16xxx_tls_auth_t	tls_level	Set TLS Authentication Level (0, 1, or 2)
const char *	p_root_ca	String representing a trusted server root certificate.
uint32_t	root_ca_size	Size associated with root CA Certificate.
const char *	p_client_cert	String representing a Client certificate.
uint32_t	client_cert_size	Size associated with Client certificate.
const char *	p_client_private_key	String representing Client Private Key.
uint32_t	private_key_size	Size associated with Client Private Key.

http_onchip_da16xxx_instance_ctrl_t

struct http_onchip_da16xxx_instance_ctrl_t

HTTP_ONCHIP_DA16XXX private control block. DO NOT MODIFY.

Data Fields
uint32_t	open	Flag to indicate if HTTP has been opened.
http_onchip_da16xxx_cfg_t const *	p_cfg	Pointer to p_cfg for HTTP.

Enumeration Type Documentation

http_onchip_da16xxx_method_t

enum http_onchip_da16xxx_method_t

HTTP Request Method

Enumerator
HTTP_ONCHIP_DA16XXX_GET	Value converted to "get" string.
HTTP_ONCHIP_DA16XXX_POST	Value converted to "post" string.
HTTP_ONCHIP_DA16XXX_PUT	Value converted to "put" string.

http_onchip_da16xxx_tls_auth_t

enum http_onchip_da16xxx_tls_auth_t

HTTP TLS Authentication Level

Enumerator
HTTP_ONCHIP_DA16XXX_TLS_VERIFY_NONE	TLS verification is not used.
HTTP_ONCHIP_DA16XXX_TLS_VERIFY_OPTIONAL	TLS verification is optional.
HTTP_ONCHIP_DA16XXX_TLS_VERIFY_REQUIRED	TLS verification is required.

Function Documentation

RM_HTTP_DA16XXX_Open()

fsp_err_t RM_HTTP_DA16XXX_Open	(	http_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		http_onchip_da16xxx_cfg_t const *const	p_cfg
	)

Initialize the DA16XXX on-chip HTTP Client service.

Parameters

[in]	p_ctrl	Pointer to HTTP Client instance control structure.
[in]	p_cfg	Pointer to HTTP Client configuration structure.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	Parameter checking was unsuccessful.
FSP_ERR_INVALID_ARGUMENT	Data size is too large or NULL.
FSP_ERR_ALREADY_OPEN	The instance has already been opened.

RM_HTTP_DA16XXX_Send()

fsp_err_t RM_HTTP_DA16XXX_Send	(	http_onchip_da16xxx_instance_ctrl_t *	p_ctrl,
		http_onchip_da16xxx_request_t *	p_request,
		http_onchip_da16xxx_buffer_t *	p_buffer
	)

Send the HTTP request with the configured buffers.

Parameters

[in]	p_ctrl	Pointer to HTTP Client instance control structure.
[in]	p_request	Pointer to HTTP request control structure.
[in]	p_buffer	Pointer to HTTP user buffer struct for request and response.

Return values

FSP_SUCCESS	Function completed successfully.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_ASSERTION	Parameter checking was unsuccessful.
FSP_ERR_NOT_OPEN	The instance has not been opened.
FSP_ERR_INVALID_ARGUMENT	Data size is too large.
FSP_ERR_INVALID_DATA	Data was not received correctly.

RM_HTTP_DA16XXX_Close()

fsp_err_t RM_HTTP_DA16XXX_Close

(

http_onchip_da16xxx_instance_ctrl_t *

p_ctrl

)

Close the DA16XXX HTTP Client service.

Parameters

[in]

p_ctrl

Pointer to HTTP Client instance control structure.

Return values

FSP_ERR_NOT_OPEN	The instance has not been opened.
FSP_SUCCESS	Function completed successfully.
FSP_ERR_ASSERTION	Parameter checking was unsuccessful.