Network Interface#

Note

To manage the network interface lifecycle correctly, it's important to use functions like sl_net_init(), sl_net_up(), sl_net_down(), and sl_net_deinit() as intended. Improper sequencing or combining sl_net_* and sl_wifi_* API functions without following the recommended order may lead to unpredictable or undefined behavior.
Stack overflows may occur if you invoke functions or use your own variables or data structures while handling callbacks. Please configure the stack size by modifying the pre-processor macro SL_SI91X_EVENT_HANDLER_STACK_SIZE as per your application's requirements. See here for the instructions for modifying a pre-processor macro.
Event/Callback handlers must not contain function calls or code which can block or delay the execution of the event/callback handler as it will cause all the other events to queue up and delay the execution of other events since all the events are invoked and handled from a single thread.
Do not call any synchronous SDK APIs from within the Event/Callback handlers.

Functions#

sl_status_t

sl_net_init(sl_net_interface_t interface, const void *configuration, void *network_context, sl_net_event_handler_t event_handler)

Initialize the specified network interface.

sl_status_t

sl_net_deinit(sl_net_interface_t interface)

De-initializes network interfaces.

sl_status_t

sl_net_up(sl_net_interface_t interface, sl_net_profile_id_t profile_id)

Bring a network interface up.

sl_status_t

sl_net_down(sl_net_interface_t interface)

Bring a network interface down.

sl_status_t

sl_net_dns_resolve_hostname(const char *host_name, const uint32_t timeout, const sl_net_dns_resolution_ip_type_t dns_resolution_ip, sl_ip_address_t *ip_address)

Resolve the given host name to an IP address.

sl_status_t

sl_net_set_dns_server(sl_net_interface_t interface, const sl_net_dns_address_t *address)

Sets DNS server IP addresses.

Function Documentation#

sl_net_init#

sl_status_t sl_net_init (sl_net_interface_t interface, const void * configuration, void * network_context, sl_net_event_handler_t event_handler)

Initialize the specified network interface.

Parameters

Type Direction Argument Name Description

sl_net_interface_t

[in]

interface

The network interface to initialize. One of the values from sl_net_interface_t

const void *

[in]

configuration

Pointer to the configuration structure for the specified interface of type sl_wifi_device_configuration_t. If NULL, then the following configuration is used internally by SDK:


sl_net_interface_t	Default configuration
SL_NET_WIFI_CLIENT_INTERFACE	sl_wifi_default_client_configuration
SL_NET_WIFI_AP_INTERFACE	sl_wifi_default_ap_configuration

void *

[in]

network_context

Runtime context specific to network interface.

sl_net_event_handler_t

[in]

event_handler

Function pointer to the network event handler callback of sl_net_event_handler_t type

This function initializes the specified network interface with the provided configuration, network context, and event handler. It supports various network interfaces such as Wi-Fi client, Wi-Fi access point.

Once the user passes a function pointer to the event handler, the network context is passed in the callback, and various events can be received through this callback.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.

Note

For Wi-Fi events, sl_net uses the wifi callback framework. Register the corresponding Wi-Fi event handlers using sl_wifi_set_callback API.
The network_context parameter is used only when the module is acting as a station in external stack mode (lwIP). In this case, network_context should refer to a valid sl_net_wifi_lwip_context_t variable.
In SoC mode, wireless initialization must be completed before using the NVM3 APIs in the common flash, as flash write and erase operations require communication between the NWP & M4.
It is recommended not to access the interfaces once the sl_net_deinit is performed to avoid unintented behavior. It is recommended to avoid using other sl_net_interface_t during sl_net_init.

sl_net_deinit#

sl_status_t sl_net_deinit (sl_net_interface_t interface)

De-initializes network interfaces.

Parameters

Type	Direction	Argument Name	Description
sl_net_interface_t	[in]	interface	This function de-initializes both Access Point and Station interfaces, regardless of the specified interface. The interface is identified by sl_net_interface_t.

This function de-initializes any network interfaces that were created, and releases any resources that were allocated during initialization.

After this, the user will not receive callbacks related to events.

Pre-conditions:
- sl_net_init should be called before this API.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.

Note

This function should not be called after an M4 OTA firmware upgrade, as it only resets the TA while the M4 application continues to run, which could cause unexpected issues. Instead, use sl_si91x_soc_nvic_reset() to perform a complete reset of both the TA and M4.
It is recommended not to access the interfaces once the sl_net_deinit is performed to avoid unintended behavior.

sl_net_up#

sl_status_t sl_net_up (sl_net_interface_t interface, sl_net_profile_id_t profile_id)

