API
For Arduino developers
README.md
1 @mainpage
2 
3 # WeeESP8266
4 
5 An ESP8266 library for Arduino providing an easy-to-use way to manipulate ESP8266.
6 
7 # Source
8 
9 Source can be download at <https://github.com/itead/ITEADLIB_Arduino_WeeESP8266>.
10 
11 You can clone it by:
12 
13  git clone https://github.com/itead/ITEADLIB_Arduino_WeeESP8266.git
14 
15 # Documentation
16 
17 Online API documentation can be reached at <http://docs.iteadstudio.com/ITEADLIB_Arduino_WeeESP8266/index.html>.
18 
19 Offline API documentation can be found under directory
20 [doc](https://github.com/itead/ITEADLIB_Arduino_WeeESP8266/tree/master/doc).
21 
22 # How to get started
23 
24 On the home page of API documentation, the tabs of Examples, Classes and Modules
25 will be useful for Arduino lovers.
26 
27 # API List
28 
29  bool kick (void) : Verify ESP8266 whether live or not.
30 
31  bool restart (void) : Restart ESP8266 by "AT+RST".
32 
33  String getVersion (void) : Get the version of AT Command Set.
34 
35  bool setOprToStation (void) : Set operation mode to staion.
36 
37  bool setOprToSoftAP (void) : Set operation mode to softap.
38 
39  bool setOprToStationSoftAP (void) : Set operation mode to station + softap.
40 
41  String getAPList (void) : Search available AP list and return it.
42 
43  bool joinAP (String ssid, String pwd) : Join in AP.
44 
45  bool leaveAP (void) : Leave AP joined before.
46 
47  bool setSoftAPParam (String ssid, String pwd, uint8_t chl=7, uint8_t ecn=4) : Set SoftAP parameters.
48 
49  String getJoinedDeviceIP (void) : Get the IP list of devices connected to SoftAP.
50 
51  String getIPStatus (void) : Get the current status of connection(UDP and TCP).
52 
53  String getLocalIP (void) : Get the IP address of ESP8266.
54 
55  bool enableMUX (void) : Enable IP MUX(multiple connection mode).
56 
57  bool disableMUX (void) : Disable IP MUX(single connection mode).
58 
59  bool createTCP (String addr, uint32_t port) : Create TCP connection in single mode.
60 
61  bool releaseTCP (void) : Release TCP connection in single mode.
62 
63  bool registerUDP (String addr, uint32_t port) : Register UDP port number in single mode.
64 
65  bool unregisterUDP (void) : Unregister UDP port number in single mode.
66 
67  bool createTCP (uint8_t mux_id, String addr, uint32_t port) : Create TCP connection in multiple mode.
68 
69  bool releaseTCP (uint8_t mux_id) : Release TCP connection in multiple mode.
70 
71  bool registerUDP (uint8_t mux_id, String addr, uint32_t port) : Register UDP port number in multiple mode.
72 
73  bool unregisterUDP (uint8_t mux_id) : Unregister UDP port number in multiple mode.
74 
75  bool setTCPServerTimeout (uint32_t timeout=180) : Set the timeout of TCP Server.
76 
77  bool startServer (uint32_t port=333) : Start Server(Only in multiple mode).
78 
79  bool stopServer (void) : Stop Server(Only in multiple mode).
80 
81  bool startTCPServer (uint32_t port=333) : Start TCP Server(Only in multiple mode).
82 
83  bool stopTCPServer (void) : Stop TCP Server(Only in multiple mode).
84 
85  bool send (const uint8_t *buffer, uint32_t len) : Send data based on TCP or UDP builded already in single mode.
86 
87  bool send (uint8_t mux_id, const uint8_t *buffer, uint32_t len) : Send data based on one of TCP or UDP builded already in multiple mode.
88 
89  uint32_t recv (uint8_t *buffer, uint32_t buffer_size, uint32_t timeout=1000) : Receive data from TCP or UDP builded already in single mode.
90 
91  uint32_t recv (uint8_t mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout=1000) : Receive data from one of TCP or UDP builded already in multiple mode.
92 
93  uint32_t recv (uint8_t *coming_mux_id, uint8_t *buffer, uint32_t buffer_size, uint32_t timeout=1000) : Receive data from all of TCP or UDP builded already in multiple mode.
94 
95 
96 # Mainboard Requires
97 
98  - RAM: not less than 2KBytes
99  - Serial: one serial (HardwareSerial or SoftwareSerial) at least
100 
101 # Suppported Mainboards
102 
103  - Arduino UNO and its derivatives
104  - Arduino MEGA and its derivatives
105  - [Iteaduino UNO](http://imall.iteadstudio.com/im130312001.html)
106  - [WBoard Pro](http://imall.iteadstudio.com/im141125005.html)
107 
108 # Select the version of ESP8266 AT Firmware
109 
110 At present, this library supports ESP8266 AT 0.18 version and 0.22 version. You
111 can select one of them to fit your module by modifing this line in `ESP8266.h`:
112 
113  #define USER_SEL_VERSION VERSION_18
114 
115 If you want to select 0.22 version, it should be like below after modification:
116 
117  #define USER_SEL_VERSION VERSION_22
118 
119 
120 # Using SoftwareSerial
121 
122 If you want to use SoftwareSerial to communicate with ESP8266, you need to modify
123 the line in file `ESP8266.h`:
124 
125  //#define ESP8266_USE_SOFTWARE_SERIAL
126 
127 After modification, it should be:
128 
129  #define ESP8266_USE_SOFTWARE_SERIAL
130 
131 
132 # Hardware Connection
133 
134 WeeESP8266 library only needs an uart for hardware connection. All communications
135 are done via uart. In each example, you must specify the uart used by mainboard
136 to communicate with ESP8266 flashed AT firmware.
137 
138 ## MEGA and WBoard Pro
139 
140 For MEGA and WBoard Pro, `Serial1` will be used if you create an object (named wifi)
141 of class ESP8266 in your code like this:
142 
143  #include "ESP8266.h"
144  ESP8266 wifi(Serial1);
145 
146 The connection should be like these:
147 
148  ESP8266_TX->RX1(D19)
149  ESP8266_RX->TX1(D18)
150  ESP8266_CH_PD->3.3V
151  ESP8266_VCC->3.3V
152  ESP8266_GND->GND
153 
154 ## UNO
155 
156 To use SoftwareSerial, `mySerial` will be used if you create an object (named wifi)
157 of class ESP8266 in your code like this:
158 
159  #include "ESP8266.h"
160  #include <SoftwareSerial.h>
161 
162  SoftwareSerial mySerial(3, 2); /* RX:D3, TX:D2 */
163  ESP8266 wifi(mySerial);
164 
165 The connection should be like these:
166 
167  ESP8266_TX->RX(D3)
168  ESP8266_RX->TX(D2)
169  ESP8266_CH_PD->3.3V
170  ESP8266_VCC->3.3V
171  ESP8266_GND->GND
172 
173 # Attention
174 
175 The size of data from ESP8266 is too big for arduino sometimes, so the library can't
176 receive the whole buffer because the size of the hardware serial buffer which is
177 defined in HardwareSerial.h is too small.
178 
179 Open the file from `\arduino\hardware\arduino\avr\cores\arduino\HardwareSerial.h`.
180 See the follow line in the HardwareSerial.h file.
181 
182  #define SERIAL_BUFFER_SIZE 64
183 
184 The default size of the buffer is 64. Change it into a bigger number, like 256 or more.
185 
186 
187 -------------------------------------------------------------------------------
188 
189 # The End!
190 
191 -------------------------------------------------------------------------------
Provide an easy-to-use way to manipulate ESP8266.
Definition: ESP8266.h:42
#define USER_SEL_VERSION
You can modify the macro to choose a different version.
Definition: ESP8266.h:37