Skip to content

Commit 6824dba

Browse files
igrrigrr
committed
Update readme
[ci skip]
1 parent 8e021ed commit 6824dba

File tree

1 file changed

+89
-82
lines changed

1 file changed

+89
-82
lines changed

‎README.md

+89-82
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,119 @@
1-
Arduino IDE with ESP8266 support
2-
================================
1+
Arduino-compatible IDE with ESP8266 support
2+
===========================================
33

4-
This is an early beta. Things might not work as expected, please do report any bugs you find.
4+
This project brings support for ESP8266 chip to the Arduino environment. ESP8266WiFi library bundled with this project has the same interface as the WiFi Shield library, making it easy to re-use existing code and libraries.
55

6-
Downloads
7-
---------
6+
### Downloads ###
87

98
| OS | Build status | Latest release |
109
| --- | ------------ | -------------- |
11-
| Linux | [![Linux build status](http://img.shields.io/travis/igrr/Arduino.svg)](https://travis-ci.org/igrr/Arduino) | [arduino-1.6.1-linux64.tar.xz](releases/download/arduino-1.6.1-esp8266-1/arduino-1.6.1-linux64.tar.xz) |
12-
| Windows | [![Windows build status](http://img.shields.io/appveyor/ci/igrr/Arduino.svg)](https://ci.appveyor.com/project/igrr/Arduino) | [arduino-1.6.1-win32.zip](releases/download/arduino-1.6.1-esp8266-1/arduino-1.6.1-win32.zip) |
13-
| OS X | | [arduino-1.6.1-macosx.zip](releases/download/arduino-1.6.1-esp8266-1/arduino-1.6.1-macosx.zip) |
10+
| Linux | [![Linux build status](http://img.shields.io/travis/igrr/Arduino.svg)](https://travis-ci.org/igrr/Arduino) | [arduino-1.6.1-linux64.tar.xz](../../releases/download/1.6.1-esp8266-1/arduino-1.6.1-linux64.tar.xz) |
11+
| Windows | [![Windows build status](http://img.shields.io/appveyor/ci/igrr/Arduino.svg)](https://ci.appveyor.com/project/igrr/Arduino) | [arduino-1.6.1-windows.zip](../../releases/download/1.6.1-esp8266-1/arduino-1.6.1-windows.zip) |
12+
| OS X | | [arduino-1.6.1-macosx-java-latest-signed.zip](../../releases/download/1.6.1-esp8266-1/arduino-1.6.1-macosx-java-latest-signed.zip) |
1413

1514

16-
What works
17-
----------
15+
### Building from source ###
16+
```
17+
$ git clone https://github.com/esp8266/Arduino.git
18+
$ cd Arduino/build
19+
$ ant dist
20+
```
1821

19-
- **pinMode, digitalRead, digitalWrite**
22+
### Things that work ###
2023

21-
Pin numbers correspond directly to the esp8266 GPIO pin numbers. To read GPIO2,
22-
call digitalRead(2);
23-
GPIO0-GPIO15 can be INPUT, OUTPUT, INPUT_PULLUP, and OUTPUT_OPEN_DRAIN.
24-
GPIO16 can be INPUT or OUTPUT.
24+
#### pinMode, digitalRead, digitalWrite, analogRead ####
2525

26-
- **analogRead(0)** reads the value of the ADC channel connected to the TOUT pin.
26+
Pin numbers correspond directly to the esp8266 GPIO pin numbers. To read GPIO2,
27+
call ```digitalRead(2);```
2728

28-
- **pin interrupts (attachInterrupt, detachInterrupt)**
29+
GPIO0-GPIO15 can be ```INPUT```, ```OUTPUT```, ```INPUT_PULLUP```, and ```OUTPUT_OPEN_DRAIN```.
30+
GPIO16 can be ```INPUT``` or ```OUTPUT```.
2931

30-
Interrupts may be attached to any GPIO pin, except GPIO16. Standard Arduino interrupt
31-
types are supported: CHANGE, RISING, FALLING.
32+
```analogRead(0)``` reads the value of the ADC channel connected to the TOUT pin.
3233

33-
- **shiftIn, shiftOut**
34-
- **millis, micros**
35-
- **delay, delayMicroseconds, yield**
34+
#### Pin interrupts (attachInterrupt, detachInterrupt) ####
3635

37-
Remember that there is a lot of code that needs to run on the chip besides the sketch
38-
when WiFi is connected. WiFi and TCP/IP libraries get a chance to handle any pending
39-
events each time the loop() function completes, OR when delay(...) is called.
40-
If you have a loop somewhere in your sketch that takes a lot of time (>50ms) without
41-
calling delay(), you might consider adding a call to delay function to keep the WiFi
42-
stack running smoothly.
43-
There is also a yield() function which is equivalent to delay(0). The delayMicroseconds
44-
function, on the other hand, does not yield to other tasks, so using it for delays
45-
more than 20 milliseconds is not recommended.
36+
Interrupts may be attached to any GPIO pin, except GPIO16. Standard Arduino interrupt
37+
types are supported: ```CHANGE```, ```RISING```, ```FALLING```.
4638

47-
- **Serial**
39+
#### shiftIn, shiftOut ####
40+
#### millis, micros ####
41+
#### delay, delayMicroseconds, yield ###
4842

49-
Only 8n1 is supported right now. By default the diagnostic output from WiFi
50-
libraries is disabled when you call Serial.begin. To enable debug output again,
51-
call Serial.setDebugOutput(true);
43+
Remember that there is a lot of code that needs to run on the chip besides the sketch
44+
when WiFi is connected. WiFi and TCP/IP libraries get a chance to handle any pending
45+
events each time the ```loop()``` function completes, OR when ```delay(...)``` is called.
46+
If you have a loop somewhere in your sketch that takes a lot of time (>50ms) without
47+
calling ```delay()```, you might consider adding a call to delay function to keep the WiFi
48+
stack running smoothly.
5249

53-
- **Ticker**
50+
There is also a ```yield()``` function which is equivalent to ```delay(0)```. The delayMicroseconds
51+
function, on the other hand, does not yield to other tasks, so using it for delays
52+
more than 20 milliseconds is not recommended.
5453

55-
Library for calling functions repeatedly with a certain period. Two examples included.
54+
#### Serial ####
5655

57-
- **EEPROM**
56+
Only 8n1 is supported right now. By default the diagnostic output from WiFi
57+
libraries is disabled when you call ```Serial.begin```. To enable debug output again,
58+
call ```Serial.setDebugOutput(true);```
5859

59-
This is a bit different from standard EEPROM class. You need to call EEPROM.begin(size)
60-
before you start reading or writing, size being the number of bytes you want to use.
61-
Size can be anywhere between 4 and 4096 bytes.
62-
EEPROM.write does not write to flash immediately, instead you must call EEPROM.commit()
63-
whenever you wish to save changes to flash. EEPROM.end() will also commit, and will
64-
release the RAM copy of EEPROM contents.
65-
Three examples included.
60+
#### WiFi(ESP8266WiFi library) ####
6661

67-
- **I2C (Wire library)**
62+
This is mostly similar to WiFi shield library. Differences include:
6863

69-
Only master mode works, and I haven't tested if Wire.setClock gives correct frequency.
70-
Before using I2C, you need to set pins you will use for SDA and SCL by calling
71-
Wire.pins(int sda, int scl), i.e. Wire.pins(0, 2); on ESP-01.
64+
- ```WiFi.mode(m)```: set mode to ```WIFI_AP```, ```WIFI_STA```, or ```WIFI_AP_STA```.
65+
- call ```WiFi.softAP(ssid)``` to set up an open network
66+
- call ```WiFi.softAP(ssid, passphrase)``` to set up a WPA2-PSK network
67+
- ```WiFi.macAddress(mac)``` is for STA, ```WiFi.softAPmacAddress(mac)``` is for AP.
68+
- ```WiFi.localIP()``` is for STA, ```WiFi.softAPIP()``` is for AP.
69+
- ```WiFi.RSSI()``` doesn't work
70+
- ```WiFi.printDiag(Serial);``` will print out some diagnostic info
7271

73-
- **OneWire (from https://www.pjrc.com/teensy/td_libs_OneWire.html)**
72+
WiFiServer, WiFiClient, and WiFiUDP behave mostly the same way as with WiFi shield library.
73+
Three samples are provided for this library.
7474

75-
Library was adapted to work with ESP8266 by including register definitions into OneWire.h
76-
Note that if you have OneWire library in your Arduino/libraries folder, it will be used
77-
instead of the one that comes with the Arduino IDE (this one).
75+
#### Ticker ####
7876

79-
- **WiFi(ESP8266WiFi library)**
77+
Library for calling functions repeatedly with a certain period. Two examples included.
8078

81-
This is mostly similar to WiFi shield library. Differences include:
82-
* WiFi.mode(m): set mode to WIFI_AP, WIFI_STA, or WIFI_AP_STA.
83-
* call WiFi.softAP(ssid) to set up an open network
84-
* call WiFi.softAP(ssid, passphrase) to set up a WPA2-PSK network
85-
* WiFi.macAddress(mac) is for STA, WiFi.softAPmacAddress(mac) is for AP.
86-
* WiFi.localIP() is for STA, WiFi.softAPIP() is for AP.
87-
* WiFi.RSSI() doesn't work
88-
* WiFi.printDiag(Serial); will print out some diagnostic info
89-
WiFiServer, WiFiClient, and WiFiUDP behave mostly the same way as with WiFi shield library.
90-
Three samples are provided for this library.
79+
#### EEPROM ####
9180

92-
- **mDNS responder (ESP8266mDNS library)**
81+
This is a bit different from standard EEPROM class. You need to call ```EEPROM.begin(size)```
82+
before you start reading or writing, size being the number of bytes you want to use.
83+
Size can be anywhere between 4 and 4096 bytes.
84+
```EEPROM.write``` does not write to flash immediately, instead you must call ```EEPROM.commit()```
85+
whenever you wish to save changes to flash. ```EEPROM.end()``` will also commit, and will
86+
release the RAM copy of EEPROM contents.
9387

94-
Allows the sketch to respond to multicast DNS queries for domain names like "foo.local".
95-
See attached example and library README file for details.
88+
Three examples included.
9689

97-
- Other libraries that don't rely on low-level access to AVR registers.
90+
#### I2C (Wire library) ####
9891

99-
- Upload via serial port
100-
Select "esptool" as a programmer, and pick the correct serial port.
101-
You need to put ESP8266 into bootloader mode before uploading code (pull GPIO0 low and
102-
toggle power).
92+
Only master mode works, and I haven't tested if Wire.setClock gives correct frequency.
93+
Before using I2C, you need to set pins you will use for SDA and SCL by calling
94+
```Wire.pins(int sda, int scl)```, i.e. ```Wire.pins(0, 2);``` on ESP-01.
10395

104-
What is not done yet
105-
--------------------
96+
#### OneWire (from https://www.pjrc.com/teensy/td_libs_OneWire.html) ####
97+
98+
Library was adapted to work with ESP8266 by including register definitions into OneWire.h
99+
Note that if you have OneWire library in your Arduino/libraries folder, it will be used
100+
instead of the one that comes with the Arduino IDE (this one).
101+
102+
#### mDNS responder (ESP8266mDNS library) ####
103+
104+
Allows the sketch to respond to multicast DNS queries for domain names like "foo.local".
105+
See attached example and library README file for details.
106+
107+
#### Other libraries that don't rely on low-level access to AVR registers.
108+
109+
- [PubSubClient](https://github.com/knolleary/pubsubclient) - [sample](https://gist.github.com/igrr/7f7e7973366fc01d6393)
110+
111+
#### Upload via serial port ####
112+
Select "esptool" as a programmer, and pick the correct serial port.
113+
You need to put ESP8266 into bootloader mode before uploading code (pull GPIO0 low and
114+
toggle power).
115+
116+
### Things not done yet ###
106117

107118
- analogWrite (PWM). ESP8266 has only one hardware PWM source. It is not yet clear how to use it with analogWrite API. Software PWM is also an option, but apparently it causes issues with WiFi connectivity.
108119
- pulseIn
@@ -115,18 +126,14 @@ What is not done yet
115126
- Samples for all the libraries
116127

117128

118-
License and credits
119-
-------------------
129+
### License and credits ###
120130

121-
Arduino IDE is licensed under GPL, with Arduino core libraries licensed under LGPL.
131+
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.
122132

123133
This build includes an xtensa gcc toolchain, which is also under GPL.
124134

125135
Espressif SDK included in this build is under Espressif Public License.
126136

127-
Esptool written by Christian Klippel is licensed under GPLv2.
128-
The source with my modfications is available on github: https://github.com/igrr/esptool-ck
129-
130-
ESP8266 port contributed by Ivan Grokhotkov, ivan@esp8266.com.
131-
137+
Esptool written by Christian Klippel is licensed under GPLv2, currently maintained by Ivan Grokhotkov: https://github.com/igrr/esptool-ck.
132138

139+
ESP8266 core support, ESP8266WiFi, Ticker, ESP8266WebServer libraries were written by Ivan Grokhotkov, ivan@esp8266.com.

0 commit comments

Comments
 (0)