WiFi Onchip Silex Driver using r_sci_uart (rm_wifi_onchip_silex)

Functions
fsp_err_t	RM_WIFI_ONCHIP_SILEX_EpochTimeGet (time_t *p_utc_time)
fsp_err_t	RM_WIFI_ONCHIP_SILEX_LocalTimeGet (uint8_t *p_local_time, uint32_t size_string)
fsp_err_t	RM_WIFI_ONCHIP_SILEX_SntpEnableSet (wifi_onchip_silex_sntp_enable_t enable)
fsp_err_t	RM_WIFI_ONCHIP_SILEX_SntpServerIpAddressSet (uint8_t *p_ip_address)
fsp_err_t	RM_WIFI_ONCHIP_SILEX_SntpTimeZoneSet (int32_t hours, uint32_t minutes, wifi_onchip_silex_sntp_daylight_savings_enable_t daylightSavingsEnable)

Detailed Description

Wifi and Socket implementation using the Silex SX-ULPGN WiFi module on RA MCUs.

Overview

This Middleware module supplies an implementation for the FreeRTOS WiFi interface and AzureRTOS NetxDuo WiFi interface using the Silex SX-ULPGN module.

You can find specifics about the WiFi and Secure Socket interface APIs supported by this module at these web sites: Wifi API.

The SX-ULPGN is a low-power, compact IEEE 802.11b/g/n 2.4GHz 1x1 Wireless LAN module equipped with the Qualcomm® QCA4010 Wireless SOC. The module comes readily equipped with radio certification for Japan, North America and Europe. More information about this module can be found at the Silex Web Site

Features

The WiFi Onchip Silex Middleware driver supplies these features:

• Supports connect/disconnect to a b/g/n (2.4GHz) WiFi Access Point using Open, WPA, and WPA2 security. Encryption types can be either TKIP, or CCMP(AES).
• Supports retrieval of the module device MAC address.
• Once connected you can acquire the assigned module device IP.
• Supports a WiFi network scan capability to get a list of local Access Points.
• Supports a Ping function to test network connectivity.
• Supports a DNS Query call to retrieve the IPv4 address of a supplied URL.
• Supports both TCP and UDP client sockets.
• Drive supports 1 or 2 UARTs for interfacing with the SX-ULPGN module. The second UART is considered optional.

Configuration

Build Time Configurations for rm_wifi_onchip_silex

The following build time configurations are defined in fsp_cfg/rm_wifi_onchip_silex_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.
Number of supported socket instances	Refer to the RA Configuration tool for available options.	1	Enable number of socket instances
Size of RX buffer for socket	Manual Entry	4096
Size of TX buffer for CMD Port	Manual Entry	1500
Size of RX buffer for CMD Port	Manual Entry	3000
Semaphore maximum timeout	Manual Entry	10000
Number of retries for AT commands	Manual Entry	10
Module Reset Port	Refer to the RA Configuration tool for available options.	06	Specify the module reset pin port for the MCU.
Module Reset Pin	Refer to the RA Configuration tool for available options.	03	Specify the module reset pin for the MCU.
Enable SNTP Client	Enabled Disabled	Disabled	Should the SNTP client of the module be enabled

Configurations for Networking > WiFi Onchip Silex Driver using r_sci_uart (rm_wifi_onchip_silex)

Configuration	Options	Default	Description
SNTP server IPv4 address	Must be a valid IPv4 address	0.0.0.0
SNTP Timezone Offset from UTC Hours	Must be between 12 and -12 hours	0	Value in hours from 12 to -12
SNTP Timezone Offset from UTC Minutes	Must be between 0 and 59 minutes	0	Value in minutes from 0 to 59
Use Daylight Savings Time	Enabled Disabled	Disabled	Specify if daytime savings should be used for local time calulation

Note: It is suggested that when using the Silex Module that DTC and FIFO are enabled in the UART configuration to facilitate a more reliable data transfer between module and MCU.

