Skip to content

Commit bafa5b4

Browse files
igrrigrr
committed
Separate project readme and core reference
1 parent c8310b7 commit bafa5b4

File tree

2 files changed

+285
-281
lines changed

2 files changed

+285
-281
lines changed

‎README.md

Lines changed: 11 additions & 281 deletions
Original file line numberDiff line numberDiff line change
@@ -15,294 +15,24 @@ Starting with 1.6.4, Arduino allows installation of third-party platform package
1515
- Enter ```http://arduino.esp8266.com/package_esp8266com_index.json``` into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas.
1616
- Open Boards Manager from Tools > Board menu and install *esp8266* platform (and don't forget to select your ESP8266 board from Tools > Board menu after installation).
1717

18-
### [Change log](hardware/esp8266com/esp8266/changes.md)
19-
2018
### Building latest version from source ###
2119
```
2220
$ git clone https://github.com/esp8266/Arduino.git
2321
$ cd Arduino/build
2422
$ ant dist
2523
```
2624

25+
### Documentation ###
26+
Latest development version: [Reference](hardware/esp8266com/esp8266/doc/README.md)
27+
2728
### Supported boards ###
2829
- Generic esp8266 modules (without auto-reset support)
29-
- NodeMCU
30+
- NodeMCU 0.9
31+
- NodeMCU 1.0
3032
- Olimex MOD-WIFI-ESP8266
31-
32-
### Things that work ###
33-
34-
#### Basic Wiring functions ####
35-
36-
```pinMode```, ```digitalRead```, ```digitalWrite```, ```analogWrite``` work as usual.
37-
38-
Pin numbers correspond directly to the esp8266 GPIO pin numbers. To read GPIO2, call ```digitalRead(2)```.
39-
40-
GPIO0-GPIO15 can be ```INPUT```, ```OUTPUT```, ```INPUT_PULLUP```, and ```INPUT_PULLDOWN```.
41-
GPIO16 can be ```INPUT```, ```OUTPUT``` or ```INPUT_PULLDOWN```.
42-
43-
```analogRead(A0)``` reads the value of the ADC channel connected to the TOUT pin.
44-
45-
```analogWrite(pin, value)``` enables software PWM on the given pin. PWM may be used on pins 0 to 15.
46-
Call ```analogWrite(pin, 0)``` to disable PWM on the pin. ```value``` may be in range from 0 to ```PWMRANGE```, which is currently equal to 1023.
47-
48-
Pin interrupts are supported through ```attachInterrupt```, ```detachInterrupt``` functions.
49-
Interrupts may be attached to any GPIO pin, except GPIO16. Standard Arduino interrupt
50-
types are supported: ```CHANGE```, ```RISING```, ```FALLING```.
51-
52-
#### Pin Functions ####
53-
54-
![Pin Functions](https://raw.githubusercontent.com/Links2004/Arduino/esp8266/docs/pin_functions.png)
55-
The most usable pin functions are mapped to the macro ```SPECIAL```, so calling ```pinMode(pin, SPECIAL)```
56-
will switch that pin in the most usable FUNCTION_X. Those are UART RX/TX on pins 1 - 3, HSPI for pins 12-15 and CLK functions for pins 0, 4 and 5.
57-
58-
#### Timing and delays ####
59-
```millis``` and ```micros``` return the number of milliseconds and microseconds elapsed after reset, respectively.
60-
61-
```delay``` pauses the sketch for a given number of milliseconds and allows WiFi and TCP/IP tasks to run.
62-
```delayMicroseconds``` pauses for a given number of microseconds.
63-
64-
Remember that there is a lot of code that needs to run on the chip besides the sketch
65-
when WiFi is connected. WiFi and TCP/IP libraries get a chance to handle any pending
66-
events each time the ```loop()``` function completes, OR when ```delay(...)``` is called.
67-
If you have a loop somewhere in your sketch that takes a lot of time (>50ms) without
68-
calling ```delay()```, you might consider adding a call to delay function to keep the WiFi
69-
stack running smoothly.
70-
71-
There is also a ```yield()``` function which is equivalent to ```delay(0)```. The delayMicroseconds
72-
function, on the other hand, does not yield to other tasks, so using it for delays
73-
more than 20 milliseconds is not recommended.
74-
75-
#### Serial ####
76-
77-
```Serial``` object works much the same way as on a regular Arduino. Apart from hardware FIFO (128 bytes for TX and RX) HardwareSerial has additional 256-byte TX and RX buffers. Both transmit and receive is interrupt-driven. Write and read functions only block the sketch execution when the respective FIFO/buffers are full/empty.
78-
79-
```Serial``` uses UART0, which is mapped to pins GPIO1 (TX) and GPIO3 (RX). Serial may be remapped to GPIO15 (TX) and GPIO13 (RX) by calling ```Serial.swap()``` after ```Serial.begin()```. Calling ```swap``` again maps UART0 back to GPIO1 and GPIO3.
80-
81-
```Serial1``` uses UART1 which is a transmit-only UART. UART1 TX pin is GPIO2. To use ```Serial1```, call ```Serial1.begin```.
82-
83-
By default the diagnostic output from WiFi libraries is disabled when you call ```Serial.begin```. To enable debug output again, call ```Serial.setDebugOutput(true)```. To redirect debug output to ```Serial1``` instead, call ```Serial1.setDebugOutput(true)```.
84-
85-
You also need to use ```Serial.setDebugOutput(true)``` to enable output from the Arduino ```printf()``` function.
86-
87-
Both ```Serial``` and ```Serial1``` objects support 5, 6, 7, 8 data bits, odd (O), even (E), and no (N) parity, and 1 or 2 stop bits. To set the desired mode, call ```Serial.begin(baudrate, SERIAL_8N1)```, ```Serial.begin(baudrate, SERIAL_6E2)```, etc.
88-
89-
#### Progmem ####
90-
91-
The Program memory features work much the same way as on a regular Arduino; placing read only data and strings in read only memory and freeing heap for your application.
92-
The important difference is that on the esp8266 the literal strings are not pooled. This means that the same literal string defined inside a ```F("")``` and/or ```PSTR("")``` will take up space for each instance in the code. So you will need to manage the duplicate strings yourself.
93-
94-
#### WiFi(ESP8266WiFi library) ####
95-
96-
This is mostly similar to WiFi shield library. Differences include:
97-
98-
- ```WiFi.mode(m)```: set mode to ```WIFI_AP```, ```WIFI_STA```, or ```WIFI_AP_STA```.
99-
- call ```WiFi.softAP(ssid)``` to set up an open network
100-
- call ```WiFi.softAP(ssid, password)``` to set up a WPA2-PSK network (password should be at least 8 characters)
101-
- ```WiFi.macAddress(mac)``` is for STA, ```WiFi.softAPmacAddress(mac)``` is for AP.
102-
- ```WiFi.localIP()``` is for STA, ```WiFi.softAPIP()``` is for AP.
103-
- ```WiFi.RSSI()``` doesn't work
104-
- ```WiFi.printDiag(Serial)``` will print out some diagnostic info
105-
- ```WiFiUDP``` class supports sending and receiving multicast packets on STA interface.
106-
When sending a multicast packet, replace ```udp.beginPacket(addr, port)``` with
107-
```udp.beginPacketMulticast(addr, port, WiFi.localIP())```.
108-
When listening to multicast packets, replace ```udp.begin(port)``` with
109-
```udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)```.
110-
You can use ```udp.destinationIP()``` to tell whether the packet received was
111-
sent to the multicast or unicast address.
112-
Also note that multicast doesn't work on softAP interface.
113-
114-
```WiFiServer```, ```WiFiClient```, and ```WiFiUDP``` behave mostly the same way as with WiFi shield library.
115-
Four samples are provided for this library.
116-
You can see more commands here: [http://www.arduino.cc/en/Reference/WiFi](http://www.arduino.cc/en/Reference/WiFi)
117-
118-
#### Ticker ####
119-
120-
Library for calling functions repeatedly with a certain period. Two examples included.
121-
122-
It is currently not recommended to do blocking IO operations (network, serial, file) from Ticker
123-
callback functions. Instead, set a flag inside the ticker callback and check for that flag inside the loop function.
124-
125-
#### EEPROM ####
126-
127-
This is a bit different from standard EEPROM class. You need to call ```EEPROM.begin(size)```
128-
before you start reading or writing, size being the number of bytes you want to use.
129-
Size can be anywhere between 4 and 4096 bytes.
130-
131-
```EEPROM.write``` does not write to flash immediately, instead you must call ```EEPROM.commit()```
132-
whenever you wish to save changes to flash. ```EEPROM.end()``` will also commit, and will
133-
release the RAM copy of EEPROM contents.
134-
135-
EEPROM library uses one sector of flash located at 0x7b000 for storage.
136-
137-
Three examples included.
138-
139-
#### I2C (Wire library) ####
140-
141-
Wire library currently supports master mode up to approximately 450KHz.
142-
Before using I2C, pins for SDA and SCL need to be set by calling
143-
```Wire.begin(int sda, int scl)```, i.e. ```Wire.begin(0, 2)``` on ESP-01,
144-
else they default to pins 4(SDA) and 5(SCL).
145-
146-
#### SPI ####
147-
148-
SPI library supports the entire Arduino SPI API including transactions, including setting phase (CPHA).
149-
Setting the Clock polarity (CPOL) is not supported, yet (SPI_MODE2 and SPI_MODE3 not working).
150-
151-
#### ESP-specific APIs ####
152-
153-
APIs related to deep sleep and watchdog timer are available in the ```ESP``` object, only available in Alpha version.
154-
155-
```ESP.deepSleep(microseconds, mode)``` will put the chip into deep sleep. ```mode``` is one of ```WAKE_RF_DEFAULT```, ```WAKE_RFCAL```, ```WAKE_NO_RFCAL```, ```WAKE_RF_DISABLED```. (GPIO16 needs to be tied to RST to wake from deepSleep.)
156-
157-
```ESP.restart()``` restarts the CPU.
158-
159-
```ESP.getFreeHeap()``` returns the free heap size.
160-
161-
```ESP.getChipId()``` returns the ESP8266 chip ID as a 32-bit integer.
162-
163-
Several APIs may be used to get flash chip info:
164-
165-
```ESP.getFlashChipId()``` returns the flash chip ID as a 32-bit integer.
166-
167-
```ESP.getFlashChipSize()``` returns the flash chip size, in bytes, as seen by the SDK (may be less than actual size).
168-
169-
```ESP.getFlashChipSpeed(void)``` returns the flash chip frequency, in Hz.
170-
171-
```ESP.getCycleCount()``` returns the cpu instruction cycle count since start as an unsigned 32-bit. This is useful for accurate timing of very short actions like bit banging.
172-
173-
```ESP.getVcc()``` may be used to measure supply voltage. ESP needs to reconfigure the ADC
174-
at startup in order for this feature to be available. Add the following line to the top
175-
of your sketch to use ```getVcc```:
176-
177-
ADC_MODE(ADC_VCC);
178-
179-
TOUT pin has to be disconnected in this mode.
180-
181-
Note that by default ADC is configured to read from TOUT pin using ```analogRead(A0)```, and
182-
```ESP.getVCC()``` is not available.
183-
184-
#### OneWire (from https://www.pjrc.com/teensy/td_libs_OneWire.html) ####
185-
186-
Library was adapted to work with ESP8266 by including register definitions into OneWire.h
187-
Note that if you already have OneWire library in your Arduino/libraries folder, it will be used
188-
instead of the one that comes with this package.
189-
190-
#### mDNS responder (ESP8266mDNS library) ####
191-
192-
Allows the sketch to respond to multicast DNS queries for domain names like "foo.local".
193-
Currently the library only works on STA interface, AP interface is not supported.
194-
See attached example and library README file for details.
195-
196-
#### DNS server (DNSServer library) ####
197-
198-
Implements a simple DNS server that can be used in both STA and AP modes. The DNS server currently supports only one domain (for all other domains it will reply with NXDOMAIN or custom status code). With it clients can open a web server running on ESP8266 using a domain name, not an IP address.
199-
See attached example for details.
200-
201-
#### Servo ####
202-
203-
This library exposes the ability to control RC (hobby) servo motors. It will support upto 24 servos on any available output pin. By defualt the first 12 servos will use Timer0 and currently this will not interfere with any other support. Servo counts above 12 will use Timer1 and features that use it will be effected.
204-
While many RC servo motors will accept the 3.3V IO data pin from a esp8266, most will not be able to run off 3.3v and will require another power source that matches their specifications. Make sure to connect the grounds between the esp8266 and the servo motor power supply.
205-
206-
#### Other libraries (not included with the IDE)
207-
208-
Libraries that don't rely on low-level access to AVR registers should work well. Here are a few libraries that were verified to work:
209-
210-
- [arduinoWebSockets](https://github.com/Links2004/arduinoWebSockets) - WebSocket Server and Client compatible with esp8266 (RFC6455)
211-
- [aREST](https://github.com/marcoschwartz/aREST) REST API handler library.
212-
- [Blynk](https://github.com/blynkkk/blynk-library) - easy IoT framework for Makers (check out the [Kickstarter page](http://tiny.cc/blynk-kick)).
213-
- [DallasTemperature](https://github.com/milesburton/Arduino-Temperature-Control-Library.git)
214-
- [DHT11](https://github.com/adafruit/DHT-sensor-library) - Download latest v1.1.0 library and no changes are necessary. Older versions should initialize DHT as follows: ```DHT dht(DHTPIN, DHTTYPE, 15)```
215-
- [NeoPixel](https://github.com/adafruit/Adafruit_NeoPixel) - Adafruit's NeoPixel library, now with support for the ESP8266 (use version 1.0.2 or higher from Arduino's library manager).
216-
- [NeoPixelBus](https://github.com/Makuna/NeoPixelBus) - Arduino NeoPixel library compatible with esp8266. Use the "NeoPixelAnimator" branch for esp8266 to get HSL color support and more.
217-
- [PubSubClient](https://github.com/Imroy/pubsubclient) MQTT library by @Imroy.
218-
- [RTC](https://github.com/Makuna/Rtc) - Arduino Library for Ds1307 & Ds3231 compatible with esp8266.
219-
- [Souliss, Smart Home](https://github.com/souliss/souliss) - Framework for Smart Home based on Arduino, Android and openHAB.
33+
- Adafruit HUZZAH ESP8266 (ESP-12)
22034
- [ST7735](https://github.com/nzmichaelh/Adafruit-ST7735-Library) - Adafruit's ST7735 library modified to be compatible with esp8266. Just make sure to modify the pins in the examples as they are still AVR specific.
22135

222-
#### Upload via serial port ####
223-
Pick the correct serial port.
224-
You need to put ESP8266 into bootloader mode before uploading code.
225-
226-
#### Power Supply ####
227-
228-
For stable use of the ESP8266 a power supply with 3.3V and >= 250mA is required.
229-
230-
* Note
231-
- using Power from USB to Serial is may unstable, they not deliver enough current.
232-
233-
#### Serial Adapter ####
234-
235-
There are many different USB to Serial adapters / boards.
236-
237-
* Note
238-
- for full upload management you need RTS and DTR
239-
- the chip need to have 3.3V TTL (5V may damage the chip)
240-
- not all board have all pins of the ICs as breakout (check before order)
241-
- CTS and DSR are not useful for upload (they are Inputs)
242-
243-
* Working ICs
244-
- FT232RL
245-
- CP2102
246-
- may others (drop a comment)
247-
248-
#### Minimal hardware Setup for Bootloading and usage ####
249-
250-
ESPxx Hardware
251-
252-
| PIN | Resistor | Serial Adapter |
253-
| ------------- | -------- | -------------- |
254-
| VCC | | VCC (3.3V) |
255-
| GND | | GND |
256-
| TX or GPIO2* | | RX |
257-
| RX | | TX |
258-
| GPIO0 | PullUp | DTR |
259-
| Reset* | | RTS |
260-
| GPIO15* | PullDown | |
261-
| CH_PD | PullUp | |
262-
263-
* Note
264-
- GPIO15 is also named MTDO
265-
- Reset is also named RSBT or REST (adding PullUp improves the stability of the Module)
266-
- GPIO2 is alternative TX for the boot loader mode
267-
268-
###### esp to Serial
269-
![ESP to Serial](https://raw.githubusercontent.com/Links2004/Arduino/esp8266/docs/ESP_to_serial.png)
270-
271-
#### Minimal hardware Setup for Bootloading only ####
272-
ESPxx Hardware
273-
274-
| PIN | Resistor | Serial Adapter |
275-
| ------------- | -------- | --------------- |
276-
| VCC | | VCC (3.3V) |
277-
| GND | | GND |
278-
| TX or GPIO2 | | RX |
279-
| RX | | TX |
280-
| GPIO0 | | GND |
281-
| Reset | | RTS* |
282-
| GPIO15 | PullDown | |
283-
| CH_PD | PullUp | |
284-
285-
* Note
286-
- if no RTS is used a manual power toggle is needed
287-
288-
#### Minimal hardware Setup for running only ####
289-
290-
ESPxx Hardware
291-
292-
| PIN | Resistor | Power supply |
293-
| ------------- | -------- | --------------- |
294-
| VCC | | VCC (3.3V) |
295-
| GND | | GND |
296-
| GPIO0 | PullUp | |
297-
| GPIO15 | PullDown | |
298-
| CH_PD | PullUp | |
299-
300-
###### minimal
301-
![ESP min](https://raw.githubusercontent.com/Links2004/Arduino/esp8266/docs/ESP_min.png)
302-
303-
###### improved stability
304-
![ESP improved stability](https://raw.githubusercontent.com/Links2004/Arduino/esp8266/docs/ESP_improved_stability.png)
305-
30636
### Issues and support ###
30737

30838
Forum: http://www.esp8266.com/arduino
@@ -311,14 +41,14 @@ Submit issues on Github: https://github.com/esp8266/Arduino/issues
31141

31242
### License and credits ###
31343

314-
Arduino IDE is based on Wiring and Processing. It is developed and maintained by the Arduino team. The IDE is licensed under GPL, and the core libraries are licensed under LGPL.
44+
Arduino IDE is based on Wiring and Processing. It is developed and maintained by the Arduino team. The IDE is licensed under GPL.
31545

316-
This build includes an xtensa gcc toolchain, which is also under GPL.
317-
318-
Espressif SDK included in this build is under Espressif Public License.
46+
ESP8266 core includes an xtensa gcc toolchain, which is also under GPL.
31947

32048
Esptool written by Christian Klippel is licensed under GPLv2, currently maintained by Ivan Grokhotkov: https://github.com/igrr/esptool-ck.
32149

322-
ESP8266 core support, ESP8266WiFi, Ticker, ESP8266WebServer libraries were written by Ivan Grokhotkov, [email protected].
50+
Espressif SDK included in this build is under Espressif MIT License.
51+
52+
ESP8266 core files are licensed under LGPL.
32353

32454
[SPI Flash File System (SPIFFS)](https://github.com/pellepl/spiffs) written by Peter Andersson is used in this project. It is distributed under MIT license.

0 commit comments

Comments
 (0)