Utility
Network

Network Utility functions. More...

Modules

Types
Network Utility Types.

Functions

gos_result_t gos_network_scan ( gos_scan_result_t **result_list, uint16_t channel_mask, const gos_ssid_t *ssid)
Scan for Wi-Fi networks. More...
gos_result_t gos_network_scan_destroy_results (void)
Destroy scan results list. More...
gos_result_t gos_network_lookup ( gos_interface_t interface, const char *hostname, gos_ip_address_t *ip_address, uint32_t timeout_ms)
Resolve hostname into corresponding IP address. More...
gos_result_t gos_network_ping ( gos_interface_t interface, const char *hostname, uint32_t *reply_time_ms)
Ping specified host and return reply time. More...
gos_result_t gos_network_verify (const gos_scan_result_t *scan_result, const uint8_t *security_str, uint8_t security_str_len, uint16_t timeout_ms)
Verify WLAN network credentials. More...
gos_result_t gos_network_get_mac ( gos_interface_t interface, char *mac_str_buffer)
Get string representation of module's MAC address. More...
gos_result_t gos_network_get_rssi (int32_t *rssi_ptr)
Get the Received Signal Strength Indicator (RSSI) of the WLAN interface. More...
gos_result_t gos_network_softap_get_rssi (const gos_mac_t *mac, int32_t *rssi_ptr)
Get the Received Signal Strength Indicator (RSSI) of a SoftAP client. More...

Detailed Description

Network Utility functions.

Function Documentation

◆ gos_network_get_mac()

gos_result_t gos_network_get_mac ( gos_interface_t interface,
char * mac_str_buffer
)

Get string representation of module's MAC address.

Note
Supplied buffer but be at least 18 characters,
Parameters
[in] interface Network interface to get MAC address
[out] mac_str_buffer Buffer to hold Wi-Fi MAC address in string format
Returns
gos_result_t result of api call
Examples:
utility/msgpack/read_write_buffer.c , and utility/msgpack/read_write_stream.c .

◆ gos_network_get_rssi()

gos_result_t gos_network_get_rssi ( int32_t * rssi_ptr )

Get the Received Signal Strength Indicator (RSSI) of the WLAN interface.

The returns the RSSI of the WLAN interface IF the interface it currently up, (i.e. if gos_network_is_up() returns true for GOS_INTERFACE_WLAN ). IF the interface is not up then this returns a result of GOS_NOTUP and the RSSI value is -999.

If RSSI averaging is enabled then the averaged RSSI is returned. If RSSI averaging is disabled then the raw RSSI is returned.

For more info about RSSI averaging, see Gecko OS Varaible API documentation wlan.rssi_average .

Parameters
[out] rssi_ptr Pointer to hold RSSI value
Returns
gos_result_t result of api call

◆ gos_network_lookup()

gos_result_t gos_network_lookup ( gos_interface_t interface,
const char * hostname,
gos_ip_address_t * ip_address,
uint32_t timeout_ms
)

Resolve hostname into corresponding IP address.

See Gecko OS Command API documentation: network_lookup .

Note
This will try up to 10 seconds to resolve the given hostname
Parameters
[in] interface Network interface to do lookup
[in] hostname Domain name to resulve
[out] ip_address corresponding IP address of given hostname
[in] timeout_ms Maximum time in milliseconds to try to resolve domain
Returns
gos_result_t result of api call

◆ gos_network_ping()

gos_result_t gos_network_ping ( gos_interface_t interface,
const char * hostname,
uint32_t * reply_time_ms
)

Ping specified host and return reply time.

See Gecko OS Command API documentation: ping .

Parameters
[in] interface gos_interface_t network interface to issue ping
[in] hostname domain name or IP address to issue ping
[out] reply_time_ms time in milliseconds for ping reply
Returns
gos_result_t result of api call

◆ gos_network_scan()

gos_result_t gos_network_scan ( gos_scan_result_t ** result_list,
uint16_t channel_mask,
const gos_ssid_t * ssid
)

Scan for Wi-Fi networks.

See Gecko OS Command API documentation: wlan_scan .

Note
Call gos_network_scan_destroy_results() to cleanup the scan results
Parameters
[out] result_list Linked list of gos_scan_result_t
[in] channel_mask Bitmask of Wi-Fi channels to scan, leave 0 to scan channels in wlan.scan.channel_mask setting
[in] ssid gos_ssid_t specific SSID to scan, leave NULL if unused
Returns
gos_result_t result of api call
Examples:
wifi/wifi_scan/main.c .

◆ gos_network_scan_destroy_results()

gos_result_t gos_network_scan_destroy_results ( void )

Destroy scan results list.

Destroy scan results returned by gos_network_scan()

Returns
gos_result_t result of api call
Examples:
wifi/wifi_scan/main.c .

◆ gos_network_softap_get_rssi()

gos_result_t gos_network_softap_get_rssi ( const gos_mac_t * mac,
int32_t * rssi_ptr
)

Get the Received Signal Strength Indicator (RSSI) of a SoftAP client.

The returns the RSSI of a SoftAP client IF the interface it currently up and the client is associated, (i.e. if gos_network_is_up() returns true for GOS_INTERFACE_SOFTAP ). IF the interface is not up then this returns a result of GOS_NOTUP and the RSSI value is -999.

Use gos_network_softap_client_list() to get a list of associated SoftAP clients and coressponding MAC addresses. If the mac argument is NULL then the RSSI of the first client in the list is returned.

If RSSI averaging is enabled then the averaged RSSI is returned. If RSSI averaging is disabled then the raw RSSI is returned.

For more info about RSSI averaging, see Gecko OS Varaible API documentation softap.rssi_average .

Parameters
[in] mac MAC address of SoftAP client
[out] rssi_ptr Pointer to hold RSSI value
Returns
gos_result_t result of api call

◆ gos_network_verify()

gos_result_t gos_network_verify ( const gos_scan_result_t * scan_result,
const uint8_t * security_str,
uint8_t security_str_len,
uint16_t timeout_ms
)

Verify WLAN network credentials.

This has the same functionality as gos_network_verify() but directly accepts the result from the gos_network_scan() API.

The security_str/security_str_len parameters depend on the security type.

  • OPEN - leave NULL
  • WPA/WPA2 - should be the PSK (64 HEX characters) or password (8 - 32 characters)
  • WEP - should be the WEP key (10 or 26 HEX characters)
Note
Using a PSK instead of password makes the API execute ~3seconds faster.
This API should wait for no more than 1second when the SoftAP is active otherwise connected clients will disconnect thinking the SoftAP has gone down.
Parameters
scan_result Scan results from gos_network_scan()
security_str Network password, PSK, or key
security_str_len Length of security_str
timeout_ms Maximum time in milliseconds to wait for verification
Returns
The result of the verification