arduino/esp8266
1
0
Fork 0
mirror of https://github.com/esp8266/Arduino.git synced 2025-04-25 20:02:37 +03:00
Code

Adding Notes in WiFi.begin docs (closes #4949) (#4958)

Browse Source 
* Also fixing formatting of unrelated link in station class docs.
This commit is contained in:
Joseph Spencer 2018-07-28 17:52:54 -07:00 committed by Develo
parent 799193888a
commit 2ee744ecdd
1 changed files with 21 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
doc/esp8266wifi/station-class.rst
View File

@ -62,7 +62,7 @@ By default, ESP will attempt to reconnect to Wi-Fi network whenever it is discon
begin begin
^^^^^ ^^^^^
There are several versions (called *`function overloads <https://en.wikipedia.org/wiki/Function_overloading>`__* in C++) of ``begin`` function. One was presented just above: There are several versions (called `function overloads <https://en.wikipedia.org/wiki/Function_overloading>`__ in C++) of ``begin`` function. One was presented just above:
``WiFi.begin(ssid, password)``. Overloads provide flexibility in number or type of accepted parameters. ``WiFi.begin(ssid, password)``. Overloads provide flexibility in number or type of accepted parameters.
The simplest overload of ``begin`` is as follows: The simplest overload of ``begin`` is as follows:
@ -71,7 +71,9 @@ The simplest overload of ``begin`` is as follows:
WiFi.begin() WiFi.begin()
Calling it will instruct module to switch to the station mode and connect to the last used access point basing on configuration saved in flash memory. Calling it will enable station mode and connect to the last used access point based on configuration saved in flash memory.
Notes: \* It is possible that calling ``begin`` will result in the module being in STA + softAP mode if the module was previously placed into AP mode. \* If you notice strange behavior with DNS or other network functionality, check which mode your module is in (see ``WiFi.mode()`` in the `Generic Class Documentation <generic-class.rst#mode>`__).
Below is the syntax of another overload of ``begin`` with the all possible parameters: Below is the syntax of another overload of ``begin`` with the all possible parameters:
@ -89,7 +91,7 @@ Disable `DHCP <https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol
.. code:: cpp .. code:: cpp
WiFi.config(local_ip, gateway, subnet, dns1, dns2) WiFi.config(local_ip, gateway, subnet, dns1, dns2)
Function will return ``true`` if configuration change is applied successfully. If configuration can not be applied, because e.g. module is not in station or station + soft access point mode, then ``false`` will be returned. Function will return ``true`` if configuration change is applied successfully. If configuration can not be applied, because e.g. module is not in station or station + soft access point mode, then ``false`` will be returned.
@ -160,7 +162,7 @@ Reconnect the station. This is done by disconnecting from the access point an th
.. code:: cpp .. code:: cpp
WiFi.reconnect() WiFi.reconnect()
Notes: 1. Station should be already connected to an access point. If this is not the case, then function will return ``false`` not performing any action. 2. If ``true`` is returned it means that connection sequence has been successfully started. User should still check for connection status, waiting until ``WL_CONNECTED`` is reported: Notes: 1. Station should be already connected to an access point. If this is not the case, then function will return ``false`` not performing any action. 2. If ``true`` is returned it means that connection sequence has been successfully started. User should still check for connection status, waiting until ``WL_CONNECTED`` is reported:
@ -180,7 +182,7 @@ Sets currently configured SSID and password to ``null`` values and disconnects t
.. code:: cpp .. code:: cpp
WiFi.disconnect(wifioff) WiFi.disconnect(wifioff)
The ``wifioff`` is an optional ``boolean`` parameter. If set to ``true``, then the station mode will be turned off. The ``wifioff`` is an optional ``boolean`` parameter. If set to ``true``, then the station mode will be turned off.
@ -191,7 +193,7 @@ Returns ``true`` if Station is connected to an access point or ``false`` if not.
.. code:: cpp .. code:: cpp
WiFi.isConnected() WiFi.isConnected()
setAutoConnect setAutoConnect
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
@ -200,7 +202,7 @@ Configure module to automatically connect on power on to the last used access po
.. code:: cpp .. code:: cpp
WiFi.setAutoConnect(autoConnect) WiFi.setAutoConnect(autoConnect)
The ``autoConnect`` is an optional parameter. If set to ``false`` then auto connection functionality up will be disabled. If omitted or set to ``true``, then auto connection will be enabled. The ``autoConnect`` is an optional parameter. If set to ``false`` then auto connection functionality up will be disabled. If omitted or set to ``true``, then auto connection will be enabled.
@ -222,7 +224,7 @@ Set whether module will attempt to reconnect to an access point in case it is di
.. code:: cpp .. code:: cpp
WiFi.setAutoReconnect(autoReconnect) WiFi.setAutoReconnect(autoReconnect)
If parameter ``autoReconnect`` is set to ``true``, then module will try to reestablish lost connection to the AP. If set to ``false`` then module will stay disconnected. If parameter ``autoReconnect`` is set to ``true``, then module will try to reestablish lost connection to the AP. If set to ``false`` then module will stay disconnected.
@ -235,7 +237,7 @@ Wait until module connects to the access point. This function is intended for mo
.. code:: cpp .. code:: cpp
WiFi.waitForConnectResult() WiFi.waitForConnectResult()
Function returns one of the following connection statuses: \* ``WL_CONNECTED`` after successful connection is established \* ``WL_NO_SSID_AVAIL``\ in case configured SSID cannot be reached \* ``WL_CONNECT_FAILED`` if password is incorrect \* ``WL_IDLE_STATUS`` when Wi-Fi is in process of changing between statuses \* ``WL_DISCONNECTED`` if module is not configured in station mode Function returns one of the following connection statuses: \* ``WL_CONNECTED`` after successful connection is established \* ``WL_NO_SSID_AVAIL``\ in case configured SSID cannot be reached \* ``WL_CONNECT_FAILED`` if password is incorrect \* ``WL_IDLE_STATUS`` when Wi-Fi is in process of changing between statuses \* ``WL_DISCONNECTED`` if module is not configured in station mode
@ -249,7 +251,7 @@ Get the MAC address of the ESP station's interface.
.. code:: cpp .. code:: cpp
WiFi.macAddress(mac) WiFi.macAddress(mac)
Function should be provided with ``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. Function should be provided with ``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.
@ -274,7 +276,7 @@ If you do not feel comfortable with pointers, then there is optional version of
.. code:: cpp .. code:: cpp
WiFi.macAddress() WiFi.macAddress()
*Example code:* *Example code:*
@ -292,7 +294,7 @@ Function used to obtain IP address of ESP station's interface.
.. code:: cpp .. code:: cpp
WiFi.localIP() WiFi.localIP()
The type of returned value is `IPAddress <https://github.com/esp8266/Arduino/blob/master/cores/esp8266/IPAddress.h>`__. There is a couple of methods available to display this type of data. They are presented in examples below that cover description of ``subnetMask``, ``gatewayIP`` and ``dnsIP`` that return the IPAdress as well. The type of returned value is `IPAddress <https://github.com/esp8266/Arduino/blob/master/cores/esp8266/IPAddress.h>`__. There is a couple of methods available to display this type of data. They are presented in examples below that cover description of ``subnetMask``, ``gatewayIP`` and ``dnsIP`` that return the IPAdress as well.
@ -399,7 +401,7 @@ The hostname may be changed using the following function:
.. code:: cpp .. code:: cpp
WiFi.hostname(aHostname) WiFi.hostname(aHostname)
Input parameter ``aHostname`` may be a type of ``char*``, ``const char*`` or ``String``. Maximum length of assigned hostname is 32 characters. Function returns either ``true`` or ``false`` depending on result. For instance, if the limit of 32 characters is exceeded, function will return ``false`` without assigning the new hostname. Input parameter ``aHostname`` may be a type of ``char*``, ``const char*`` or ``String``. Maximum length of assigned hostname is 32 characters. Function returns either ``true`` or ``false`` depending on result. For instance, if the limit of 32 characters is exceeded, function will return ``false`` without assigning the new hostname.
@ -427,7 +429,7 @@ Return the status of Wi-Fi connection.
WiFi.status() WiFi.status()
Function returns one of the following connection statuses: Function returns one of the following connection statuses:
- ``WL_CONNECTED`` after successful connection is established - ``WL_CONNECTED`` after successful connection is established
- ``WL_NO_SSID_AVAIL`` in case configured SSID cannot be reached - ``WL_NO_SSID_AVAIL`` in case configured SSID cannot be reached
@ -531,7 +533,7 @@ Below is similar function, but returning BSSID but as a ``String`` type.
.. code:: cpp .. code:: cpp
WiFi.BSSIDstr() WiFi.BSSIDstr()
*Example code:* *Example code:*
@ -552,7 +554,7 @@ Return the signal strength of Wi-Fi network, that is formally called `Received S
.. code:: cpp .. code:: cpp
WiFi.RSSI() WiFi.RSSI()
Signal strength value is provided in dBm. The type of returned value is ``int32_t``. Signal strength value is provided in dBm. The type of returned value is ``int32_t``.
@ -615,7 +617,7 @@ Depending on connection result function returns either ``true`` or ``false`` (``
:: ::
Wi-Fi mode set to WIFI_STA Wi-Fi mode set to WIFI_STA
Begin WPS (press WPS button on your router) ... Success Begin WPS (press WPS button on your router) ... Success
......... .........
Connected, IP address: 192.168.1.102 Connected, IP address: 192.168.1.102
@ -631,7 +633,7 @@ Start smart configuration mode by sniffing for special packets that contain SSID
.. code:: cpp .. code:: cpp
beginSmartConfig() beginSmartConfig()
Query Smart Config status, to decide when stop configuration. Function returns either ``true`` or ``false of``\ boolean\` type. Query Smart Config status, to decide when stop configuration. Function returns either ``true`` or ``false of``\ boolean\` type.
@ -643,6 +645,6 @@ Stop smart config, free the buffer taken by ``beginSmartConfig()``. Depending on
.. code:: cpp .. code:: cpp
stopSmartConfig() stopSmartConfig()
For additional details regarding Smart Config please refer to `ESP8266 API User Guide <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__. For additional details regarding Smart Config please refer to `ESP8266 API User Guide <http://bbs.espressif.com/viewtopic.php?f=51&t=1023>`__.