Note: If you wish to use flow control then you must enable flow control in the RA Configuration editor. This can be found in the UART setting. It is advantageous to use flow control all the time since it allows the hardware to gate the flow of data across the serial bus. Without hardware flow control for faster data rate you will most likely see an overflow condition between MCU and the module device.

Note: Higher baud rates are supported in the RA Configuration editor and should be changed in the first UART configuration. There is no need to change the second UART baud rate since it is only used as an AT command channel.

Note: It is a good idea to also enable the FIFO in the UART configuration settings if you plan to use higher baud rates.

Interrupt Configuration

Refer to UART (r_sci_uart). R_SCI_UART_Open() is called by WiFi Onchip Silex Driver using r_sci_uart (rm_wifi_onchip_silex).

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 Silex Driver using r_sci_uart (rm_wifi_onchip_silex)

Usage Notes

Limitations

• WiFi AP connections do not currently support WEP security.
• When operating with a single UART only single socket connections are possible. To support multiple sockets two UART channels must be connected to the module. When using the Renesas-provided SX-ULPGN PMOD board the second UART channel is on pins 9 and 10 of the PMOD header.
• Network connection parameters SSID and Passphrase for the Access Point can not contain any commas. This is a current limitation of the Silex module firmware. The rm_wifi_onchip_silex_connect() function will return an error if a comma is detected.
• When operating with a single UART and there is an active socket connection you cannot call WIFI_Scan(), WIFI_Ping(), WIFI_GetMAC(), or WIFI_GetIPInfo(). Calling one of these function will return an error code in this situation. These commands are blocked in the one UART case during an active socket connection because they could cause data loss. To avoid this limitation please configure the hardware to use both UARTs.
• The Silex WiFi modules SNTP support requires all configuration changes to made when the WiFi is disconnected from an Access Point. This is a limitation of the Silex module firmware. If changes to the default SNTP settings are required then the application will have to close the current AP connection, make the necessary SNTP changes, and then re-establish the original connection.

Examples

Basic Example

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

void wifi_onchip_basic_example (void)
{
    WIFIReturnCode_t wifi_err;

    /* Setup Access Point connection parameters */
    WIFINetworkParams_t net_params =
    {
        .ucChannel                  = 0,
        .xPassword.xWPA.cPassphrase = "password",
        .ucSSID                     = "access_point_ssid",
        .xPassword.xWPA.ucLength = 8,
        .ucSSIDLength            = 17,
        .xSecurity               = eWiFiSecurityWPA2,
    };

    memset(scan_data, 0, sizeof(WIFIScanResult_t) * MAX_WIFI_SCAN_RESULTS);
    memset(g_socket_recv_buffer, 0, sizeof(uint8_t) * SX_WIFI_SOCKET_RX_BUFFER_SIZE);

    /* 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);

    /* Get address assigned by AP */
    WIFIIPConfiguration_t ipInfo;
    wifi_err = WIFI_GetIPInfo(&ipInfo);
    assert(eWiFiSuccess == wifi_err);

    /* Ping an address accessible on the network */
    uint8_t        ip_address[4] = {216, 58, 194, 174}; // NOLINT
    const uint16_t ping_count    = 3;
    const uint32_t intervalMS    = 100;
    wifi_err = WIFI_Ping(&ip_address[0], ping_count, intervalMS);
    assert(eWiFiSuccess == wifi_err);

    /* Scan the local Wifi network for other APs */
    wifi_err = WIFI_Scan(&scan_data[0], MAX_WIFI_SCAN_RESULTS);
    assert(eWiFiSuccess == wifi_err);

    /* Shutdown the WIFI */
    WIFI_Off();
}

SNTP example

An example of using Simple Network Time Protocol (SNTP) on WiFi in an application.

#define RM_WIFI_ONCHIP_SILEX_TEMP_BUFFER_SIZE    (64)

