Home
Written by Hieromon Ikasamo, 2015, under MIT license.
ESP8266 WiFi Library for Arduino provides a function for easily WiFi communication using ESP8266 from your sketch via the serial on such as Arduino UNO, Leonardo and MEGA.
Also this library has a debug output facility can monitor the transmitted and received data.
- Conditions of ESP8266 module
- ESP8266 Class
- Functions
- Hints
This library is implemented and tested under the following version of ESP8266 firmware. If the version of ESP8266 to be used is different, download the conformed version of firmware from Espressif site, and update the firmware.
The version of ESP8266 module can be found in the AT+GMR command. An AT command would be executed with the serial terminal emulator as Tera Term immediately on your PC.
AT+GMR
AT version:0.22.0.0(Mar 20 2015 10:04:26)
SDK version:1.0.0
compile time:Mar 20 2015 11:00:32
OK
In order to update the firmware of ESP8266 requires firmware file itself and writing tool to EEPROM. There are various types of the firmware, this library is required an AT-command firmware. You will find a brief description of the firmware at Elecdragon wiki documents.
- AT firmware: esp_iot_sdk_v1.0.0_15_03_20.zip
- EEPROM flash writing tool: nodemcu-flasher
ESP8266 class instance can be referred with the WiFi variable from your sketch by including a ESP8266.h header file.
#include "ESP8266.h"
Reset ESP8266 module by either the external reset pin or RST command. Usually ESP8266 a power-on reset is enabled. This function is used to reset the ESP8266 module at any time during the execution of the sketch.
In hardware reset, this function along external signal resets the modules at any time in synchronization with the sketch run. In software reset, restart the module by AT+RST of AT command.
WiFi.reset(rst)
- rst - WIFI_RESET: One of the the following arguments:
WIFI_RESET_HARD: Resets using an external reset signal.
WIFI_RESET_SOFT: Restart the module in accordance with RST command.
- true: Successful
- false: Some error occurred
If the sketch uses the hardware reset for module resetting it wire the RST pin to Arduino. And it defines the below directive for RST signal in ESP8266.h file.
Also the circuit wiring must be shift to 3.3V level. See details for signal level shift.
// ESP8266_RST_PIN must be assigned to the Arduino pin for RST of ESP8266.
#define ESP8266_RST_PIN 2
Start ESP8266 communication. Sets baud rate for serial data transmission between Arduino and ESP8266.
WiFi.begin(baudRate)
- baudRate - long: Baud rate for communicating with ESP8266 module, uses a valid spped of 4800 to 115200. If you specify more than 19200, need to increase the serial buffer size.
- true: Successful
- false: Some error occurred
Disconnect from WiFi access point and close UART session with ESP3266 communication.
WiFi.end()
None
None
Configuration WiFi mode, IP transfer mode and multiple connection mode.
WiFi.config(mode, mux, ipMode)
- mode - WIFI_MODE: An activity to intended of the ESP8266 operation.
WIFI_MODE_STA: Station
WIFI_MODE_AP: Soft-AP
WIFI_MODE_APSTA: Station and Soft-AP - mux - WIFI_MUX: Multiple connection establishment
WIFI_MUX_SINGLE: Single connection
WIFI_MUX_MULTI: Multi connection - ipMode - WIFI_IPMODE: Transfer mode
WIFI_IPMODE_NORMAL: Normal
WIFI_IPMODE_BARE: Unvarnished transmission mode
- WIFI_ERR_OK : Successful
- WIFI_ERR_ERROR : Some error occurred
Connect to the WiFi access point.
WiFi.join(ssid, pwd)
- ssid - char*: SSID of the access point to be connected.
- pwd - char*: Pass phrase for the SSID.
- WIFI_ERR_OK : Successful
- WIFI_ERR_ERROR : Some error occurred
Disconnect from the WiFi access point.
WiFi.disconnect()
None
- WIFI_ERR_OK : Successful
- WIFI_ERR_ERROR : Some error occurred
Inquire the connection establishment status with specified the access point.
WiFi.isConnect(ssid)
- ssid - char*: SID of the WiFi Access Point
- true : Connected
- false : Not connected
Close the currently TCP/UPD active connection. Execute to either CIPCLOSE or CIPSERVER=0 of AT command, it is determined by the current connection type that is established by the setup function. When connection is the WIFI_CONN_SERVER then AT+CIPSERVER=0, or the WIFI_CONN_CLIENT then AT+CIPCLOSE.
WiFi.close()
WiFi.close(channel)
- channel - int8_t: Connection ID, If established connection is the single, this parameter will be no specified.
None
Get current WiFi connection status.
WiFi.status()
None
The following values indicating the connection state.
- WIFI_STATUS_GOTIP : IP address assigned
- WIFI_STATUS_CONN : WiFi connected
- WIFI_STATUS_DISCONN : WiFi disconnected
- WIFI_STATUS_NOTCONN : WiFi did not connected
Get IP address and reports resulted IP address string.
WiFi.ip(mode)
mode - WIFI_MODE: Which would be notified WIFI_MODE_STA or WIFI_MODE_AP.
IP address character string which is specified by the mode parameter.
Set the ESP8266 mode of making up the connection topology.
WiFi.setup(conn, protocol, mux)
- conn - WIFI_CONN: The following values indicating the connection topology.
WIFI_CONN_CLIENT: Client access
WIFI_CONN_SERVER: Server connection
WIFI_CONN_PEER: Client access by UDP connection - protocol - WIFI_PRO: Transfer protocol to be used in this connection.
WIFI_PRO_TCP: Uses TCP protocol
WIFI_PRO_UDP: Uses UDP protocol
- WIFI_ERR_OK : Successful
- WIFI_ERR_ERROR : Some error occurred
Start IP connection for server side with passive SYN. IP connection executed by AT+CIPSERVER command.
WiFi.server(port)
- port - uint16_t: Port number
- WIFI_ERR_CONNECT : A server connection has been started.
- WIFI_ERR_ERROR : Some error occurred.
Start the IP connection for client side.
WiFi.connect(address, port)
WiFi.connect(channel, address, port)
- channel - int8_t: Connection ID, specify this parameter to a multi-connection.
- address - char*: IP address of the peer
- port - uint16_t: Port number
- WIFI_ERR_CONNECT : A server connection has been started.
- WIFI_ERR_ERROR : Some error occurred.
Send data with connection ID specified or without the connection ID.
WiFi.send(data)
WiFi.send(channel, data)
- channel - int8_t: Connection ID to be used for the transmission. If the current connection has no the connection ID, this parameter is not specified.
- data - uint8_t*: The send data including the terminating null byte ('\0').
- WIFI_ERR_OK : Successful
- WIFI_ERR_TIMEOUT : Time-out occurred
- WIFI_ERR_ERROR : Some error occurred
Sending data along with making a connection establishment.
WiFi.send(channel, address, port, data)
- channel - int8_t: Connection ID to be used for the transmission.
- address - char*: IP address
- port - uint16_t: Port Number
- data - char*: The send data including the terminating null byye ('\0').
- WIFI_ERR_OK : Successful
- WIFI_ERR_TIMEOUT : Time-out occurred
- WIFI_ERR_ERROR : Some error occurred
Start listening at the specified connection, and then stores the received data to the buffer. If the connection mode is single, no specify the channel argument.
WiFi.receive(buffer, size, timeOut)
WiFi.receive(channel, buffer, size, timeOut)
- channel - int8_t: Connection ID
- buffer - uint8_t*: Buffer to store the received data that header has been excluded
'+PD:n'. - size - uint16_t: Buffer size
- timeOut - uint32_t: Time-out scale, 0 without time-out
Received data length
Starts the listening from selected connection. If the connection mode is single, No specify to the channel argument. When the reception starts it will analyze the '+IPAD' identifier from ESP8266, and returns data length necessary for receiving. Wait for the reception indefinitely when give zero to timeOut argument. If a timeout occurs return value will be zero.
WiFi.listen(channel, timeOut)
WiFi.listen(timeOut)
- channel - int8_t: Connection ID
- timeOut - uint32_t: Time-out scale, 0 without time-out.
The length of the data to be received
Usually, the listen function is used in conjunction with the read function. The WiFi reception, the sketch performs the listen function to the beginning. It will return the actual data length to be received and the sketch repeats the read function for times of the length.
int16_t c;
uint16_t len;
// Request to the server.
WiFi.send((const uint8_t *)"GET / HTTP/1.1\r\n\r\n");
// Wait for response and get data length to be received.
len = WiFi.listen(0);
// Receiving loop corresponding to the previous request.
while (len) {
if ((c = WiFi.read()) > 0) {
// Some processes are here, for the received byte.
len--;
}
}
Return a character that was received from ESP8266.
WiFi.read()
None
The character read, or -1 if none is available.
Get the number of bytes available for reading from ESP8266. This is data that's already arrived in the serial receive buffer.
WiFi.available()
None
The number of bytes available to read.
Arduino can use the SortwareSerial for communication with a ESP8266 module. Normally the sketch should use the hardware serial. Software serial are not suitable for high-speed communication. However, the sketch want to use the SoftwareSerial then must write the include directive in top section of the sketch.
#include "SoftwareSerial.h"
And ESP8266 library will use the software serial when ESP8266_USE_SOFTWARESERIAL macro is defined. This macro is defined as the below in ESP8266.h header file.
#define ESP8266_USE_SOFTWARESERIAL
Also send and receive pin should be defined by the following macro in ESP8266.h file.
#define _ESP8266_ALT_RX 8
#define _ESP8266_ALT_TX 9
But it can not be used at the same time with software serial for ESP8266 communication when using the DebugSerial.
The skecth can use the DebugSerial to monitor the data between the ESP8266 and Arduino. Define ESP8266_USE_DEBUGSERIAL macro in ESP8266.h header file to enable the DebugSerial. It must include SoftwareSerial header file when it outputs the communication data between Arduino and ESP8266 to the serial. Write #include directive as the below in top of the sketch code.
#include "SoftwareSerial.h"
Also it defines the RX pin and TX pins software serial with baud rate of debugging output rate uses in ESP8266.h file.
#define ESP8266_USE_DEBUGSERIAL
#define _ESP8266_DBG_BAUDRATE 9600 // DebugSeral default baud rate
#define _ESP8266_DBG_RX 8 // Capture pin for receiving
#define _ESP8266_DBG_TX 9 // Capture pin for transmitting
Baud rate of ESP8266 at factory setting is 115200 usually. This rate is too fast for the control by Arduino, so that it is necessary to re-set the appropriate baud rate at the WiFi.begin function. However, it is valid only after you have made a change in the baud rate by AT+UART of ESP8266 AT command. The baud rate just after the module reset would be restored by factory setting.
In order to reliably operate the ESP8266 it is useful to increase the buffer size of Arduino serial library. The ways generally well known is re-definition of SERIAL_RX_BUFFER_SIZE macro in HardwareSerial.h file of the Arduino IDE. An article of HOBBY ELECRONICS will be helpful.
Available operating voltage of ESP8266 is 3.0V to 3.6V (3.3V typical). Most ESP8266 module is not 5V tolerant. Using the ESP8266 module with a 5V Arduino requires the use of level shifting circuitry for RX and RST of the ESP8266 module. Level shift circuit to be connected in a properly, this article can be useful. Anyway, connected by dividing resistors is the easiest.
ESPRESSIF SYSTEMS has released a document of AT Command set.