Keil Studio Cloud
Mistake on this page?
Report an issue in GitHub or email us
Docs › APIs › Network interfaces › Wi-Fi

Wi-Fi

WiFiInterface class hierarchy

The WifiInterface provides a simple C++ API for connecting to the internet over a Wi-Fi device.

Wi-Fi class reference

WiFiInterface Class Reference
Public Types
typedef mbed::Callback< void(nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t
 Hostname translation callback (for use with gethostbyname_async()). More...
Public Member Functions
virtual nsapi_error_t set_credentials (const char *ssid, const char *pass, nsapi_security_t security=NSAPI_SECURITY_NONE)=0
 Set the Wi-Fi network credentials. More...
virtual nsapi_error_t set_channel (uint8_t channel)=0
 Set the Wi-Fi network channel. More...
virtual int8_t get_rssi ()=0
 Get the current radio signal strength for active connection. More...
virtual nsapi_error_t connect (const char *ssid, const char *pass, nsapi_security_t security=NSAPI_SECURITY_NONE, uint8_t channel=0)=0
 Attempt to connect to a Wi-Fi network. More...
virtual nsapi_error_t connect ()=0
 Attempt to connect to a Wi-Fi network. More...
virtual nsapi_error_t disconnect ()=0
 Stop the interface. More...
virtual nsapi_size_or_error_t scan (WiFiAccessPoint *res, nsapi_size_t count)=0
 Scan for available networks. More...
virtual WiFiInterface * wifiInterface ()
 Return pointer to a WiFiInterface. More...
virtual void set_default_parameters ()
 defined(DOXYGEN_ONLY) More...
virtual void set_as_default ()
 Set network interface as default one. More...
virtual const char * get_mac_address ()
 Get the local MAC address. More...
virtual nsapi_error_t get_ip_address (SocketAddress *address)
 Get the local IP address. More...
virtual nsapi_error_t get_ipv6_link_local_address (SocketAddress *address)
 Get the IPv6 link local address. More...
virtual nsapi_error_t get_netmask (SocketAddress *address)
 Get the local network mask. More...
virtual nsapi_error_t get_gateway (SocketAddress *address)
 Get the local gateway. More...
virtual char * get_interface_name (char *interface_name)
 Get the network interface name. More...
virtual nsapi_error_t set_network (const SocketAddress &ip_address, const SocketAddress &netmask, const SocketAddress &gateway)
 Configure this network interface to use a static IP address. More...
virtual nsapi_error_t set_dhcp (bool dhcp)
 Enable or disable DHCP on connecting the network. More...
virtual nsapi_error_t gethostbyname (const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)
 Translate a hostname to an IP address with specific version using network interface name. More...
virtual nsapi_value_or_error_t gethostbyname_async (const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)
 Translate a hostname to an IP address (asynchronous) using network interface name. More...
virtual nsapi_error_t gethostbyname_async_cancel (int id)
 Cancel asynchronous hostname translation. More...
virtual nsapi_error_t add_dns_server (const SocketAddress &address, const char *interface_name)
 Add a domain name server to list of servers to query. More...
virtual void attach (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
 Register callback for status reporting. More...
void add_event_listener (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
 Add event listener for interface. More...
void remove_event_listener (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
 Remove event listener from interface. More...
virtual nsapi_connection_status_t get_connection_status () const
 Get the connection status. More...
virtual nsapi_error_t set_blocking (bool blocking)
 Set asynchronous operation of connect() and disconnect() calls. More...
virtual EthInterface * ethInterface ()
 Return pointer to an EthInterface. More...
virtual MeshInterface * meshInterface ()
 Return pointer to a MeshInterface. More...
virtual CellularInterface * cellularBase ()
 Return pointer to a CellularInterface. More...
virtual EMACInterface * emacInterface ()
 Return pointer to an EMACInterface. More...
virtual CellularInterface * cellularInterface ()
 Return pointer to a CellularInterface. More...
Static Public Member Functions
static WiFiInterface * get_default_instance ()
 Get the default Wi-Fi interface. More...

Usage

To bring up the network interface of an external Wi-Fi device (for example, the ESP8266Interface):

  1. Instantiate an implementation of the WiFiInterface class.
    1. Initialize the AT command parser.
  2. Call the connect() function with an SSID and password for the Wi-Fi network.
    1. Command the Wi-Fi device to connect to network.
  3. Once connected, you can use the WiFiInterface as a target for opening network sockets.

To bring up the network interface of an Ethernet-like driver (for example, the OdinWiFiInterface):

  1. Instantiate an implementation of the WiFiInterface class.
    1. Initialize the Wi-Fi driver for the target.
    2. Initialize network stack (LWIP).
  2. Call the connect() function with an SSID and password for the Wi-Fi network.
    1. Connect the Wi-Fi driver to the Wi-Fi network.
    2. Ensure the network stack acquires the IP address and DNS server address.
  3. Once connected, you can use the WiFiInterface as a target for opening network sockets.

Troubleshooting information

Network interface connect() and set_credential() might return following errors:

Error code Possible reason
NSAPI_ERROR_UNSUPPORTED Security mode is unsupported.
NSAPI_ERROR_PARAMETER Wrong parameters supplied for the given security mode, for example, no password.
NSAPI_ERROR_NO_SSID The device did not find the given Wi-Fi network.
NSAPI_ERROR_AUTH_FAILURE Wrong password given.
NSAPI_ERROR_DEVICE_ERROR Unknown failure happened in the device. The device may not be capable of reporting more descriptive error codes.

Security

For specifying security settings, both connect() and set_credential() have optional parameter nsapi_security_t security, which defines the security mode the device uses. WifiInterface supports the following security modes:

nsapi_security_t Security mode
NSAPI_SECURITY_NONE Not secure. Require no password or encryption.
NSAPI_SECURITY_WEP WEP security. Outdated.
NSAPI_SECURITY_WPA WPA security mode. Obsolete by WPA2; do not use.
NSAPI_SECURITY_WPA2 WPA2 security. Mostly used security mode.
NSAPI_SECURITY_WPA_WPA2 Allows either WPA or WPA2 security.

Please note that settings should match the security mode from the access point. Also, not all drivers support every mode. For most compatible settings, use NSAPI_SECURITY_WPA_WPA2, and set the Wi-Fi access point to allow only WPA2 mode.

Wi-Fi example

This program scans for Wi-Fi access points in the area. There are multiple Wi-Fi components that implement the WiFiInterface class. The example below uses the ESP8266Interface and OdinWiFiInterface.

The ESP8266Interface uses AT commands over serial interface to connect to an external Wi-Fi device. The OdinWiFiInterface provides an Ethernet-like driver to the Mbed OS network stack. The network stack uses the driver to connect to Wi-Fi:

main.cppImport into Mbed IDE 
/* WiFi Example
 * Copyright (c) 2016 ARM Limited
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

#include "mbed.h"

WiFiInterface *wifi;

const char *sec2str(nsapi_security_t sec)
{
    switch (sec) {
        case NSAPI_SECURITY_NONE:
            return "None";
        case NSAPI_SECURITY_WEP:
            return "WEP";
        case NSAPI_SECURITY_WPA:
            return "WPA";
        case NSAPI_SECURITY_WPA2:
            return "WPA2";
        case NSAPI_SECURITY_WPA_WPA2:
            return "WPA/WPA2";
        case NSAPI_SECURITY_UNKNOWN:
        default:
            return "Unknown";
    }
}

int scan_demo(WiFiInterface *wifi)
{
    WiFiAccessPoint *ap;

    printf("Scan:\n");

    int count = wifi->scan(NULL,0);

    if (count <= 0) {
        printf("scan() failed with return value: %d\n", count);
        return 0;
    }

    /* Limit number of network arbitrary to 15 */
    count = count < 15 ? count : 15;

    ap = new WiFiAccessPoint[count];
    count = wifi->scan(ap, count);

    if (count <= 0) {
        printf("scan() failed with return value: %d\n", count);
        return 0;
    }

    for (int i = 0; i < count; i++) {
        printf("Network: %s secured: %s BSSID: %hhX:%hhX:%hhX:%hhx:%hhx:%hhx RSSI: %hhd Ch: %hhd\n", ap[i].get_ssid(),
               sec2str(ap[i].get_security()), ap[i].get_bssid()[0], ap[i].get_bssid()[1], ap[i].get_bssid()[2],
               ap[i].get_bssid()[3], ap[i].get_bssid()[4], ap[i].get_bssid()[5], ap[i].get_rssi(), ap[i].get_channel());
    }
    printf("%d networks available.\n", count);

    delete[] ap;
    return count;
}

int main()
{
    printf("WiFi example\n");

#ifdef MBED_MAJOR_VERSION
    printf("Mbed OS version %d.%d.%d\n\n", MBED_MAJOR_VERSION, MBED_MINOR_VERSION, MBED_PATCH_VERSION);
#endif

    wifi = WiFiInterface::get_default_instance();
    if (!wifi) {
        printf("ERROR: No WiFiInterface found.\n");
        return -1;
    }

    int count = scan_demo(wifi);
    if (count == 0) {
        printf("No WIFI APs found - can't continue further.\n");
        return -1;
    }

    printf("\nConnecting to %s...\n", MBED_CONF_APP_WIFI_SSID);
    int ret = wifi->connect(MBED_CONF_APP_WIFI_SSID, MBED_CONF_APP_WIFI_PASSWORD, NSAPI_SECURITY_WPA_WPA2);
    if (ret != 0) {
        printf("\nConnection error: %d\n", ret);
        return -1;
    }

    printf("Success\n\n");
    printf("MAC: %s\n", wifi->get_mac_address());
    printf("IP: %s\n", wifi->get_ip_address());
    printf("Netmask: %s\n", wifi->get_netmask());
    printf("Gateway: %s\n", wifi->get_gateway());
    printf("RSSI: %d\n\n", wifi->get_rssi());

    wifi->disconnect();

    printf("\nDone\n");
}

Related content

Previous Next
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.