/*
 * Example of the use of SNTP with Wifi. Example gets the epoch time and local
 * system time strings. It is also demonstrated how the user will need to disconnect
 * from the access point to make changes to the SNTP configuration during runtime.
 *
 * Function assumes that the SNTP has been enabled and configured with proper
 * SNTP server address. For brevity error checking has not been implemented.
 *
 */
void wifi_onchip_sntp_example (void)
{
    /* Setup Access Point connection parameters */
    WIFINetworkParams_t net_params =
    {
        .ucSSID                     = "access_point_ssid",
        .ucSSIDLength               = 17,
        .xPassword.xWPA.cPassphrase = "password",
        .xPassword.xWPA.ucLength    = 8,
        .ucChannel                  = 0,
        .xSecurity                  = eWiFiSecurityWPA2
    };

    uint8_t local_time[RM_WIFI_ONCHIP_SILEX_TEMP_BUFFER_SIZE];
    time_t  current_sys_time = 0;

    // SNTP IP address
    uint8_t ip_address_sntp_server_valid[4] = {216, 239, 35, 0}; // NOLINT : Static IP address

    memset(local_time, 0, sizeof(local_time));

    /* Open connection to the Wifi Module */
    WIFI_On();

    /* Connect to the Access Point */
    WIFI_ConnectAP(&net_params);

    /* Get the Epoch time in seconds since Jan 1, 1970 UTC */
    RM_WIFI_ONCHIP_SILEX_EpochTimeGet(&current_sys_time);

    /* Get the local time string */
    RM_WIFI_ONCHIP_SILEX_LocalTimeGet((uint8_t *) local_time, sizeof(local_time));

    /* Disconnect from the access point to make changes to the SNTP configuration */
    WIFI_Disconnect();

    /* Change the IP address of the server */
    RM_WIFI_ONCHIP_SILEX_SntpServerIpAddressSet((uint8_t *) ip_address_sntp_server_valid);

    /* Change the timezone to PST with daylight saving enabled */
    RM_WIFI_ONCHIP_SILEX_SntpTimeZoneSet(-7, 0, WIFI_ONCHIP_SILEX_SNTP_DAYLIGHT_SAVINGS_ENABLE);

    /* Connect back to the access point */
    WIFI_ConnectAP(&net_params);

    /* Get the Epoch time in seconds since Jan 1, 1970 UTC */
    RM_WIFI_ONCHIP_SILEX_EpochTimeGet(&current_sys_time);

    /* Get the local time string in format [DayOfWeek Month DayOfMonth Year Hour:Minute:Second] */
    RM_WIFI_ONCHIP_SILEX_LocalTimeGet((uint8_t *) local_time, sizeof(local_time));

    /* Disconnect from the Access Point and shutdown the WIFI module*/
    WIFI_Disconnect();
    WIFI_Off();
}

Data Structures
struct	wifi_onchip_silex_cfg_t
struct	ulpgn_socket_t
struct	wifi_onchip_silex_instance_ctrl_t

Enumerations
enum	sx_ulpgn_socket_status_t
enum	sx_ulpgn_socket_rw
enum	wifi_onchip_silex_sntp_enable_t
enum	wifi_onchip_silex_sntp_daylight_savings_enable_t

---

Data Structure Documentation

wifi_onchip_silex_cfg_t

struct wifi_onchip_silex_cfg_t

User configuration structure, used in open function

Data Fields
const uint32_t	num_uarts	Number of UART interfaces to use.
const uint32_t	num_sockets	Number of sockets to initialize.
const bsp_io_port_pin_t	reset_pin	Reset pin used for module.
const uart_instance_t *	uart_instances[WIFI_ONCHIP_SILEX_CFG_MAX_NUMBER_UART_PORTS]	SCI UART instances.
const wifi_onchip_silex_sntp_enable_t	sntp_enabled	Enable/Disable the SNTP Client.
const uint8_t *	sntp_server_ip	The SNTP server IP address string.
const int32_t	sntp_timezone_offset_from_utc_hours	Timezone offset from UTC in (+/-) hours.
const uint32_t	sntp_timezone_offset_from_utc_minutes	Timezone offset from UTC in minutes.
const wifi_onchip_silex_sntp_daylight_savings_enable_t	sntp_timezone_use_daylight_savings	Enable/Disable use of daylight saving time.
void const *	p_context	User defined context passed into callback function.
void const *	p_extend	Pointer to extended configuration by instance of interface.