Bring a network interface up.

Parameters

Type	Direction	Argument Name	Description
sl_net_interface_t	[in]	interface	Interface identified by sl_net_interface_t.
sl_net_profile_id_t	[in]	profile_id	Network profile identifier for the specific interface of type sl_net_profile_id_t

This function brings the specified network interface up, making it ready for network communication.

For SL_NET_WIFI_CLIENT_INTERFACE, the API fetches profile data from the profile ID, scans the network and connects to the network, configures the IP address, and updates the profile data.

For SL_NET_WIFI_AP_INTERFACE, the API fetches profile data from the profile ID, configures the IP address, updates the profile data, and starts the Access Point (AP).

Pre-conditions:
- sl_net_init should be called before this API.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.

Note

By default, profile and credential configurations in sl_net_defaults.h are used by SDK.
To enable support for both IPv4 and IPv6, the ip.type in the profile should be set to (SL_IPV4|SL_IPV6).
The user can define their profile and credential configurations for an interface by calling sl_net_set_profile and sl_net_set_credential APIs before calling sl_net_up API.
The user is advised to reset the NWP with sl_net_deinit() if this API fails with error SL_STATUS_TIMEOUT.

sl_net_down#

sl_status_t sl_net_down (sl_net_interface_t interface)

Bring a network interface down.

Parameters

Type	Direction	Argument Name	Description
sl_net_interface_t	[in]	interface	Interface identified by sl_net_interface_t. This parameter specifies which network interface to bring down.

This function deactivates the specified network interface, effectively disconnecting it from the WLAN network. It should be called to properly shut down the interface and release any associated resources.

Pre-conditions:
- sl_net_up should be called before this API to ensure the interface is active before attempting to bring it down.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.

sl_net_dns_resolve_hostname#

sl_status_t sl_net_dns_resolve_hostname (const char * host_name, const uint32_t timeout, const sl_net_dns_resolution_ip_type_t dns_resolution_ip, sl_ip_address_t * ip_address)

Resolve the given host name to an IP address.

Parameters

Type	Direction	Argument Name	Description
const char *	[in]	host_name	Host name that needs to be resolved.
const uint32_t	[in]	timeout	Timeout in milliseconds. If the timeout value is greater than zero, the caller will be blocked until the timeout period to get the response. If the value is zero, the response will be sent through sl_net_event_handler_t.
const sl_net_dns_resolution_ip_type_t	[in]	dns_resolution_ip	DNS resolution by IP of type sl_net_dns_resolution_ip_type_t.
sl_ip_address_t *	[out]	ip_address	IP address object to store resolved IP address of type sl_ip_address_t.

This function resolves a host name to its corresponding IP address. It requires the DNS client feature to be enabled in the TCP/IP feature bitmap before calling.

Pre-conditions:
- The sl_net_up API must be called before this API.
- If sl_net_up is not used, then sl_si91x_configure_ip_address should be called prior to this API.
- The SL_SI91X_TCP_IP_FEAT_DNS_CLIENT bit should be enabled in the TCP/IP feature bitmap.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.

sl_net_set_dns_server#

sl_status_t sl_net_set_dns_server (sl_net_interface_t interface, const sl_net_dns_address_t * address)

Sets DNS server IP addresses.

Parameters

Type	Direction	Argument Name	Description
sl_net_interface_t	[in]	interface	The network interface of type sl_net_interface_t.
const sl_net_dns_address_t *	[in]	address	The structure containing the primary and secondary server addresses of type sl_net_dns_address_t.

This function configures the DNS server IP addresses for the specified network interface.


Condition	DNS Mode
Primary DNS and Secondary DNS are both NULL	DHCP
Primary DNS and Secondary DNS are both zero IP addresses	DHCP
Primary DNS is NULL and Secondary DNS is a zero IP address	DHCP
Secondary DNS is NULL and Primary DNS is a zero IP address	DHCP
Primary DNS is a valid IP address and Secondary DNS is NULL	Static
Secondary DNS is a valid IP address and Primary DNS is NULL	Static
Both Primary DNS and Secondary DNS are valid IP addresses	Static
Primary DNS is zero IP address and Secondary DNS is a valid IP address	Static
Secondary DNS is zero IP address and Primary DNS is a valid IP address	Static

Pre-conditions:
- The SL_SI91X_TCP_IP_FEAT_DNS_CLIENT bit should be enabled in the TCP/IP feature bitmap.

Returns

sl_status_t. See Status Codes and WiSeConnect Status Codes for details.