Utility

Network Utility functions. More...

Modules

Types
Network Utility Types.
 

Functions

zos_result_t zn_network_scan (zos_scan_result_t **result_list, uint16_t channel_mask, const zos_ssid_t *ssid)
 Scan for Wi-Fi networks. More...
 
zos_result_t zn_network_scan_destroy_results (void)
 Destroy scan results list. More...
 
zos_result_t zn_network_lookup (zos_interface_t interface, const char *hostname, uint32_t *ip_address)
 Resolve hostname into corresponding IP address. More...
 
zos_result_t zn_network_lookup_with_timeout (zos_interface_t interface, const char *hostname, uint32_t *ip_address, uint32_t timeout)
 Resolve hostname into corresponding IP address with specified timeout. More...
 
zos_result_t zn_network_ping (zos_interface_t interface, const char *hostname, uint32_t *reply_time_ms)
 Ping specified host and return reply time. More...
 
zos_result_t zn_network_verify (const zos_scan_result_t *scan_result, const uint8_t *security_str, uint8_t security_str_len, uint16_t timeout_ms)
 Verify WLAN network credentials. More...
 
zos_result_t zn_network_get_mac (char *mac_str_buffer)
 Get string representation of module's MAC address. More...
 
zos_result_t zn_network_get_rssi (int32_t *rssi_ptr)
 Get the Received Signal Strength Indicator (RSSI) of the WLAN interface. More...
 
zos_result_t zn_network_softap_get_rssi (const zos_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

zos_result_t zn_network_get_mac ( char *  mac_str_buffer)

Get string representation of module's MAC address.

Note
Supplied buffer but be at least 18 characters,
Parameters
[out]mac_str_bufferBuffer to hold Wi-Fi MAC address in string format
Returns
zos_result_t result of api call
Examples:
cloud/bluemix/bluemix.c, and demo/moray3d/moray3d.c.
zos_result_t zn_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 zn_network_is_up() returns ZOS_TRUE for ZOS_WLAN ). IF the interface is not up then this returns a result of ZOS_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 ZentriOS Varaible API documentation wlan.rssi_average.

Parameters
[out]rssi_ptrPointer to hold RSSI value
Returns
zos_result_t result of api call
zos_result_t zn_network_lookup ( zos_interface_t  interface,
const char *  hostname,
uint32_t *  ip_address 
)

Resolve hostname into corresponding IP address.

See ZentriOS 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
Returns
zos_result_t result of api call
zos_result_t zn_network_lookup_with_timeout ( zos_interface_t  interface,
const char *  hostname,
uint32_t *  ip_address,
uint32_t  timeout 
)

Resolve hostname into corresponding IP address with specified timeout.

See ZentriOS Command API documentation: network_lookup.

Parameters
[in]interfaceNetwork interface to do lookup
[in]hostnameDomain name to resulve
[out]ip_addresscorresponding IP address of given hostname
[in]timeoutMaximum time in milliseconds to try to resolve domain
Returns
zos_result_t result of api call
zos_result_t zn_network_ping ( zos_interface_t  interface,
const char *  hostname,
uint32_t *  reply_time_ms 
)

Ping specified host and return reply time.

See ZentriOS Command API documentation: ping.

Parameters
[in]interfacezos_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
zos_result_t result of api call
zos_result_t zn_network_scan ( zos_scan_result_t **  result_list,
uint16_t  channel_mask,
const zos_ssid_t ssid 
)

Scan for Wi-Fi networks.

See ZentriOS Command API documentation: wlan_scan.

Note
Call zn_network_scan_destroy_results() to cleanup the scan results
Parameters
[out]result_listLinked list of zos_scan_result_t
[in]channel_maskBitmask of Wi-Fi channels to scan, leave 0 to scan channels in wlan.scan.channel_mask setting
[in]ssidzos_ssid_t specific SSID to scan, leave NULL if unused
Returns
zos_result_t result of api call
Examples:
basic/network_verify/network_verify.c, basic/scan/scan.c, and nxp/lcd_scan/main.c.
zos_result_t zn_network_scan_destroy_results ( void  )

Destroy scan results list.

Destroy scan results returned by zn_network_scan()

Returns
zos_result_t result of api call
Examples:
basic/scan/scan.c, and nxp/lcd_scan/main.c.
zos_result_t zn_network_softap_get_rssi ( const zos_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 zn_network_is_up() returns ZOS_TRUE for ZOS_SOFTAP). IF the interface is not up then this returns a result of ZOS_NOTUP and the RSSI value is -999.

Use zn_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 ZentriOS Varaible API documentation softap.rssi_average.

Parameters
[in]macMAC address of SoftAP client
[out]rssi_ptrPointer to hold RSSI value
Returns
zos_result_t result of api call
zos_result_t zn_network_verify ( const zos_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 zn_network_verify() but directly accepts the result from the zn_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 zn_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
Examples:
basic/network_verify/network_verify.c.