ulpgn_socket_t

struct ulpgn_socket_t

Silex ULPGN Wifi internal socket instance structure

Data Fields
StreamBufferHandle_t	socket_byteq_hdl	Socket stream buffer handle.
StaticStreamBuffer_t	socket_byteq_struct	Structure to hold stream buffer info.
uint8_t	socket_recv_buff[WIFI_ONCHIP_SILEX_CFG_MAX_SOCKET_RX_SIZE]	Socket receive buffer used by byte queue.
uint32_t	socket_status	Current socket status.
uint32_t	socket_recv_error_count	Socket receive error count.
uint32_t	socket_create_flag	Flag to determine in socket has been created.
uint32_t	socket_read_write_flag	flag to determine if read and/or write channels are active.

wifi_onchip_silex_instance_ctrl_t

struct wifi_onchip_silex_instance_ctrl_t

WIFI_ONCHIP_SILEX private control block. DO NOT MODIFY.

Data Fields
uint32_t	open	Flag to indicate if wifi instance has been initialized.
wifi_onchip_silex_cfg_t const *	p_wifi_onchip_silex_cfg	Pointer to initial configurations.
bsp_io_port_pin_t	reset_pin	Wifi module reset pin.
uint32_t	num_uarts	number of UARTS currently used for communication with module
uint32_t	tx_data_size	Size of the data to send.
uint32_t	num_creatable_sockets	Number of simultaneous sockets supported.
uint32_t	curr_cmd_port	Current UART instance index for AT commands.
uint32_t	curr_data_port	Current UART instance index for data.
uint8_t	cmd_rx_queue_buf[WIFI_ONCHIP_SILEX_CFG_CMD_RX_BUF_SIZE]	Command port receive buffer used by byte queue // FreeRTOS.
StreamBufferHandle_t	socket_byteq_hdl	Socket stream buffer handle.
StaticStreamBuffer_t	socket_byteq_struct	Structure to hold stream buffer info.
volatile uint32_t	curr_socket_index	Currently active socket instance.
uint8_t	cmd_tx_buff[WIFI_ONCHIP_SILEX_CFG_CMD_TX_BUF_SIZE]	Command send buffer.
uint8_t	cmd_rx_buff[WIFI_ONCHIP_SILEX_CFG_CMD_RX_BUF_SIZE]	Command receive buffer.
uint32_t	at_cmd_mode	Current command mode.
uint8_t	curr_ipaddr[4]	Current IP address of module.
uint8_t	curr_subnetmask[4]	Current Subnet Mask of module.
uint8_t	curr_gateway[4]	Current GAteway of module.
SemaphoreHandle_t	tx_sem	Transmit binary semaphore handle.
SemaphoreHandle_t	rx_sem	Receive binary semaphore handle.
uint8_t	last_data[WIFI_ONCHIP_SILEX_RETURN_TEXT_LENGTH]	Tailing buffer used for command parser.
uart_instance_t *	uart_instance_objects[WIFI_ONCHIP_SILEX_CFG_MAX_NUMBER_UART_PORTS]	UART instance objects.
SemaphoreHandle_t	uart_tei_sem[WIFI_ONCHIP_SILEX_CFG_MAX_NUMBER_UART_PORTS]	UART transmission end binary semaphore.
ulpgn_socket_t	sockets[WIFI_ONCHIP_SILEX_CFG_NUM_CREATEABLE_SOCKETS]	Internal socket instances.

Enumeration Type Documentation

sx_ulpgn_socket_status_t

enum sx_ulpgn_socket_status_t

Silex ULPGN Wifi socket status types

sx_ulpgn_socket_rw

