Utility

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]interfaceNetwork interface to get MAC address
[out]mac_str_bufferBuffer 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_ptrPointer 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]interfaceNetwork interface to do lookup
[in]hostnameDomain name to resulve
[out]ip_addresscorresponding IP address of given hostname
[in]timeout_msMaximum 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]interfacegos_interface_t network interface to issue ping
[in]hostnamedomain name or IP address to issue ping
[out]reply_time_mstime 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_listLinked list of gos_scan_result_t
[in]channel_maskBitmask of Wi-Fi channels to scan, leave 0 to scan channels in wlan.scan.channel_mask setting
[in]ssidgos_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]macMAC address of SoftAP client
[out]rssi_ptrPointer 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_resultScan results from gos_network_scan()
security_strNetwork password, PSK, or key
security_str_lenLength of security_str
timeout_msMaximum time in milliseconds to wait for verification
Returns
The result of the verification