esp8266/doc/esp8266wifi/soft-access-point-class.rst

:orphan:

Soft Access Point Class
-----------------------

Section below is ESP8266 specific as `Arduino WiFi library <https://www.arduino.cc/en/Reference/WiFi>`__ documentation does not cover soft access point. The API description is broken down into three short chapters. They cover how to setup soft-AP, manage connection, and obtain information on soft-AP interface configuration.

Table of Contents
-----------------

-  `Set up Network <#set-up-network>`__

   -  `softAP <#softap>`__
   -  `softAPConfig <#softapconfig>`__

-  `Manage Network <#manage-network>`__

   -  `softAPdisconnect <#softapdisconnect>`__
   -  `softAPgetStationNum <#softapgetstationnum>`__

-  `Network Configuration <#network-configuration>`__

   -  `softAPIP <#softapip>`__
   -  `softAPmacAddress <#softapmacaddress>`__

Set up Network
~~~~~~~~~~~~~~

This section describes functions to set up and configure ESP8266 in the soft access point (soft-AP) mode.

softAP
^^^^^^

Set up a soft access point to establish a Wi-Fi network.

The simplest version (`an overload in C++
terms <https://en.wikipedia.org/wiki/Function_overloading>`__) of this function requires only one parameter and is used to set up an open Wi-Fi network.

.. code:: cpp

    WiFi.softAP(ssid)

To set up password protected network, or to configure additional network parameters, use the following overload:

.. code:: cpp

    WiFi.softAP(ssid, password, channel, hidden)

The first parameter of this function is required, remaining three are optional.

Meaning of all parameters is as follows: - ``ssid`` - character string containing network SSID (max. 63 characters) \* ``password`` - optional character string with a password. For WPA2-PSK network it should be at least 8 character long. If not specified, the access point will be open for anybody to connect. \* ``channel`` - optional parameter to set Wi-Fi channel, from 1 to 13. Default channel = 1. \* ``hidden`` - optional parameter, if set to ``true`` will hide SSID

Function will return ``true`` or ``false`` depending on result of setting the soft-AP.

Notes: \* The network established by softAP will have default IP address of 192.168.4.1. This address may be changed using ``softAPConfig`` (see below). \* Even though ESP8266 can operate in soft-AP + station mode, it actually has only one hardware channel. Therefore in soft-AP + station mode, the soft-AP channel will default to the number used by station. For more information how this may affect operation of stations connected to ESP8266's soft-AP, please check `this FAQ entry <http://bbs.espressif.com/viewtopic.php?f=10&t=324>`__ on Espressif forum.

softAPConfig
^^^^^^^^^^^^

Configure the soft access point's network interface.

.. code:: cpp

    softAPConfig (local_ip, gateway, subnet) 

| All parameters are the type of ``IPAddress`` and defined as follows:
  \* ``local_ip`` - IP address of the soft access point \* ``gateway`` -
  gateway IP address
| \* ``subnet`` - subnet mask

Function will return ``true`` or ``false`` depending on result of changing the configuration.

*Example code:*

.. code:: cpp

    #include <ESP8266WiFi.h>

    IPAddress local_IP(192,168,4,22);
    IPAddress gateway(192,168,4,9);
    IPAddress subnet(255,255,255,0);

    void setup()
    {
      Serial.begin(115200);
      Serial.println();

      Serial.print("Setting soft-AP configuration ... ");
      Serial.println(WiFi.softAPConfig(local_IP, gateway, subnet) ? "Ready" : "Failed!");

      Serial.print("Setting soft-AP ... ");
      Serial.println(WiFi.softAP("ESPsoftAP_01") ? "Ready" : "Failed!");

      Serial.print("Soft-AP IP address = ");
      Serial.println(WiFi.softAPIP());
    }

    void loop() {}

*Example output:*

::

    Setting soft-AP configuration ... Ready
    Setting soft-AP ... Ready
    Soft-AP IP address = 192.168.4.22

Manage Network
~~~~~~~~~~~~~~

Once soft-AP is established you may check the number of stations connected, or shut it down, using the following functions.

softAPgetStationNum
^^^^^^^^^^^^^^^^^^^

Get the count of the stations that are connected to the soft-AP interface.

.. code:: cpp

    WiFi.softAPgetStationNum() 

*Example code:*

.. code:: cpp

    Serial.printf("Stations connected to soft-AP = %d\n", WiFi.softAPgetStationNum());

*Example output:*

::

    Stations connected to soft-AP = 2

Note: the maximum number of stations that may be connected to ESP8266 soft-AP is five.

softAPdisconnect
^^^^^^^^^^^^^^^^

Disconnect stations from the network established by the soft-AP.

.. code:: cpp

    WiFi.softAPdisconnect(wifioff) 

Function will set currently configured SSID and password of the soft-AP to null values. The parameter ``wifioff`` is optional. If set to ``true`` it will switch the soft-AP mode off.

Function will return ``true`` if operation was successful or ``false`` if otherwise.

Network Configuration
~~~~~~~~~~~~~~~~~~~~~

Functions below provide IP and MAC address of ESP8266's soft-AP.

softAPIP
^^^^^^^^

Return IP address of the soft access point's network interface.

.. code:: cpp

    WiFi.softAPIP() 

Returned value is of ``IPAddress`` type.

*Example code:*

.. code:: cpp

    Serial.print("Soft-AP IP address = ");
    Serial.println(WiFi.softAPIP());

*Example output:*

::

    Soft-AP IP address = 192.168.4.1

softAPmacAddress
^^^^^^^^^^^^^^^^

Return MAC address of soft access point. This function comes in two versions, which differ in type of returned values. First returns a pointer, the second a ``String``.

Pointer to MAC
''''''''''''''

.. code:: cpp

    WiFi.softAPmacAddress(mac)

Function accepts one parameter ``mac`` that is a pointer to memory location (an ``uint8_t`` array the size of 6 elements) to save the mac address. The same pointer value is returned by the function itself.

*Example code:*

.. code:: cpp

    uint8_t macAddr[6];
    WiFi.softAPmacAddress(macAddr);
    Serial.printf("MAC address = %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);

*Example output:*

::

    MAC address = 5e:cf:7f:8b:10:13

MAC as a String
'''''''''''''''

Optionally you can use function without any parameters that returns a ``String`` type value.

.. code:: cpp

    WiFi.softAPmacAddress()

*Example code:*

.. code:: cpp

    Serial.printf("MAC address = %s\n", WiFi.softAPmacAddress().c_str());

*Example output:*

::

    MAC address = 5E:CF:7F:8B:10:13

For code samples please refer to separate section with `examples <soft-access-point-examples.rst>`__ dedicated specifically to the Soft Access Point Class.