enum sx_ulpgn_socket_rw

Silex socket shutdown channels

wifi_onchip_silex_sntp_enable_t

enum wifi_onchip_silex_sntp_enable_t

Silex WiFi module enable/disable for SNTP

wifi_onchip_silex_sntp_daylight_savings_enable_t

enum wifi_onchip_silex_sntp_daylight_savings_enable_t

Silex WiFi module enable/disable for SNTP

Function Documentation

RM_WIFI_ONCHIP_SILEX_EpochTimeGet()

fsp_err_t RM_WIFI_ONCHIP_SILEX_EpochTimeGet

(

time_t *

p_utc_time

)

This will retrieve time info from an NTP server at the address entered via an during configuration. If the server isn’t set or the client isn’t enabled, then it will return an error. The date/time is retrieved as the number of seconds since 00:00:00 UTC January 1, 1970

Parameters

[out]

p_utc_time

Returns the epoch time in seconds.

Return values

FSP_SUCCESS	Successfully retrieved the system time from module.
FSP_ERR_ASSERTION	The parameter utc_time or p_instance_ctrl is NULL.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_NOT_OPEN	Module is not open.

Get the current system time as the number of seconds since epoch 1970-01-01 00:00:00 UTC

RM_WIFI_ONCHIP_SILEX_LocalTimeGet()

fsp_err_t RM_WIFI_ONCHIP_SILEX_LocalTimeGet	(	uint8_t *	p_local_time,
		uint32_t	size_string
	)

Get the current local time based on current timezone in a string . Exp: Wed Oct 15 1975 07:06:00

Parameters

[out]	p_local_time	Returns local time in string format.
[in]	size_string	Size of p_local_time string buffer.The size of this string needs to be at least 25 bytes

Return values

FSP_SUCCESS	Successfully returned the local time string.
FSP_ERR_ASSERTION	The parameter local_time or p_instance_ctrl is NULL.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_SIZE	String size value passed in exceeds maximum.

Get the current local time based on current timezone in a string format

RM_WIFI_ONCHIP_SILEX_SntpEnableSet()

fsp_err_t RM_WIFI_ONCHIP_SILEX_SntpEnableSet

(

wifi_onchip_silex_sntp_enable_t

enable

)

Set the SNTP Client to Enable or Disable

Parameters

[in]

enable

Can be set to enable/disable for SNTP support.

Return values

FSP_SUCCESS	Successfully set the value.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_NOT_OPEN	Module is not open.

Enable or Disable the SNTP Client Service

RM_WIFI_ONCHIP_SILEX_SntpServerIpAddressSet()

fsp_err_t RM_WIFI_ONCHIP_SILEX_SntpServerIpAddressSet

(

uint8_t *

p_ip_address

)

Set the SNTP Client Server IP Address

Parameters

[in]

p_ip_address

Pointer to IP address of SNTP server in byte array format.

Return values

FSP_SUCCESS	Successfully set the value.
FSP_ERR_ASSERTION	The parameter p_ip_address or p_instance_ctrl is NULL.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_NOT_OPEN	Module is not open.

Update the SNTP Server IP Address

RM_WIFI_ONCHIP_SILEX_SntpTimeZoneSet()

fsp_err_t RM_WIFI_ONCHIP_SILEX_SntpTimeZoneSet	(	int32_t	hours,
		uint32_t	minutes,
		wifi_onchip_silex_sntp_daylight_savings_enable_t	daylightSavingsEnable
	)

Set the SNTP Client Timezone

Parameters

[in]	hours	Number of hours (+/-) used for timezone offset from GMT.
[in]	minutes	Number of minutes used for timezone offset from GMT.
[in]	daylightSavingsEnable	Enable/Disable daylight saving in the timezone calculation.

Return values

FSP_SUCCESS	Successfully set the value.
FSP_ERR_WIFI_FAILED	Error occurred with command to Wifi module.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_ARGUMENT	Parameter passed into function was invalid.

Update the SNTP Timezone