Clase Station¶
La cantidad de características proporcionadas por ESP8266 en el modo de estación es mucho más extensa que la que se cubre en la librería original Arduino WiFi. Por lo tanto, en lugar de complementar la documentación original, hemos decidido escribir una nueva desde cero.
La descripción de la clase de estación se ha dividido en cuatro partes. Primero analiza los métodos para establecer la conexión a un punto de acceso. Segundo proporciona métodos para administrar la conexión, como p. ej. reconnect
o isConnected
. En tercer lugar, se cubren las propiedades para obtener información sobre la conexión, como la dirección MAC o IP. Finalmente, la cuarta sección proporciona métodos alternativos para conectarse, como p. ej. Configuración protegida WiFi (WPS).
Tabla de contenidos¶
Los puntos siguientes proporcionan descripciones y retazos de código sobre como usar métodos particulares.
Para obtener más muestras de código, consulte la sección separada con ejemplos <station-examples> dedicada específicamente a la Clase Station.
Comienza aquí¶
El cambio del módulo al modo estación se realiza con la función begin
. Los parámetros típicos de begin
incluyen SSID y contraseña, por lo que el módulo se puede conectar a un punto de acceso específico.
WiFi.begin(ssid, password)
Por defecto, ESP intentará volver a conectarse a la red WiFi cada vez que se desconecte. No hay necesidad de manejar esto con código separado. Una buena forma de simular la desconexión sería resetear el punto de acceso. ESP reportará la desconexión y luego tratará de reconectarse automáticamente.
begin¶
Hay varias versiones (sobrecargas) de la función begin
. Una presentada justo ahora: WiFi.begin(ssid, password)
. Sobrecargas que proveen flexibilidad en el número o tipos de parámetros aceptados.
La sobrecarga mas simple de begin
es la siguiente:
WiFi.begin()
Al llamarlo se habilitará el modo de STATION y se conectará al último punto de acceso utilizado según la configuración guardada en la memoria flash.
Notas:
- Es posible que al llamar a
begin
el módulo esté en modo STA+softAP si el módulo se colocó previamente en modo AP. - Si observa un comportamiento extraño con DNS u otra funcionalidad de red, verifique en qué modo se encuentra su módulo (consulte
WiFi.mode()
en Documentación de la clase genérica) .
A continuación se muestra la sintaxis de otra sobrecarga de begin
con todos los parámetros posibles:
WiFi.begin(ssid, password, channel, bssid, connect)
El significado de los parámetros es el siguiente:
ssid
- Una String que contiene el SSID del punto de acceso que queremos conectarnos, Puede tener hasta 32 caracteres.password
- Contraseña del punto de acceso, un String que debe tener como mínimo una longitud de 8 caracteres y menos de 64 caracteres.channel
- Canal del AP, si queremos operar en un canal específico, de lo contrario, este parámetro puede omitirse.bssid
- Dirección MAC del AP, este parámetro es también opcional.connect
- Un parámetroboolean
que si se establece afalse
, instruirá al módulo para que solo guarde los parámetros sin establecer conexión con el punto de acceso.
config¶
Desactiva el cliente DHCP y establece la configuración IP del interfaz de estación con valores definidos por el usuario. El interfaz tendrá una configuración IP estática en vez de los valores servidos por el DHCP.
WiFi.config(local_ip, gateway, subnet, dns1, dns2)
Función que devuelve true
si la configuración se aplica satisfactoriamente. Si la configuración no puede aplicarse, porque p. ej. el módulo no está en modo estación o estación + punto de acceso, entonces devolverá false
.
La siguiente configuración IP debe proveerse:
local_ip
- Introduce aquí la dirección IP que quieras asignar al interfaz estación del ESP.gateway
- Debe contener la dirección IP de la puerta de enlace (Gateway - de un router) para acceder a redes externas.subnet
- Esta es la máscara de subred que define el rango de direcciones IP de la red local.dns1
,dns2
- Parámetro opcional que define la dirección IP del servidor de dominio (DNS) que mantiene un directorio de nombres de dominio (como p.ej. www.google.es) y nos las traduce a direcciones IP.
Código de ejemplo:
#include <ESP8266WiFi.h>
const char* ssid = "********";
const char* password = "********";
IPAddress staticIP(192,168,1,22);
IPAddress gateway(192,168,1,9);
IPAddress subnet(255,255,255,0);
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Conectando a %s\n", ssid);
WiFi.begin(ssid, password);
WiFi.config(staticIP, gateway, subnet);
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Conectado, dirección IP: ");
Serial.println(WiFi.localIP());
}
void loop() {}
Ejemplo de salida:
Conectando a sensor-net
.
Conectado, dirección IP: 192.168.1.22
Tenga en cuenta que la estación con configuración de IP estática por lo general se conecta a la red más rápido. En el ejemplo anterior, tomó aproximadamente 500 ms (se muestra un punto .). Esto se debe a que la obtención de la configuración IP por parte del cliente DHCP lleva tiempo y en este caso este paso se omite. Si pasa los tres parámetros como 0.0.0.0 (local_ip, gateway y subred), volverá a habilitar DHCP. Necesita volver a conectar el dispositivo para obtener nuevas direcciones IP.
Gestión de la conexión¶
reconnect¶
Reconecta la estación. Esto se hace por desconexión del punto de acceso y entonces volviendo a conectar al mismo punto de acceso.
WiFi.reconnect()
Notes:
- La estación debe estar ya conectada a un punto de acceso. Si no es el caso, la función devolverá
false
sin realizar ninguna acción. - Si se devuelve
true
significa que la secuencia de conexión se ha iniciado con éxito. El usuario aún debe verificar el estado de la conexión, esperando hasta que se informeWL_CONNECTED
:
WiFi.reconnect();
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
disconnect¶
Establece la SSID y contraseña actualmente configurada al valor null
y desconecta la estación del punto de acceso.
WiFi.disconnect(wifioff)
El parámetro wifioff
es de tipo boolean
opcional. Si se establece a true
, el modo estación será apagado.
isConnected¶
Devuelve true
si la estación está conecta a un punto de acceso, en caso contrario devuelve false
.
WiFi.isConnected()
setAutoConnect¶
Configura el módulo para conectarse automáticamente tras encenderse al último punto de acceso utilizado.
WiFi.setAutoConnect(autoConnect)
El parámetro autoConnect
es opcional. Si se establece a false
la funcionalidad de auto conexión será desactivada. Si se omite o se establece a true
, la auto conexión se activará.
getAutoConnect¶
Es una función «compañera» a setAutoConnect()
. Si devuelve true
el módulo está configurado para conectar al último punto de acceso tras encenderse.
WiFi.getAutoConnect()
Si la funcionalidad de auto conexión está desactivada, la función devuelve false
.
setAutoReconnect¶
Establece si el módulo intentará volver a conectarse a un punto de acceso en caso de que esté desconectado.
WiFi.setAutoReconnect(autoReconnect)
Si el parámetro autoReconnect
está establecido en true
, el módulo intentará restablecer la conexión perdida al punto de acceso. Si se establece en false
, el módulo permanecerá desconectado.
Nota: ejecutar setAutoReconnect(true)
cuando el módulo ya está desconectado no lo hará volver a conectarse al punto de acceso. En cambio, debería utilizarse reconnect()
.
waitForConnectResult¶
Espera hasta que el módulo se conecte al punto de acceso. Esta función está destinada para el módulo configurado modo estación o estación + punto de acceso SoftAP.
WiFi.waitForConnectResult()
La función devuelve uno de los siguientes estados de conexión:
WL_CONNECTED
- Después de establecida una conexión exitosa.WL_NO_SSID_AVAIL
- En caso de que no se pueda alcanzar el SSID configurado.WL_CONNECT_FAILED
- Si la contraseña es incorrecta.WL_IDLE_STATUS
- Cuando WiFi está en proceso de cambio entre estados.WL_DISCONNECTED
- Si el módulo no está configurado en modo de estación.
Configuración¶
macAddress¶
Obtiene la dirección MAC de la interfaz de estación ESP.
WiFi.macAddress(mac)
Se debe proporcionar a la función la variable mac
que es un puntero a la ubicación de la memoria (una matriz uint8_t
de tamaño de 6 elementos) para guardar la dirección MAC. El mismo valor de puntero es devuelto por la función.
Código de ejemplo:
if (WiFi.status() == WL_CONNECTED)
{
uint8_t macAddr[6];
WiFi.macAddress(macAddr);
Serial.printf("Conectado, dirección MAC: %02x:%02x:%02x:%02x:%02x:%02x\n", macAddr[0], macAddr[1], macAddr[2], macAddr[3], macAddr[4], macAddr[5]);
}
Ejemplo de salida:
Conectado, dirección MAC: 5C:CF:7F:08:11:17
Si no se siente cómodo con los punteros, existe una versión opcional de esta función disponible. En lugar del puntero, devuelve un String
que contiene la misma dirección MAC.
WiFi.macAddress()
Código de ejemplo:
if (WiFi.status() == WL_CONNECTED)
{
Serial.printf("Conectado, dirección MAC: %s\n", WiFi.macAddress().c_str());
}
localIP¶
Función utilizada para obtener la dirección IP de la interfaz de estación ESP.
WiFi.localIP()
El tipo de valor devuelto es IPAddress. Hay un par de métodos disponibles para mostrar este tipo de datos. Se presentan en ejemplos a continuación que cubren la descripción de subnetMask
, gatewayIP
y dnsIP
que también devuelven valores IPAddress.
Código de ejemplo:
if (WiFi.status() == WL_CONNECTED)
{
Serial.print("Conectado, dirección IP: ");
Serial.println(WiFi.localIP());
}
Ejemplo de salida:
Conectado, dirección IP: 192.168.1.10
subnetMask¶
Obtiene la máscara de subred de la interfaz de estación.
WiFi.subnetMask()
El módulo debe estar conectado al punto de acceso para obtener la máscara de subred.
Código de ejemplo:
Serial.print("Máscara de subred: ");
Serial.println(WiFi.subnetMask());
Ejemplo de salida:
Máscara de subred: 255.255.255.0
gatewayIP¶
Obtiene la dirección IP de la puerta de acceso o gateway.
WiFi.gatewayIP()
Código de ejemplo:
Serial.printf("Getaway IP: %s\n", WiFi.gatewayIP().toString().c_str());
Ejemplo de salida:
Getaway IP: 192.168.1.9
dnsIP¶
Obtiene la dirección IP del Servidor de Nombres de Dominio (DNS).
WiFi.dnsIP(dns_no)
Con el parámetro de entrada dns_no
podemos especificar qué IP del servidor de nombres de dominio necesitamos. Este parámetro está basado en cero y los valores permitidos son ninguno, 0 o 1. Si no se proporciona ningún parámetro, se devuelve la IP del DNS n.° 1.
Código de ejemplo:
Serial.print("DNS: #1, #2 IP: ");
WiFi.dnsIP().printTo(Serial);
Serial.print(", ");
WiFi.dnsIP(1).printTo(Serial);
Serial.println();
Ejemplo de salida:
DNS: #1, #2 IP: 62.179.1.60, 62.179.1.61
hostname¶
Obtiene el nombre del servidor DHCP asignado a la estación ESP.
WiFi.hostname()
La función devuelve un valor del tipo String
. El nombre de host predeterminado está en formato ESP_24xMAC
donde 24xMAC son los últimos 24 bits de la dirección MAC del módulo.
El nombre del servidor DHCP puede cambiarse usando la siguiente función:
WiFi.hostname(aHostname)
El parámetro de entrada aHostname
puede ser del tipo char*
, const char*
o String
. La longitud máxima del nombre de host asignado es de 32 caracteres. La función devuelve true
o false
según el resultado. Por ejemplo, si se excede el límite de 32 caracteres, la función devolverá falso
sin asignar el nuevo nombre de host.
Código de ejemplo:
Serial.printf("Hostname por defecto: %s\n", WiFi.hostname().c_str());
WiFi.hostname("Station_Tester_02");
Serial.printf("Nuevo hostname: %s\n", WiFi.hostname().c_str());
Ejemplo de salida:
Hostname por defecto: ESP_081117
Nuevo hostname: Station_Tester_02
status¶
Devuelve el estado de la conexión WiFi.
WiFi.status()
La función devuelve uno de los siguientes estados de conexión:
WL_CONNECTED
- Después de que se establece una conexión exitosa.WL_NO_SSID_AVAIL
- En caso de que no se pueda alcanzar el SSID configurado.WL_CONNECT_FAILED
- Si la contraseña es incorrecta.WL_IDLE_STATUS
- Cuando WiFi está cambiando de estado.WL_DISCONNECTED
- Si el módulo no está configurado en modo de estación.
El valor devuelto es del tipo wl_status_t
definido en wl_definitions.h
Código de ejemplo:
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.printf("Estado de la conexión: %d\n", WiFi.status());
Serial.printf("Conectando a %s\n", ssid);
WiFi.begin(ssid, password);
Serial.printf("Estado de la conexión: %d\n", WiFi.status());
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.printf("\nEstado de la conexión: %d\n", WiFi.status());
Serial.print("Conectado, dirección IP: ");
Serial.println(WiFi.localIP());
}
void loop() {}
Ejemplo de salida:
Estado de la conexión: 6
Conectando a sensor-net
Estado de la conexión: 6
......
Estado de la conexión: 3
Conectado, dirección IP: 192.168.1.10
Los estatus de conexión 6 y 3 como puede verse en wl_definitions.h son:
3 - WL_CONNECTED
6 - WL_DISCONNECTED
Según este ejemplo, cuando se ejecuta el código anterior, el módulo está desconectado inicialmente de la red y devuelve el estado de conexión 6 - WL_DISCONNECTED
. También está desconectado inmediatamente después de ejecutar WiFi.begin(ssid, password)
. Luego, después de unos 3 segundos (basándose en el número de puntos que se muestran cada 500 ms), finalmente se activa el estado de conexión 3 - WL_CONNECTED
.
SSID¶
Devuelve el nombre de la red WiFi, formalmente llamada Service Set Identifier (SSID).
WiFi.SSID()
El valor devuelto es del tipo String
.
Código de ejemplo:
Serial.printf("SSID: %s\n", WiFi.SSID().c_str());
Ejemplo de salida:
SSID: sensor-net
psk¶
Devuelve la clave pre compartida actual (contraseña) asociada a la red WiFi.
WiFi.psk()
El valor devuelto es del tipo String
.
BSSID¶
Devuelve la dirección MAC del punto de acceso al que está conectado el módulo ESP. Esta dirección se denomina formalmente Basic Service Set Identifier (BSSID).
WiFi.BSSID()
La función BSSID()
devuelve un puntero a la ubicación de la memoria (una matriz uint8_t
con tamaño de 6 elementos) donde se guarda el BSSID.
A continuación se muestra una función similar, pero que devuelve BSSID como del tipo String
.
WiFi.BSSIDstr()
Código de ejemplo:
Serial.printf("BSSID: %s\n", WiFi.BSSIDstr().c_str());
Ejemplo de salida:
BSSID: 00:1A:70:DE:C1:68
RSSI¶
Devuelve la potencia de la señal WiFi, que formalmente se llama Received Signal Strength Indicator (RSSI).
WiFi.RSSI()
El valor de intensidad de la señal se proporciona en dBm (decibelios). El tipo del valor devuelto es int32_t
.
Código de ejemplo:
Serial.printf("RSSI: %d dBm\n", WiFi.RSSI());
Ejemplo de salida:
RSSI: -68 dBm
Conexiones diferentes¶
El SDK de ESP8266 proporciona métodos para conectar la estación ESP a un punto de acceso. Aparte el core ESP8266/Arduino implementa WPS y Smart Config como se describe con más detalle a continuación.
WPS¶
La siguiente función beginWPSConfig
permite conectarse a una red usando Wi-Fi Protected Setup (WPS). Actualmente solo se permite el método PBC (Push Button Configuration) (modo WPS_TYPE_PBC
) compatible (SDK 1.5.4).
WiFi.beginWPSConfig()
Dependiendo del resultado de la conexión, la función devuelve true
o false
(tipo boolean
).
Código de ejemplo:
#include <ESP8266WiFi.h>
void setup(void)
{
Serial.begin(115200);
Serial.println();
Serial.printf("Modo WiFi establecido a WIFI_STA %s\n", WiFi.mode(WIFI_STA) ? "" : "Falló!");
Serial.print("Comienzo WPS (presione el botón WPS en su router) ... ");
Serial.println(WiFi.beginWPSConfig() ? "OK" : "Falló!");
while (WiFi.status() != WL_CONNECTED)
{
delay(500);
Serial.print(".");
}
Serial.println();
Serial.print("Conectado, dirección IP: ");
Serial.println(WiFi.localIP());
}
void loop() {}
Ejemplo de salida:
Modo WiFi establecido a WIFI_STA
Comienzo WPS (presione el botón WPS en su router) ... OK
.........
Conectado, dirección IP: 192.168.1.102
Smart Config¶
La conexión Smart Config de un módulo ESP y un punto de acceso se realiza olfateando (sniffing) los paquetes especiales que contienen SSID y la contraseña del AP deseado. Para hacerlo, el dispositivo móvil o la computadora deben tener la funcionalidad de transmisión de SSID y contraseña codificados.
Las siguientes tres funciones se proporcionan para implementar Smart Config.
Inicie el modo Smart Config olfateando los paquetes especiales que contienen el SSID y la contraseña del punto de acceso deseado. Dependiendo del resultado, se devuelve true
o false
.
beginSmartConfig()
Consulta el estado de Smart Config, para decidir cuándo detener la configuración. La función devuelve true
o false
de tipo boolean
.
smartConfigDone()
Detiene Smart Config y libera el buffer tomado por beginSmartConfig()
. Dependiendo del resultado de la función, devuelve true
o `` false`` de tipo `` boolean``.
stopSmartConfig()
Para obtener más información acerca de Smart Config, consulte la guía de usuario de la API ESP8266.
Consulte la sección separada con ejemplos dedicada específicamente a la Clase Station.