diff --git a/ESP8266/ESP8266.cpp b/ESP8266/ESP8266.cpp index e1652cb..5c8ccfe 100644 --- a/ESP8266/ESP8266.cpp +++ b/ESP8266/ESP8266.cpp @@ -15,24 +15,29 @@ */ #include "ESP8266.h" -#include "mbed_debug.h" +#include "Callback.h" +#include "mbed_error.h" #include "nsapi_types.h" +#include "PinNames.h" #include #define ESP8266_DEFAULT_BAUD_RATE 115200 #define ESP8266_ALL_SOCKET_IDS -1 -ESP8266::ESP8266(PinName tx, PinName rx, bool debug) - : _serial(tx, rx, ESP8266_DEFAULT_BAUD_RATE), - _parser(&_serial), - _packets(0), +ESP8266::ESP8266(PinName tx, PinName rx, bool debug, PinName rts, PinName cts) + : _serial(tx, rx, ESP8266_DEFAULT_BAUD_RATE), + _serial_rts(rts), + _serial_cts(cts), + _parser(&_serial), + _packets(0), _packets_end(&_packets), _connect_error(0), _fail(false), _closed(false), _socket_open(), - _connection_status(NSAPI_STATUS_DISCONNECTED) + _connection_status(NSAPI_STATUS_DISCONNECTED), + _heap_usage(0) { _serial.set_baud( ESP8266_DEFAULT_BAUD_RATE ); _parser.debug_on(debug); @@ -70,6 +75,46 @@ int ESP8266::get_firmware_version() } } +bool ESP8266::stop_uart_hw_flow_ctrl(void) +{ + // Stop board's flow control + _serial.set_flow_control(SerialBase::Disabled, _serial_rts, _serial_cts); + + // Stop ESP8266's flow control + bool done = _parser.send("AT+UART_CUR=%u,8,1,0,0", ESP8266_DEFAULT_BAUD_RATE) + && _parser.recv("OK\n"); + + return done; +} + +bool ESP8266::start_uart_hw_flow_ctrl(void) +{ + bool done = true; + + if (_serial_rts != NC && _serial_cts != NC) { + // Start board's flow control + _serial.set_flow_control(SerialBase::RTSCTS, _serial_rts, _serial_cts); + + // Start ESP8266's flow control + done = _parser.send("AT+UART_CUR=%u,8,1,0,3", ESP8266_DEFAULT_BAUD_RATE) + && _parser.recv("OK\n"); + + } else if (_serial_rts != NC) { + _serial.set_flow_control(SerialBase::RTS, _serial_rts, NC); + + done = _parser.send("AT+UART_CUR=%u,8,1,0,2", ESP8266_DEFAULT_BAUD_RATE) + && _parser.recv("OK\n"); + + } else if (_serial_cts != NC) { + done = _parser.send("AT+UART_CUR=%u,8,1,0,1", ESP8266_DEFAULT_BAUD_RATE) + && _parser.recv("OK\n"); + + _serial.set_flow_control(SerialBase::CTS, NC, _serial_cts); + } + + return done; +} + bool ESP8266::startup(int mode) { if (!(mode == WIFIMODE_STATION || mode == WIFIMODE_SOFTAP @@ -361,7 +406,10 @@ nsapi_error_t ESP8266::send(int id, const void *data, uint32_t amount) if (_parser.send("AT+CIPSEND=%d,%lu", id, amount) && _parser.recv(">") && _parser.write((char*)data, (int)amount) >= 0) { - while (_parser.process_oob()); // multiple sends in a row require this + // No flow control, data overrun is possible + if (_serial_rts == NC) { + while (_parser.process_oob()); // Drain USART receive register + } _smutex.unlock(); return NSAPI_ERROR_OK; } @@ -376,25 +424,37 @@ void ESP8266::_packet_handler() { int id; int amount; + int pdu_len; // parse out the packet if (!_parser.recv(",%d,%d:", &id, &amount)) { return; } - struct packet *packet = (struct packet*)malloc( - sizeof(struct packet) + amount); + pdu_len = sizeof(struct packet) + amount; + + if ((_heap_usage + pdu_len) > MBED_CONF_ESP8266_SOCKET_BUFSIZE) { + MBED_WARNING(MBED_MAKE_ERROR(MBED_MODULE_DRIVER, MBED_ERROR_CODE_ENOBUFS), \ + "ESP8266::_packet_handler(): \"esp8266.socket-bufsize\"-limit exceeded, packet dropped"); + return; + } + + struct packet *packet = (struct packet*)malloc(pdu_len); if (!packet) { - debug("ESP8266: could not allocate memory for RX data\n"); + MBED_WARNING(MBED_MAKE_ERROR(MBED_MODULE_DRIVER, MBED_ERROR_CODE_ENOMEM), \ + "ESP8266::_packet_handler(): Could not allocate memory for RX data"); return; } + _heap_usage += pdu_len; packet->id = id; packet->len = amount; + packet->alloc_len = amount; packet->next = 0; if (_parser.read((char*)(packet + 1), amount) < amount) { free(packet); + _heap_usage -= pdu_len; return; } @@ -403,17 +463,23 @@ void ESP8266::_packet_handler() _packets_end = &packet->next; } +void ESP8266::process_oob(uint32_t timeout, bool all) { + setTimeout(timeout); + // Poll for inbound packets + while (_parser.process_oob() && all) { + } + setTimeout(); +} + int32_t ESP8266::recv_tcp(int id, void *data, uint32_t amount, uint32_t timeout) { _smutex.lock(); - setTimeout(timeout); - // Poll for inbound packets - while (_parser.process_oob()) { + // No flow control, drain the USART receive register ASAP to avoid data overrun + if (_serial_rts == NC) { + process_oob(timeout, true); } - setTimeout(); - // check if any packets are ready for us for (struct packet **p = &_packets; *p; p = &(*p)->next) { if ((*p)->id == id) { @@ -426,10 +492,13 @@ int32_t ESP8266::recv_tcp(int id, void *data, uint32_t amount, uint32_t timeout) _packets_end = p; } *p = (*p)->next; + _smutex.unlock(); + uint32_t pdu_len = sizeof(struct packet) + q->alloc_len; uint32_t len = q->len; free(q); + _heap_usage -= pdu_len; return len; } else { // return only partial packet memcpy(data, q+1, amount); @@ -446,6 +515,11 @@ int32_t ESP8266::recv_tcp(int id, void *data, uint32_t amount, uint32_t timeout) _smutex.unlock(); return 0; } + + // Flow control, read from USART receive register only when no more data is buffered, and as little as possible + if (_serial_rts != NC) { + process_oob(timeout, false); + } _smutex.unlock(); return NSAPI_ERROR_WOULD_BLOCK; @@ -477,7 +551,9 @@ int32_t ESP8266::recv_udp(int id, void *data, uint32_t amount, uint32_t timeout) *p = (*p)->next; _smutex.unlock(); + uint32_t pdu_len = sizeof(struct packet) + q->alloc_len; free(q); + _heap_usage -= pdu_len; return len; } } @@ -493,13 +569,14 @@ void ESP8266::_clear_socket_packets(int id) while (*p) { if ((*p)->id == id || id == ESP8266_ALL_SOCKET_IDS) { struct packet *q = *p; + int pdu_len = sizeof(struct packet) + q->alloc_len; if (_packets_end == &(*p)->next) { _packets_end = p; // Set last packet next field/_packets } *p = (*p)->next; - free(q); + _heap_usage -= pdu_len; } else { // Point to last packet next field p = &(*p)->next; diff --git a/ESP8266/ESP8266.h b/ESP8266/ESP8266.h index 60f8524..0f76fc3 100644 --- a/ESP8266/ESP8266.h +++ b/ESP8266/ESP8266.h @@ -41,7 +41,7 @@ class ESP8266 { public: - ESP8266(PinName tx, PinName rx, bool debug=false); + ESP8266(PinName tx, PinName rx, bool debug=false, PinName rts=NC, PinName cts=NC); /** * Check firmware version of ESP8266 @@ -265,6 +265,20 @@ class ESP8266 */ nsapi_connection_status_t get_connection_status() const; + /** + * Start board's and ESP8266's UART flow control + * + * @return true if started + */ + bool start_uart_hw_flow_ctrl(); + + /** + * Stop board's and ESP8266's UART flow control + * + * @return true if started + */ + bool stop_uart_hw_flow_ctrl(); + static const int8_t WIFIMODE_STATION = 1; static const int8_t WIFIMODE_SOFTAP = 2; static const int8_t WIFIMODE_STATION_SOFTAP = 3; @@ -272,13 +286,16 @@ class ESP8266 private: UARTSerial _serial; + PinName _serial_rts; + PinName _serial_cts; ATCmdParser _parser; Mutex _smutex; // Protect serial port access struct packet { struct packet *next; int id; - uint32_t len; + uint32_t len; // Remaining length + uint32_t alloc_len; // Original length // data follows } *_packets, **_packets_end; void _packet_handler(); @@ -292,6 +309,7 @@ class ESP8266 void _connection_status_handler(); void _oob_socket_close_error(); void _clear_socket_packets(int id); + void process_oob(uint32_t timeout, bool all); char _ip_buffer[16]; char _gateway_buffer[16]; @@ -304,6 +322,7 @@ class ESP8266 int _socket_open[SOCKET_COUNT]; nsapi_connection_status_t _connection_status; Callback _connection_status_cb; + size_t _heap_usage; }; #endif diff --git a/ESP8266Interface.cpp b/ESP8266Interface.cpp index 56a4ec1..6c9d7f4 100644 --- a/ESP8266Interface.cpp +++ b/ESP8266Interface.cpp @@ -41,7 +41,7 @@ #define ESP8266_VERSION 2 ESP8266Interface::ESP8266Interface() - : _esp(MBED_CONF_ESP8266_TX, MBED_CONF_ESP8266_RX, MBED_CONF_ESP8266_DEBUG), + : _esp(MBED_CONF_ESP8266_TX, MBED_CONF_ESP8266_RX, MBED_CONF_ESP8266_DEBUG, MBED_CONF_ESP8266_RTS, MBED_CONF_ESP8266_CTS), _initialized(false), _started(false) { @@ -57,8 +57,8 @@ ESP8266Interface::ESP8266Interface() } // ESP8266Interface implementation -ESP8266Interface::ESP8266Interface(PinName tx, PinName rx, bool debug) - : _esp(tx, rx, debug), +ESP8266Interface::ESP8266Interface(PinName tx, PinName rx, bool debug, PinName rts, PinName cts) + : _esp(tx, rx, debug, rts, cts), _initialized(false), _started(false) { @@ -267,9 +267,15 @@ bool ESP8266Interface::_disable_default_softap() nsapi_error_t ESP8266Interface::_init(void) { if (!_initialized) { + if (!_esp.stop_uart_hw_flow_ctrl()) { + return NSAPI_ERROR_DEVICE_ERROR; + } if (!_esp.reset()) { return NSAPI_ERROR_DEVICE_ERROR; } + if (!_esp.start_uart_hw_flow_ctrl()) { + return NSAPI_ERROR_DEVICE_ERROR; + } if (!_get_firmware_ok()) { return NSAPI_ERROR_DEVICE_ERROR; } diff --git a/ESP8266Interface.h b/ESP8266Interface.h index 4d19dd6..20d5813 100644 --- a/ESP8266Interface.h +++ b/ESP8266Interface.h @@ -40,7 +40,7 @@ class ESP8266Interface : public NetworkStack, public WiFiInterface * @param rx RX pin * @param debug Enable debugging */ - ESP8266Interface(PinName tx, PinName rx, bool debug = false); + ESP8266Interface(PinName tx, PinName rx, bool debug=false, PinName rts=NC, PinName cts=NC); /** Start the interface * diff --git a/README.md b/README.md index 17ce2ff..2fd00e4 100644 --- a/README.md +++ b/README.md @@ -10,4 +10,45 @@ ESP8266 modules come in different shapes and formats, but the most important fac - The ESP8266 WiFi module does not allow the TCP client to bind on a specific port. - Setting up a UDP server is not possible. -- The serial port does not have hardware flow control enabled. The AT command set does not either have a way to limit the download rate. Therefore, downloading anything larger than the serial port input buffer is unreliable. An application should be able to read fast enough to stay ahead of the network. This affects mostly the TCP protocol where data would be lost with no notification. On UDP, this would lead to only packet losses which the higher layer protocol should recover from. +- The serial port does not have hardware flow control enabled by default. The AT command set does not either have a way to limit the download rate. Therefore, downloading anything larger than the serial port input buffer is unreliable. An application should be able to read fast enough to stay ahead of the network. This affects mostly the TCP protocol where data would be lost with no notification. On UDP, this would lead to only packet losses which the higher layer protocol should recover from. + +## UART HW flow control + +UART HW flow control requires you to additionally wire the CTS and RTS flow control pins between your board and your ESP8266 module. Once this is done remember to add configuration option for flow control in your app config file. Here a [ST NUCLEO-F429ZI](https://os.mbed.com/platforms/ST-Nucleo-F429ZI/) board and [ESPBee XBee Module](https://www.cascologix.com/product/espbee/) are used as an example. + +**NOTE** Not all modules expose ESP8266's RTS and CTS pins so beware when you are choosing one. + +Once you have your HW set up add configuration like this in your app config - Arduino pins D1 and D0 assumed for TX and RX: + +``` javascript +"target_overrides": { + "NUCLEO_F429ZI": { + "esp8266.rts": "PG_12", + "esp8266.cts": "PG_15" + } +``` + +### Example board pins + 1. TX - D1 (Arduino Uno Revision 3 connectivity headers) + 2. RX - D0 (Arduino Uno Revision 3 connectivity headers) + 3. RTS - PG_12 (STMicroelectronics Morpho extension pin headers) + 4. CTS - PG_15 (STMicroelectronics Morpho extension pin headers) + +### Example ESP8266 pins + 1. TX - D1 (Arduino Wireless Protoshield headers)/ TX (ESPBee XBee headers) + 2. RX - D0 (Arduino Wireless Protoshield headers)/ RX (ESPBee XBee headers) + 3. RTS - RTS (ESPBee XBee headers) + 4. CTS - CTS (ESPBee XBee headers) + +### Connections +With these pictures only consider the green and yellow wires which are connected to ESP8266. Pink wire is for reset and the rest for firmware update. TX and RX go through Arduino pins D1 and D0. + +**NOTE** GPIO15(ESPBee RTS) needs to be pulled down during startup to boot from flash, instead of firmware update or boot from SD card. Once the software is running the same pin is used as the RTS pin. + + 1. Board TX - ESP8266 RX + 2. Board RX - ESP8266 TX + 3. Board RTS(grey) - ESP8266 CTS(yellow) + 4. Board CTS(white) - ESP8266 RTS(green) + +![RTS,CTS](nucleo_esp8266_hw_fc1.jpg) +![RTS,CTS](nucleo_esp8266_hw_fc2.jpg) diff --git a/mbed_lib.json b/mbed_lib.json index 4d8cd41..8985ff0 100644 --- a/mbed_lib.json +++ b/mbed_lib.json @@ -3,11 +3,19 @@ "config": { "tx": { "help": "TX pin for serial connection", - "value": null + "value": "D1" }, "rx": { "help": "RX pin for serial connection", - "value": null + "value": "D0" + }, + "rts": { + "help": "RTS pin for serial connection", + "value": "NC" + }, + "cts": { + "help": "CTS pin for serial connection", + "value": "NC" }, "debug": { "help": "Enable debug logs", @@ -16,6 +24,10 @@ "provide-default": { "help": "Provide default WifiInterface. [true/false]", "value": false + }, + "socket-bufsize": { + "help": "Max socket data heap usage", + "value": 8192 } }, "target_overrides": { @@ -30,6 +42,10 @@ "NUCLEO_F411RE": { "tx": "D8", "rx": "D2" + }, + "NUCLEO_F429ZI": { + "rts": "NC", + "cts": "NC" } } } diff --git a/nucleo_esp8266_hw_fc1.jpg b/nucleo_esp8266_hw_fc1.jpg new file mode 100644 index 0000000..b59145a Binary files /dev/null and b/nucleo_esp8266_hw_fc1.jpg differ diff --git a/nucleo_esp8266_hw_fc2.jpg b/nucleo_esp8266_hw_fc2.jpg new file mode 100644 index 0000000..f7429ba Binary files /dev/null and b/nucleo_esp8266_hw_fc2.jpg differ