From 866921c54a889a7cb96cc3c24c304d6809dbb603 Mon Sep 17 00:00:00 2001 From: Ivan Grokhotkov Date: Mon, 23 Nov 2015 20:21:16 +0300 Subject: [PATCH] Documentation update --- doc/boards.md | 83 ++++--- doc/changes.md | 2 +- doc/filesystem.md | 253 +++++++++++++++++++ doc/installing.md | 80 ++++++ doc/libraries.md | 153 ++++++++++++ doc/ota_updates/ota_updates.md | 154 ++++++------ doc/reference.md | 408 +------------------------------ doc/reference_items.yml | 15 ++ package/esp8266-arudino-doc.bash | 15 +- 9 files changed, 643 insertions(+), 520 deletions(-) create mode 100644 doc/filesystem.md create mode 100644 doc/installing.md create mode 100644 doc/libraries.md create mode 100644 doc/reference_items.yml diff --git a/doc/boards.md b/doc/boards.md index 9aec334ded..5c3104be66 100644 --- a/doc/boards.md +++ b/doc/boards.md @@ -2,24 +2,36 @@ title: Supported Hardware --- -- [Adafruit HUZZAH ESP8266 (ESP-12)](#adafruit-huzzah-esp8266-esp-12) -- [NodeMCU 0.9](#nodemcu-0-9) -- [NodeMCU 1.0](#nodemcu-1-0) -- [Olimex MOD-WIFI-ESP8266-DEV](#olimex-mod-wifi-esp8266-dev) -- [Olimex MOD-WIFI-ESP8266](#olimex-mod-wifi-esp8266) -- [SparkFun ESP8266 Thing](#sparkfun-esp8266-thing) -- [SweetPea ESP-210](#sweetpea-esp-210) -- [Generic ESP8266 modules](#generic-esp8266-modules) -- [WeMos D1](#wemos-d1) -- [WeMos D1 mini](#wemos-d1-mini) - -### Adafruit HUZZAH ESP8266 (ESP-12) +## Table of contents + * [Adafruit HUZZAH ESP8266 (ESP\-12)](#adafruit-huzzah-esp8266-esp-12) + * [NodeMCU 0\.9 ](#nodemcu-09-) + * [Pin mapping](#pin-mapping) + * [NodeMCU 1\.0](#nodemcu-10) + * [Olimex MOD\-WIFI\-ESP8266\-DEV](#olimex-mod-wifi-esp8266-dev) + * [Olimex MOD\-WIFI\-ESP8266](#olimex-mod-wifi-esp8266) + * [SparkFun ESP8266 Thing](#sparkfun-esp8266-thing) + * [SweetPea ESP\-210](#sweetpea-esp-210) + * [Generic ESP8266 modules](#generic-esp8266-modules) + * [Serial Adapter](#serial-adapter) + * [Minimal Hardware Setup for Bootloading and Usage](#minimal-hardware-setup-for-bootloading-and-usage) + * [ESP to Serial](#esp-to-serial) + * [Minimal Hardware Setup for Bootloading only](#minimal-hardware-setup-for-bootloading-only) + * [Minimal Hardware Setup for Running only](#minimal-hardware-setup-for-running-only) + * [Minimal](#minimal) + * [Improved Stability](#improved-stability) + * [Boot Messages and Modes](#boot-messages-and-modes) + * [rst cause](#rst-cause) + * [boot mode](#boot-mode) + * [WeMos D1](#wemos-d1) + * [WeMos D1 mini](#wemos-d1-mini) + +## Adafruit HUZZAH ESP8266 (ESP-12) *TODO: add notes* -### NodeMCU 0.9 +## NodeMCU 0.9 -#### Pin mapping +### Pin mapping Pin numbers written on the board itself do not correspond to ESP8266 GPIO pin numbers. Constants are defined to make using this board easier: @@ -39,7 +51,7 @@ static const uint8_t D10 = 1; If you want to use NodeMCU pin 5, use D5 for pin number, and it will be translated to 'real' GPIO pin 14. -### NodeMCU 1.0 +## NodeMCU 1.0 This module is sold under many names for around $6.50 on AliExpress and it's one of the cheapest, fully integrated ESP8266 solutions. @@ -51,7 +63,7 @@ The board also features a NCP1117 voltage regulator, a blue LED on GPIO16 and a Full pinout and PDF schematics can be found [here](https://github.com/nodemcu/nodemcu-devkit-v1.0) -### Olimex MOD-WIFI-ESP8266-DEV +## Olimex MOD-WIFI-ESP8266-DEV This board comes with 2 MB of SPI flash and optional accessories (e.g. evaluation board ESP8266-EVB or BAT-BOX for batteries). @@ -65,21 +77,21 @@ UART pins for programming and serial I/O are GPIO1 (TXD, pin 3) and GPIO3 (RXD, Get the board schematics [here](https://github.com/OLIMEX/ESP8266/blob/master/HARDWARE/MOD-WIFI-ESP8266-DEV/MOD-WIFI-ESP8266-DEV_schematic.pdf) -### Olimex MOD-WIFI-ESP8266 +## Olimex MOD-WIFI-ESP8266 This is a stripped down version of the above. Behaves identically in terms of jumpers but has less pins readily available for I/O. Still 2 MB of SPI flash. -### SparkFun ESP8266 Thing ### +## SparkFun ESP8266 Thing ### Product page: https://www.sparkfun.com/products/13231 *TODO: add notes* -### SweetPea ESP-210 +## SweetPea ESP-210 *TODO: add notes* -### Generic ESP8266 modules +## Generic ESP8266 modules These modules come in different form factors and pinouts. See the page at ESP8266 community wiki for more info: [ESP8266 Module Family](http://www.esp8266.com/wiki/doku.php?id=esp8266-module-family). @@ -94,10 +106,10 @@ In order to use these modules, make sure to observe the following: - **Put ESP8266 into bootloader mode** before uploading code. -### Serial Adapter +## Serial Adapter There are many different USB to Serial adapters / boards. -To be able to put ESP8266 into bootloader mode using serial handshaking lines, you need the adapter which breaks out RTS and DTR outputs. CTS and DSR are not useful for upload (they are inputs). Make sure the adapter can work with 3.3V IO voltage: it should have a jumper or a switch to select between 5V and 3.3V, or be marked as 3.3V only. +To be able to put ESP8266 into bootloader mode using serial handshaking lines, you need the adapter which breaks out RTS and DTR outputs. CTS and DSR are not useful for upload (they are inputs). Make sure the adapter can work with 3.3V IO voltage: it should have a jumper or a switch to select between 5V and 3.3V, or be marked as 3.3V only. Adapters based around the following ICs should work: @@ -107,7 +119,7 @@ Adapters based around the following ICs should work: PL2303-based adapters are known not to work on Mac OS X. See https://github.com/igrr/esptool-ck/issues/9 for more info. -### Minimal Hardware Setup for Bootloading and Usage +## Minimal Hardware Setup for Bootloading and Usage | PIN | Resistor | Serial Adapter | @@ -127,10 +139,10 @@ PL2303-based adapters are known not to work on Mac OS X. See https://github.com/ - GPIO2 is alternative TX for the boot loader mode - **Directly connecting a pin to VCC or GND is not a substitute for a PullUp or PullDown resistor, doing this can break upload management and the serial console, instability has also been noted in some cases.** -### ESP to Serial +## ESP to Serial ![ESP to Serial](ESP_to_serial.png) -#### Minimal Hardware Setup for Bootloading only ## +### Minimal Hardware Setup for Bootloading only ## ESPxx Hardware | PIN | Resistor | Serial Adapter | @@ -147,7 +159,7 @@ ESPxx Hardware * Note - if no RTS is used a manual power toggle is needed -#### Minimal Hardware Setup for Running only ## +### Minimal Hardware Setup for Running only ## ESPxx Hardware @@ -159,13 +171,13 @@ ESPxx Hardware | GPIO15 | PullDown | | | CH_PD | PullUp | | -### Minimal +## Minimal ![ESP min](ESP_min.png) -### Improved Stability +## Improved Stability ![ESP improved stability](ESP_improved_stability.png) -### Boot Messages and Modes +## Boot Messages and Modes The ESP module checks at every boot the Pins 0, 2 and 15. based on them its boots in different modes: @@ -182,10 +194,10 @@ at startup the ESP prints out the current boot mode example: rst cause:2, boot mode:(3,6) ``` -note: +note: - GPIO2 is used as TX output and the internal Pullup is enabled on boot. -#### rst cause +### rst cause | Number | Description | | ------ | ---------------------- | @@ -193,10 +205,10 @@ note: | 1 | normal boot | | 2 | reset pin | | 3 | software reset | -| 4 | watchdog reset | +| 4 | watchdog reset | -#### boot mode +### boot mode the first value respects the pin setup of the Pins 0, 2 and 15. @@ -214,7 +226,8 @@ the first value respects the pin setup of the Pins 0, 2 and 15. note: - number = ((GPIO15 << 2) | (GPIO0 << 1) | GPIO2); -### WeMos D1 +## WeMos D1 Product page: http://wemos.cc -### WeMos D1 mini + +## WeMos D1 mini Product page: http://wemos.cc diff --git a/doc/changes.md b/doc/changes.md index bed3d0da68..b9b440c919 100644 --- a/doc/changes.md +++ b/doc/changes.md @@ -1,5 +1,5 @@ --- -title: Change log +title: Change Log --- *Current release* diff --git a/doc/filesystem.md b/doc/filesystem.md new file mode 100644 index 0000000000..31aa148abb --- /dev/null +++ b/doc/filesystem.md @@ -0,0 +1,253 @@ +--- +title: File System +--- + +## Table of Contents + * [Flash layout](#flash-layout) + * [Uploading files to file system](#uploading-files-to-file-system) + * [File system object (SPIFFS)](#file-system-object-spiffs) + * [begin](#begin) + * [format](#format) + * [open](#open) + * [exists](#exists) + * [openDir](#opendir) + * [remove](#remove) + * [rename](#rename) + * [info](#info) + * [Filesystem information structure](#filesystem-information-structure) + * [Directory object (Dir)](#directory-object-dir) + * [File object](#file-object) + * [seek](#seek) + * [position](#position) + * [size](#size) + * [name](#name) + * [close](#close) + + +## Flash layout + +Even though file system is stored on the same flash chip as the program, programming new sketch will not modify file system contents. This allows to use file system to store sketch data, configuration files, or content for Web server. + +The following diagram illustrates flash layout used in Arduino environment: + + |--------------|-------|---------------|--|--|--|--|--| + ^ ^ ^ ^ ^ + Sketch OTA update File system EEPROM WiFi config (SDK) + +File system size depends on the flash chip size. Depending on the board which is selected in IDE, you have the following options for flash size: + +Board | Flash chip size, bytes | File system size, bytes +------|-----------------|----------------- +Generic module | 512k | 64k +Generic module | 1M | 64k, 128k, 256k, 512k +Generic module | 2M | 1M +Generic module | 4M | 3M +Adafruit HUZZAH | 4M | 1M, 3M +NodeMCU 0.9 | 4M | 1M, 3M +NodeMCU 1.0 | 4M | 1M, 3M +Olimex MOD-WIFI-ESP8266(-DEV)| 2M | 1M +SparkFun Thing | 512k | 64k +SweetPea ESP-210 | 4M | 1M, 3M +WeMos D1 & D1 mini | 4M | 1M, 3M + +**Note:** to use any of file system functions in the sketch, add the following include to the sketch: + +```c++ +#include "FS.h" +``` + +## Uploading files to file system + +*ESP8266FS* is a tool which integrates into the Arduino IDE. It adds a menu item to *Tools* menu for uploading the contents of sketch data directory into ESP8266 flash file system. + +- Download the tool: https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.1.3/ESP8266FS-0.1.3.zip. +- In your Arduino sketchbook directory, create `tools` directory if it doesn't exist yet +- Unpack the tool into `tools` directory (the path will look like `/Arduino/tools/ESP8266FS/tool/esp8266fs.jar`) +- Restart Arduino IDE +- Open a sketch (or create a new one and save it) +- Go to sketch directory (choose Sketch > Show Sketch Folder) +- Create a directory named `data` and any files you want in the file system there +- Make sure you have selected a board, port, and closed Serial Monitor +- Select Tools > ESP8266 Sketch Data Upload. This should start uploading the files into ESP8266 flash file system. When done, IDE status bar will display `SPIFFS Image Uploaded` message. + + +## File system object (SPIFFS) + +### begin + +```c++ +SPIFFS.begin() +``` + +This method mounts SPIFFS file system. It must be called before any other +FS APIs are used. Returns *true* if file system was mounted successfully, false +otherwise. + +### format + +```c++ +SPIFFS.format() +``` + +Formats the file system. May be called either before or after calling `begin`. +Returns *true* if formatting was successful. + +### open + +```c++ +SPIFFS.open(path, mode) +``` + +Opens a file. `path` should be an absolute path starting with a slash +(e.g. `/dir/filename.txt`). `mode` is a string specifying access mode. It can be +one of "r", "w", "a", "r+", "w+", "a+". Meaning of these modes is the same as +for `fopen` C function. + +Returns *File* object. To check whether the file was opened successfully, use +the boolean operator. + +```c++ +File f = SPIFFS.open("/f.txt", "w"); +if (!f) { + Serial.println("file open failed"); +} +``` + +### exists + +```c++ +SPIFFS.exists(path) +``` + +Returns *true* if a file with given path exists, *false* otherwise. + +### openDir + +```c++ +SPIFFS.openDir(path) +``` + +Opens a directory given its absolute path. Returns a *Dir* object. To check if +directory was opened successfully, use the boolean operator, similar to opening +a file. + +### remove + +```c++ +SPIFFS.remove(path) +``` + +Deletes the file given its absolute path. Returns *true* if file was deleted successfully. + +### rename + +```c++ +SPIFFS.rename(pathFrom, pathTo) +``` + +Renames file from `pathFrom` to `pathTo`. Paths must be absolute. Returns *true* +if file was renamed successfully. + +### info + +```c++ +FSInfo fs_info; +SPIFFS.info(fs_info); +``` + +Fills [FSInfo structure](#filesystem-information-structure) with information about +the file system. Returns `true` is successful, `false` otherwise. + +## Filesystem information structure + +```c++ +struct FSInfo { + size_t totalBytes; + size_t usedBytes; + size_t blockSize; + size_t pageSize; + size_t maxOpenFiles; + size_t maxPathLength; +}; +``` + +This is the structure which may be filled using FS::info method. Field names +are self-explanatory. + +## Directory object (Dir) + +The purpose of *Dir* object is to iterate over files inside a directory. +It provides three methods: `next()`, `fileName()`, and `openFile(mode)`. + +The following example shows how it should be used: + +```c++ +Dir dir = SPIFFS.openDir("/data"); +while (dir.next()) { + Serial.print(dir.fileName()); + File f = dir.openFile("r"); + Serial.println(f.size()); +} +``` + +`dir.next()` returns true while there are files in the directory to iterate over. +It must be called before calling `fileName` and `openFile` functions. + +`openFile` method takes *mode* argument which has the same meaning as for `SPIFFS.open` function. + +## File object + +`SPIFFS.open` and `dir.openFile` functions return a *File* object. This object +supports all the functions of *Stream*, so you can use `readBytes`, `findUntil`, +`parseInt`, `println`, and all other *Stream* methods. + +There are also some functions which are specific to *File* object. + +### seek + +```c++ +file.seek(offset, mode) +``` + +This function behaves like `fseek` C function. Depending on the value of `mode`, +it moves current position in a file as follows: + +- if `mode` is `SeekSet`, position is set to `offset` bytes from the beginning. +- if `mode` is `SeekCur`, current position is moved by `offset` bytes. +- if `mode` is `SeekEnd`, position is set to `offset` bytes from the end of the +file. + +Returns *true* if position was set successfully. + +### position + +```c++ +file.position() +``` + +Returns the current position inside the file, in bytes. + +### size + +```c++ +file.size() +``` + +Returns file size, in bytes. + + +### name + +```c++ +String name = file.name(); +``` + +Returns file name, as `const char*`. Convert it to *String* for storage. + +### close + +```c++ +file.close() +``` + +Close the file. No other operations should be performed on *File* object after `close` function was called. diff --git a/doc/installing.md b/doc/installing.md new file mode 100644 index 0000000000..16ba27a002 --- /dev/null +++ b/doc/installing.md @@ -0,0 +1,80 @@ +--- +title: Installation +--- + +## Boards Manager ## + +This is the suggested installation method for end users. + +### Prerequisites +- Arduino 1.6.5, get it from [Arduino website](https://www.arduino.cc/en/Main/OldSoftwareReleases#previous). Arduino 1.6.6 has several issues, so we recommend to stick with 1.6.5 for now. +- Internet connection + +### Instructions +- Start Arduino and open Preferences window. +- Enter ```http://arduino.esp8266.com/stable/package_esp8266com_index.json``` into *Additional Board Manager URLs* field. You can add multiple URLs, separating them with commas. +- Open Boards Manager from Tools > Board menu and find *esp8266* platform. +- Select the version you need from a drop-down box. +- Click *install* button. +- Don't forget to select your ESP8266 board from Tools > Board menu after installation. + +You may optionally use *staging* boards manager package link: +`http://arduino.esp8266.com/staging/package_esp8266com_index.json`. This may contain some new features, but at the same time, some things might be broken. + +## Using git version + +This is the suggested installation method for contributors and library developers. + +### Prerequisites + +- Arduino 1.6.5 (or newer, if you know what you are doing) +- git +- python 2.7 +- terminal, console, or command prompt (depending on you OS) +- Internet connection + +### Instructions + +- Open the console and go to Arduino directory. This can be either your *sketchbook* directory (usually `/Arduino`), or the directory of Arduino application itself, the choice is up to you. +- Clone this repository into hardware/esp8266com/esp8266 directory. Alternatively, clone it elsewhere and create a symlink, if your OS supports them. + + ```bash + cd hardware + mkdir esp8266com + cd esp8266com + git clone https://github.com/esp8266/Arduino.git esp8266 + ``` + You should end up with the following directory structure: + + ```bash + Arduino + | + --- hardware + | + --- esp8266com + | + --- esp8266 + | + --- bootloaders + --- cores + --- doc + --- libraries + --- package + --- tests + --- tools + --- variants + --- platform.txt + --- programmers.txt + --- README.md + --- boards.txt + --- LICENSE + ``` + +- Download binary tools + + ```bash + cd esp8266/tools + python get.py + ``` + +- Restart Arduino diff --git a/doc/libraries.md b/doc/libraries.md new file mode 100644 index 0000000000..210ef2f81e --- /dev/null +++ b/doc/libraries.md @@ -0,0 +1,153 @@ +--- +title: Libraries +--- + +## Table of Contents + * [WiFi(ESP8266WiFi library)](#wifiesp8266wifi-library) + * [Ticker](#ticker) + * [EEPROM](#eeprom) + * [I2C (Wire library)](#i2c-wire-library) + * [SPI](#spi) + * [SoftwareSerial](#softwareserial) + * [ESP\-specific APIs](#esp-specific-apis) + * [OneWire](#onewire) + * [mDNS and DNS\-SD responder (ESP8266mDNS library)](#mdns-and-dns-sd-responder-esp8266mdns-library) + * [SSDP responder (ESP8266SSDP)](#ssdp-responder-esp8266ssdp) + * [DNS server (DNSServer library)](#dns-server-dnsserver-library) + * [Servo](#servo) + * [Other libraries (not included with the IDE)](#other-libraries-not-included-with-the-ide) + +## WiFi(ESP8266WiFi library) + +This is mostly similar to WiFi shield library. Differences include: + +- `WiFi.mode(m)`: set mode to `WIFI_AP`, `WIFI_STA`, `WIFI_AP_STA` or `WIFI_OFF`. +- call `WiFi.softAP(ssid)` to set up an open network +- call `WiFi.softAP(ssid, password)` to set up a WPA2-PSK network (password should be at least 8 characters) +- `WiFi.macAddress(mac)` is for STA, `WiFi.softAPmacAddress(mac)` is for AP. +- `WiFi.localIP()` is for STA, `WiFi.softAPIP()` is for AP. +- `WiFi.printDiag(Serial)` will print out some diagnostic info +- `WiFiUDP` class supports sending and receiving multicast packets on STA interface. +When sending a multicast packet, replace `udp.beginPacket(addr, port)` with +`udp.beginPacketMulticast(addr, port, WiFi.localIP())`. +When listening to multicast packets, replace `udp.begin(port)` with +`udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)`. +You can use `udp.destinationIP()` to tell whether the packet received was +sent to the multicast or unicast address. + +`WiFiServer`, `WiFiClient`, and `WiFiUDP` behave mostly the same way as with WiFi shield library. +Four samples are provided for this library. +You can see more commands here: [http://www.arduino.cc/en/Reference/WiFi](http://www.arduino.cc/en/Reference/WiFi) + +## Ticker + +Library for calling functions repeatedly with a certain period. Two examples included. + +It is currently not recommended to do blocking IO operations (network, serial, file) from Ticker +callback functions. Instead, set a flag inside the ticker callback and check for that flag inside the loop function. + +## EEPROM + +This is a bit different from standard EEPROM class. You need to call `EEPROM.begin(size)` +before you start reading or writing, size being the number of bytes you want to use. +Size can be anywhere between 4 and 4096 bytes. + +`EEPROM.write` does not write to flash immediately, instead you must call `EEPROM.commit()` +whenever you wish to save changes to flash. `EEPROM.end()` will also commit, and will +release the RAM copy of EEPROM contents. + +EEPROM library uses one sector of flash located just after the SPIFFS. + +Three examples included. + +## I2C (Wire library) + +Wire library currently supports master mode up to approximately 450KHz. +Before using I2C, pins for SDA and SCL need to be set by calling +`Wire.begin(int sda, int scl)`, i.e. `Wire.begin(0, 2)` on ESP-01, +else they default to pins 4(SDA) and 5(SCL). + +## SPI + +SPI library supports the entire Arduino SPI API including transactions, including setting phase (CPHA). +Setting the Clock polarity (CPOL) is not supported, yet (SPI_MODE2 and SPI_MODE3 not working). + +## SoftwareSerial + +An ESP8266 port of SoftwareSerial library done by Peter Lerup (@plerup) supports baud rate up to 115200 and multiples SoftwareSerial instances. See https://github.com/plerup/espsoftwareserial if you want to suggest an improvement or open an issue related to SoftwareSerial. + +## ESP-specific APIs + +APIs related to deep sleep and watchdog timer are available in the `ESP` object, only available in Alpha version. + +`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.) + +`ESP.restart()` restarts the CPU. + +`ESP.getFreeHeap()` returns the free heap size. + +`ESP.getChipId()` returns the ESP8266 chip ID as a 32-bit integer. + +Several APIs may be used to get flash chip info: + +`ESP.getFlashChipId()` returns the flash chip ID as a 32-bit integer. + +`ESP.getFlashChipSize()` returns the flash chip size, in bytes, as seen by the SDK (may be less than actual size). + +`ESP.getFlashChipSpeed(void)` returns the flash chip frequency, in Hz. + +`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. + +`ESP.getVcc()` may be used to measure supply voltage. ESP needs to reconfigure the ADC +at startup in order for this feature to be available. Add the following line to the top +of your sketch to use `getVcc`: + +```c++ +ADC_MODE(ADC_VCC); +``` + +TOUT pin has to be disconnected in this mode. + +Note that by default ADC is configured to read from TOUT pin using `analogRead(A0)`, and +`ESP.getVCC()` is not available. + +## OneWire + +Library was adapted to work with ESP8266 by including register definitions into OneWire.h +Note that if you already have OneWire library in your Arduino/libraries folder, it will be used +instead of the one that comes with this package. + +## mDNS and DNS-SD responder (ESP8266mDNS library) + +Allows the sketch to respond to multicast DNS queries for domain names like "foo.local", and DNS-SD (service dicovery) queries. +See attached example for details. + +## SSDP responder (ESP8266SSDP) + +SSDP is another service discovery protocol, supported on Windows out of the box. See attached example for reference. + +## DNS server (DNSServer library) + +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. +See attached example for details. + +## Servo + +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. +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. + +## Other libraries (not included with the IDE) + +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: + +- [arduinoWebSockets](https://github.com/Links2004/arduinoWebSockets) - WebSocket Server and Client compatible with ESP8266 (RFC6455) +- [aREST](https://github.com/marcoschwartz/aREST) REST API handler library. +- [Blynk](https://github.com/blynkkk/blynk-library) - easy IoT framework for Makers (check out the [Kickstarter page](http://tiny.cc/blynk-kick)). +- [DallasTemperature](https://github.com/milesburton/Arduino-Temperature-Control-Library.git) +- [DHT-sensor-library](https://github.com/adafruit/DHT-sensor-library) - Arduino library for the DHT11/DHT22 temperature and humidity sensors. Download latest v1.1.1 library and no changes are necessary. Older versions should initialize DHT as follows: `DHT dht(DHTPIN, DHTTYPE, 15)` +- [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). +- [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. +- [PubSubClient](https://github.com/Imroy/pubsubclient) MQTT library by @Imroy. +- [RTC](https://github.com/Makuna/Rtc) - Arduino Library for Ds1307 & Ds3231 compatible with ESP8266. +- [Souliss, Smart Home](https://github.com/souliss/souliss) - Framework for Smart Home based on Arduino, Android and openHAB. +- [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. diff --git a/doc/ota_updates/ota_updates.md b/doc/ota_updates/ota_updates.md index bac75e9ec1..b7963a1147 100644 --- a/doc/ota_updates/ota_updates.md +++ b/doc/ota_updates/ota_updates.md @@ -3,22 +3,29 @@ title: OTA Update --- ## Table of Contents -* [Introduction](#introduction) - * [Security](#security) - * [Safety](#safety) - * [Basic Requirements](#basic-requirements) -* [Arduino IDE](#arduino-ide) - * [Requirements](#requirements) - * [Application Example](#application-example) - * [Classic OTA](#classic-ota) - * [ArduinoOTA](#arduinoota) -* [Web Browser](#web-browser) - * [Requirements](#requirements-1) - * [Implementation Overview](#implementation-overview) - * [Application Example](#application-example-1) -* [HTTP Server](#http-server) -* [Stream Interface](#stream-interface) -* [Updater class](#updater-class) + * [Introduction](#introduction) + * [Security](#security) + * [Safety](#safety) + * [Basic Requirements](#basic-requirements) + * [Arduino IDE](#arduino-ide) + * [Requirements](#requirements) + * [Application Example](#application-example) + * [Classic OTA](#classic-ota) + * [ArduinoOTA](#arduinoota) + * [Web Browser](#web-browser) + * [Requirements](#requirements-1) + * [Implementation Overview](#implementation-overview) + * [Application Example](#application-example-1) + * [HTTP Server](#http-server) + * [Requirements](#requirements-2) + * [Arduino code](#arduino-code) + * [Simple updater](#simple-updater) + * [Advanced updater](#advanced-updater) + * [Server request handling](#server-request-handling) + * [Simple updater](#simple-updater-1) + * [Advanced updater](#advanced-updater-1) + * [Stream Interface](#stream-interface) + * [Updater class](#updater-class) ## Introduction @@ -26,11 +33,12 @@ title: OTA Update OTA (Over the Air) update is the process of loading the firmware to ESP module using Wi-Fi connection rather that a serial port. Such functionality became extremely useful in case of limited or no physical access to the module. OTA may be done using: + * [Arduino IDE](#arduino-ide) * [Web Browser](#web-browser) * [HTTP Server](#http-server) -Arduino IDE option is intended primarily for software development phase. The two other options would be more useful after deployment, to provide module with application updates manually with a web browser or automatically using a http server. +Arduino IDE option is intended primarily for software development phase. The two other options would be more useful after deployment, to provide module with application updates manually with a web browser or automatically using a http server. In any case first firmware upload have to be done over a serial port. If OTA routines are correctly implemented in a sketch, then all subsequent uploads may be done over the air. @@ -39,14 +47,16 @@ There is no imposed security on OTA process from being hacked. It is up to devel ### Security -Module has to be exposed wirelessly to get it updated with a new sketch. That poses chances of module being violently hacked and loaded with some other code. To reduce likelihood of being hacked consider protecting your uploads with a password, selecting certain OTA port, etc. +Module has to be exposed wirelessly to get it updated with a new sketch. That poses chances of module being violently hacked and loaded with some other code. To reduce likelihood of being hacked consider protecting your uploads with a password, selecting certain OTA port, etc. Check functionality provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library that may improve security: + ```cpp void setPort(uint16_t port); -void setHostname(const char *hostname); -void setPassword(const char *password); +void setHostname(const char* hostname); +void setPassword(const char* password); ``` + Certain protection functionality is already built in and do not require any additional coding by developer. [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) and espota.py use [Digest-MD5](https://en.wikipedia.org/wiki/Digest_access_authentication) to authenticate upload. Integrity of transferred data is verified on ESP side using [MD5](https://en.wikipedia.org/wiki/MD5) checksum. Make your own risk analysis and depending on application decide what library functions to implement. If required consider implementation of other means of protection from being hacked, e.g. exposing module for uploads only according to specific schedule, trigger OTA only be user pressing dedicated “Update” button, etc. @@ -54,11 +64,12 @@ Make your own risk analysis and depending on application decide what library fun ### Safety -OTA process takes ESP’s resources and bandwidth during upload. Then module is restarted and a new sketch executed. Analyse and test how it affects functionality of your existing and new sketch. +OTA process takes ESP’s resources and bandwidth during upload. Then module is restarted and a new sketch executed. Analyse and test how it affects functionality of your existing and new sketch. If ESP is placed in remote location and controlling some equipment, you should put additional attention what happens if operation of this equipment is suddenly interrupted by update process. Therefore decide how to put this equipment into safe state before starting the update. For instance your module may be controlling a garden watering system in a sequence. If this sequence is not properly shut down and a water valve left open, your garden may be flooded if this valve is not closed after OTA is finished and module restarts. -The following functions are provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library and intended to handle functionality of your application during specific stages of OTA on or on an OTA error: +The following functions are provided with [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library and intended to handle functionality of your application during specific stages of OTA or on an OTA error: + ```cpp void onStart(OTA_CALLBACK(fn)); void onEnd(OTA_CALLBACK(fn)); @@ -88,8 +99,10 @@ Uploading modules wirelessly from Arduino IDE is intended for the following typi ### Application Example -Currently there are two software configurations that support OTA updates -- [Classic OTA](#classic-ota-configuration): Arduino IDE 1.6.5 and 1.6.5-947-g39819f0 (of July 23, 2015) or 1.6.5-1160-gef26c5f (of Sep 30, 2015) version of platform package that provides first OTA implementation, yet without support for [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library. This particular configuration is easier to configure in Arduino IDE and therefore suggested for less experienced users. It soon will be depreciated once implementation below is fully released. +Currently there are two software configurations that support OTA updates. + +- [Classic OTA](#classic-ota-configuration): Arduino IDE 1.6.5 and 1.6.5-947-g39819f0 (of July 23, 2015) or 1.6.5-1160-gef26c5f (of Sep 30, 2015) version of platform package that provides first OTA implementation, yet without support for [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library. This particular configuration is easier to configure in Arduino IDE and therefore suggested for less experienced users. It soon will be depreciated once implementation below is fully released. + - [ArduinoOTA](#arduinoota-configuration): Arduino-PR-4107-BUILD-421 and latest git version of platform package that includes [ArduinoOTA](https://github.com/esp8266/Arduino/tree/master/libraries/ArduinoOTA) library. This configuration features preliminary build of Arduino IDE and is intended for more experienced users. Please mid your step. Instructions below demonstrate how to configure both [Classic OTA](#classic-ota-configuration) and [ArduinoOTA](#arduinoota-configuration) using NodeMCU 1.0 (ESP-12E Module) board. @@ -98,46 +111,39 @@ Instructions below demonstrate how to configure both [Classic OTA](#classic-ota- #### Classic OTA 1. Before you begin, please make sure that you have the following installed: - - Arduino IDE and ESP8266 board support as described under https://github.com/esp8266/Arduino#installing-with-boards-manager - - [Python](https://www.python.org/) 2.7 (do not install Python 3.5 that is not supported): + - Arduino IDE and ESP8266 board support as described under https://github.com/esp8266/Arduino#installing-with-boards-manager + - [Python](https://www.python.org/) 2.7 (do not install Python 3.5 that is not supported): - **Note:** Windows users should select “Add python.exe to Path” (see below – this option is not selected by default). + **Note:** Windows users should select “Add python.exe to Path” (see below – this option is not selected by default). - ![Python installation set up](ota-ide-python-configuration.png) + ![Python installation set up](ota-ide-python-configuration.png) 2. Now prepare the sketch and configuration for the upload over a serial port. + - Start Arduino IDE and load sketch DNS_SD_Arduino_OTA.ino available under File > Examples > ESP8266mDNS + ![OTA sketch selection](ota-ide-sketch-selection.png) + **Note:** This sketch is available only for 1.6.5-947-g39819f0 (of July 23, 2015) and 1.6.5-1160-gef26c5f (of Sep 30, 2015) versions of platform packages installed in Arduino IDE using https://github.com/esp8266/Arduino#installing-with-boards-manager. It was removed in [#980](https://github.com/esp8266/Arduino/pull/980) from GitHub repository. + - Update ssid and pass in the sketch so the module can join your Wi-Fi network + ![ssid and pass entry](ota-ide-ssid-pass-entry.png) + - Configure upload parameters as below (you may need to adjust configuration if you are using a different module): + ![configuration of serial upload](ota-ide-serial-upload-configuration.png) - - Start Arduino IDE and load sketch DNS_SD_Arduino_OTA.ino available under File > Examples > ESP8266mDNS - - ![OTA sketch selection](ota-ide-sketch-selection.png) - - **Note:** This sketch is available only for 1.6.5-947-g39819f0 (of July 23, 2015) and 1.6.5-1160-gef26c5f (of Sep 30, 2015) versions of platform packages installed in Arduino IDE using https://github.com/esp8266/Arduino#installing-with-boards-manager. It was removed in [#980](https://github.com/esp8266/Arduino/pull/980) from GitHub repository. - - - Update ssid and pass in the sketch so the module can join your Wi-Fi network - - ![ssid and pass entry](ota-ide-ssid-pass-entry.png) +3. Upload the sketch (Ctrl+U). Once done open Serial Monitor (Ctrl+Shift+M) and check if module has joined your Wi-Fi network. - - Configure upload parameters as below (you may need to adjust configuration if you are using a different module): - - ![configuration of serial upload](ota-ide-serial-upload-configuration.png) - -3. Upload the sketch (Ctrl+U). Once done open Serial Monitor (Ctrl+Shift+M) and check if module has joined your Wi-Fi network. - - ![check if module joined network](ota-ide-module-joined-wifi.png) + ![check if module joined network](ota-ide-module-joined-wifi.png) 4. Only if module is connected to network, after a couple of seconds, the esp8266-ota port will show up in Arduino IDE: - ![selection og OTA port](ota-ide-ota-port-selection.png) + ![selection og OTA port](ota-ide-ota-port-selection.png) 5. Now get ready for your first OTA upload by changing configuration settings as follows: - ![configuration of OTA upload](ota-ide-ota-upload-configuration.png) + ![configuration of OTA upload](ota-ide-ota-upload-configuration.png) - **Note:** If you do not see “Upload Using: OTA” option available for “NodeMCU 1.0 (ESP-12E Module)” board, please upload the latest [boards.txt](https://github.com/esp8266/Arduino/blob/master/boards.txt) file from GitHub repository, replace existing file and restart Arduino IDE. + **Note:** If you do not see “Upload Using: OTA” option available for “NodeMCU 1.0 (ESP-12E Module)” board, please upload the latest [boards.txt](https://github.com/esp8266/Arduino/blob/master/boards.txt) file from GitHub repository, replace existing file and restart Arduino IDE. 6. If you have successfully completed all the above steps, you can upload (Ctrl+U) the same (or any other) sketch over OTA: - ![OTA upload complete](ota-ide-ota-upload-complete.png) + ![OTA upload complete](ota-ide-ota-upload-complete.png) **Note** To be able to upload your sketch over and over again using OTA, you need to embed OTA routines inside. Please use DNS_SD_Arduino_OTA.ino as an example. @@ -157,6 +163,7 @@ Instructions below demonstrate how to configure both [Classic OTA](#classic-ota- ## Web Browser Updates described in this chapter are done with a web browser that can be useful in the following typical scenarios: + - after application deployment if loading directly from Arduino IDE is inconvenient or not possible - after deployment if user is unable to expose module for OTA from external update server - to provide updates after deployment to small quantity of modules when setting an update server is not practicable @@ -200,46 +207,39 @@ You can use another module if it meets “Flash chip size is 2x the size of the 1. Before you begin, please make sure that you have the following software installed: - - - Arduino IDE and 2.0.0-rc1 (of Nov 17, 2015) version of platform package as described under https://github.com/esp8266/Arduino#installing-with-boards-manager - - Host software depending on O/S you use: - 1. Avahi http://avahi.org/ for Linux - 2. Bonjour http://www.apple.com/support/bonjour/ for Windows - 3. Mac OSX and iOS - support is already built in / no any extra s/w is required + - Arduino IDE and 2.0.0-rc1 (of Nov 17, 2015) version of platform package as described under https://github.com/esp8266/Arduino#installing-with-boards-manager + - Host software depending on O/S you use: + 1. Avahi http://avahi.org/ for Linux + 2. Bonjour http://www.apple.com/support/bonjour/ for Windows + 3. Mac OSX and iOS - support is already built in / no any extra s/w is required 2. Prepare the sketch and configuration for initial upload with a serial port. - - Start Arduino IDE and load sketch WebUpdater.ino available under File > Examples > ESP8266HTTPUpdateServer. - - Update ssid and pass in the sketch so the module can join your Wi-Fi network. - - Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option. - - ![Preferences - enablig verbose output during compilation](ota-web-show-verbose-compilation.png) - - **Note:** This setting will be required in step 5 below. You can uncheck this setting it afterwards. + - Start Arduino IDE and load sketch WebUpdater.ino available under File > Examples > ESP8266HTTPUpdateServer. + - Update ssid and pass in the sketch so the module can join your Wi-Fi network. + - Open File > Preferences, look for “Show verbose output during:” and check out “compilation” option. + ![Preferences - enablig verbose output during compilation](ota-web-show-verbose-compilation.png) + **Note:** This setting will be required in step 5 below. You can uncheck this setting afterwards. -3. Upload sketch (Ctrl+U). Once done open Serial Monitor (Ctrl+Shift+M) and check if you see the following message displayed, that contains url for OTA update. - - ![Serial Monitor - after first load using serial](ota-web-serial-monitor-ready.png) - - **Note:** Such message will be shown only after module successfully joins network and is ready for an OTA upload: +3. Upload sketch (Ctrl+U). Once done open Serial Monitor (Ctrl+Shift+M) and check if you see the following message displayed, that contains url for OTA update. + ![Serial Monitor - after first load using serial](ota-web-serial-monitor-ready.png) + **Note:** Such message will be shown only after module successfully joins network and is ready for an OTA upload: 4. Now open web browser and enter the url provided on Serial Monitor, i.e. http://esp8266-webupdate.local/update. Once entered, browser should display a form like below that has been served by your module. The form invites you to choose a file for update. + ![OTA update form in web browser](ota-web-browser-form.png) + **Note:** If entering “http://esp8266-webupdate.local/update” does not work, try replacing “esp8266-webupdate” with module’s IP address. For example, if your module IP is “192.168.1.100” then url should be “http://192.168.1.100/update”. This workaround is useful in case the host software installed in step 2 does not work. If still nothing works and there are no clues on Serial Monitor, try to diagnose issue by opening provided url in Google Chrome, pressing F12 and checking contents of “Console” and “Network” tabs. Chrome provides some advanced logging on these tabs. - ![OTA update form in web browser](ota-web-browser-form.png) - - **Note:** If entering “http://esp8266-webupdate.local/update” does not work, try replacing “esp8266-webupdate” with module’s IP address. For example, if your module IP is “192.168.1.100” then url should be “http://192.168.1.100/update”. This workaround is useful in case the host software installed in step 2 does not work. If still nothing works and there are no clues on Serial Monitor, try to diagnose issue by opening provided url in Google Chrome, pressing F12 and checking contents of “Console” and “Network” tabs. Chrome provides some advanced logging on these tabs. +5. To obtain the file navigate to directory used by Arduino IDE to store results of compilation. You can check the path to this file in compilation log shown in IDE debug window as marked below. -5. To obtain the file navigate to directory used by Arduino IDE to store results of compilation. You can check the path to this file in compilation log shown in IDE debug window as marked below. - - ![Compilation complete - path to binary file](ota-web-path-to-binary.png) + ![Compilation complete - path to binary file](ota-web-path-to-binary.png) 6. Now press “Choose File” in web browser, go to directory identified in step 5 above, find the file “WebUpdater.cpp.bin” and upload it. If upload is successful you will see “OK” on web browser like below. - ![OTA update complete](ota-web-browser-form-ok.png) + ![OTA update complete](ota-web-browser-form-ok.png) - Module will reboot that should be visible on Serial Monitor: + Module will reboot that should be visible on Serial Monitor: - ![Serial Monitor - after OTA update](ota-web-serial-monitor-reboot.png) + ![Serial Monitor - after OTA update](ota-web-serial-monitor-reboot.png) Just after reboot you should see exactly the same message “HTTPUpdateServer ready! Open http:// esp8266-webupdate.local /update in your browser” like in step 3. This is because module has been loaded again with the same code – first using serial port, and then using OTA. @@ -319,6 +319,7 @@ Example header data: With this information the script now can check if a update is needed. It is also possible to deliver different binaries based on the MAC address for example. Script example: + ```php https://www.pjrc.com/teensy/td_libs_OneWire.html)](#onewire-from-httpswwwpjrccomteensytd_libs_onewirehtml) - * [mDNS and DNS-SD responder (ESP8266mDNS library)](#mdns-and-dns-sd-responder-esp8266mdns-library) - * [SSDP responder (ESP8266SSDP)](#ssdp-responder-esp8266ssdp) - * [DNS server (DNSServer library)](#dns-server-dnsserver-library) - * [Servo](#servo) - * [Other libraries (not included with the IDE)](#other-libraries-not-included-with-the-ide) - -Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc) + * [Table of Contents](#table-of-contents) + * [Digital IO](#digital-io) + * [Analog input](#analog-input) + * [Analog output](#analog-output) + * [Timing and delays](#timing-and-delays) + * [Serial](#serial) + * [Progmem](#progmem) ## Digital IO @@ -142,366 +111,3 @@ const char HTTP[] PROGMEM = "http:"; response2 += FPSTR(HTTP); } ``` - -## File system - -Even though file system is stored on the same flash chip as the program, programming new sketch will not modify file system contents. This allows to use file system to store sketch data, configuration files, or content for Web server. - -The following diagram illustrates flash layout used in Arduino environment: - - |--------------|-------|---------------|--|--|--|--|--| - ^ ^ ^ ^ ^ - Sketch OTA update File system EEPROM WiFi config (SDK) - -File system size depends on the flash chip size. Depending on the board which is selected in IDE, you have the following options for flash size: - -Board | Flash chip size, bytes | File system size, bytes -------|-----------------|----------------- -Generic module | 512k | 64k -Generic module | 1M | 64k, 128k, 256k, 512k -Generic module | 2M | 1M -Generic module | 4M | 3M -Adafruit HUZZAH | 4M | 1M, 3M -NodeMCU 0.9 | 4M | 1M, 3M -NodeMCU 1.0 | 4M | 1M, 3M -Olimex MOD-WIFI-ESP8266(-DEV)| 2M | 1M -SparkFun Thing | 512k | 64k -SweetPea ESP-210 | 4M | 1M, 3M -WeMos D1 & D1 mini | 4M | 1M, 3M - -**Note:** to use any of file system functions in the sketch, add the following include to the sketch: - -```c++ -#include "FS.h" -``` - -### Uploading files to file system - -*ESP8266FS* is a tool which integrates into the Arduino IDE. It adds a menu item to *Tools* menu for uploading the contents of sketch data directory into ESP8266 flash file system. - -- Download the tool: https://github.com/esp8266/arduino-esp8266fs-plugin/releases/download/0.1.3/ESP8266FS-0.1.3.zip. -- In your Arduino sketchbook directory, create `tools` directory if it doesn't exist yet -- Unpack the tool into `tools` directory (the path will look like `/Arduino/tools/ESP8266FS/tool/esp8266fs.jar`) -- Restart Arduino IDE -- Open a sketch (or create a new one and save it) -- Go to sketch directory (choose Sketch > Show Sketch Folder) -- Create a directory named `data` and any files you want in the file system there -- Make sure you have selected a board, port, and closed Serial Monitor -- Select Tools > ESP8266 Sketch Data Upload. This should start uploading the files into ESP8266 flash file system. When done, IDE status bar will display `SPIFFS Image Uploaded` message. - - -### File system object (SPIFFS) - -#### begin - -```c++ -SPIFFS.begin() -``` - -This method mounts SPIFFS file system. It must be called before any other -FS APIs are used. Returns *true* if file system was mounted successfully, false -otherwise. - -#### format - -```c++ -SPIFFS.format() -``` - -Formats the file system. May be called either before or after calling `begin`. -Returns *true* if formatting was successful. - -#### open - -```c++ -SPIFFS.open(path, mode) -``` - -Opens a file. `path` should be an absolute path starting with a slash -(e.g. `/dir/filename.txt`). `mode` is a string specifying access mode. It can be -one of "r", "w", "a", "r+", "w+", "a+". Meaning of these modes is the same as -for `fopen` C function. - -Returns *File* object. To check whether the file was opened successfully, use -the boolean operator. - -```c++ -File f = SPIFFS.open("/f.txt", "w"); -if (!f) { - Serial.println("file open failed"); -} -``` - -#### exists - -```c++ -SPIFFS.exists(path) -``` - -Returns *true* if a file with given path exists, *false* otherwise. - -#### openDir - -```c++ -SPIFFS.openDir(path) -``` - -Opens a directory given its absolute path. Returns a *Dir* object. To check if -directory was opened successfully, use the boolean operator, similar to opening -a file. - -#### remove - -```c++ -SPIFFS.remove(path) -``` - -Deletes the file given its absolute path. Returns *true* if file was deleted successfully. - -#### rename - -```c++ -SPIFFS.rename(pathFrom, pathTo) -``` - -Renames file from `pathFrom` to `pathTo`. Paths must be absolute. Returns *true* -if file was renamed successfully. - -#### info - -```c++ -FSInfo fs_info; -SPIFFS.info(fs_info); -``` - -Fills [FSInfo structure](#filesystem-information-structure) with information about -the file system. Returns `true` is successful, `false` otherwise. - -### Filesystem information structure - -```c++ -struct FSInfo { - size_t totalBytes; - size_t usedBytes; - size_t blockSize; - size_t pageSize; - size_t maxOpenFiles; - size_t maxPathLength; -}; -``` - -This is the structure which may be filled using FS::info method. Field names -are self-explanatory. - -### Directory object (Dir) - -The purpose of *Dir* object is to iterate over files inside a directory. -It provides three methods: `next()`, `fileName()`, and `openFile(mode)`. - -The following example shows how it should be used: - -```c++ -Dir dir = SPIFFS.openDir("/data"); -while (dir.next()) { - Serial.print(dir.fileName()); - File f = dir.openFile("r"); - Serial.println(f.size()); -} -``` - -`dir.next()` returns true while there are files in the directory to iterate over. -It must be called before calling `fileName` and `openFile` functions. - -`openFile` method takes *mode* argument which has the same meaning as for `SPIFFS.open` function. - -### File object - -`SPIFFS.open` and `dir.openFile` functions return a *File* object. This object -supports all the functions of *Stream*, so you can use `readBytes`, `findUntil`, -`parseInt`, `println`, and all other *Stream* methods. - -There are also some functions which are specific to *File* object. - -#### seek - -```c++ -file.seek(offset, mode) -``` - -This function behaves like `fseek` C function. Depending on the value of `mode`, -it moves current position in a file as follows: - -- if `mode` is `SeekSet`, position is set to `offset` bytes from the beginning. -- if `mode` is `SeekCur`, current position is moved by `offset` bytes. -- if `mode` is `SeekEnd`, position is set to `offset` bytes from the end of the -file. - -Returns *true* if position was set successfully. - -#### position - -```c++ -file.position() -``` - -Returns the current position inside the file, in bytes. - -#### size - -```c++ -file.size() -``` - -Returns file size, in bytes. - - -#### name - -```c++ -String name = file.name(); -``` - -Returns file name, as `const char*`. Convert it to *String* for storage. - -#### close - -```c++ -file.close() -``` - -Close the file. No other operations should be performed on *File* object after `close` function was called. - -## WiFi(ESP8266WiFi library) - -This is mostly similar to WiFi shield library. Differences include: - -- `WiFi.mode(m)`: set mode to `WIFI_AP`, `WIFI_STA`, `WIFI_AP_STA` or `WIFI_OFF`. -- call `WiFi.softAP(ssid)` to set up an open network -- call `WiFi.softAP(ssid, password)` to set up a WPA2-PSK network (password should be at least 8 characters) -- `WiFi.macAddress(mac)` is for STA, `WiFi.softAPmacAddress(mac)` is for AP. -- `WiFi.localIP()` is for STA, `WiFi.softAPIP()` is for AP. -- `WiFi.printDiag(Serial)` will print out some diagnostic info -- `WiFiUDP` class supports sending and receiving multicast packets on STA interface. -When sending a multicast packet, replace `udp.beginPacket(addr, port)` with -`udp.beginPacketMulticast(addr, port, WiFi.localIP())`. -When listening to multicast packets, replace `udp.begin(port)` with -`udp.beginMulticast(WiFi.localIP(), multicast_ip_addr, port)`. -You can use `udp.destinationIP()` to tell whether the packet received was -sent to the multicast or unicast address. - -`WiFiServer`, `WiFiClient`, and `WiFiUDP` behave mostly the same way as with WiFi shield library. -Four samples are provided for this library. -You can see more commands here: [http://www.arduino.cc/en/Reference/WiFi](http://www.arduino.cc/en/Reference/WiFi) - -## Ticker - -Library for calling functions repeatedly with a certain period. Two examples included. - -It is currently not recommended to do blocking IO operations (network, serial, file) from Ticker -callback functions. Instead, set a flag inside the ticker callback and check for that flag inside the loop function. - -## EEPROM - -This is a bit different from standard EEPROM class. You need to call `EEPROM.begin(size)` -before you start reading or writing, size being the number of bytes you want to use. -Size can be anywhere between 4 and 4096 bytes. - -`EEPROM.write` does not write to flash immediately, instead you must call `EEPROM.commit()` -whenever you wish to save changes to flash. `EEPROM.end()` will also commit, and will -release the RAM copy of EEPROM contents. - -EEPROM library uses one sector of flash located just after the SPIFFS. - -Three examples included. - -## I2C (Wire library) - -Wire library currently supports master mode up to approximately 450KHz. -Before using I2C, pins for SDA and SCL need to be set by calling -`Wire.begin(int sda, int scl)`, i.e. `Wire.begin(0, 2)` on ESP-01, -else they default to pins 4(SDA) and 5(SCL). - -## SPI - -SPI library supports the entire Arduino SPI API including transactions, including setting phase (CPHA). -Setting the Clock polarity (CPOL) is not supported, yet (SPI_MODE2 and SPI_MODE3 not working). - -## SoftwareSerial - -An ESP8266 port of SoftwareSerial library done by Peter Lerup (@plerup) supports baud rate up to 115200 and multiples SoftwareSerial instances. See the https://github.com/plerup/espsoftwareserial if you want to suggest an improvement or open an issue related to SoftwareSerial. - -## ESP-specific APIs - -APIs related to deep sleep and watchdog timer are available in the `ESP` object, only available in Alpha version. - -`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.) - -`ESP.restart()` restarts the CPU. - -`ESP.getFreeHeap()` returns the free heap size. - -`ESP.getChipId()` returns the ESP8266 chip ID as a 32-bit integer. - -Several APIs may be used to get flash chip info: - -`ESP.getFlashChipId()` returns the flash chip ID as a 32-bit integer. - -`ESP.getFlashChipSize()` returns the flash chip size, in bytes, as seen by the SDK (may be less than actual size). - -`ESP.getFlashChipSpeed(void)` returns the flash chip frequency, in Hz. - -`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. - -`ESP.getVcc()` may be used to measure supply voltage. ESP needs to reconfigure the ADC -at startup in order for this feature to be available. Add the following line to the top -of your sketch to use `getVcc`: - -```c++ -ADC_MODE(ADC_VCC); -``` - -TOUT pin has to be disconnected in this mode. - -Note that by default ADC is configured to read from TOUT pin using `analogRead(A0)`, and -`ESP.getVCC()` is not available. - -## OneWire (from https://www.pjrc.com/teensy/td_libs_OneWire.html) - -Library was adapted to work with ESP8266 by including register definitions into OneWire.h -Note that if you already have OneWire library in your Arduino/libraries folder, it will be used -instead of the one that comes with this package. - -## mDNS and DNS-SD responder (ESP8266mDNS library) - -Allows the sketch to respond to multicast DNS queries for domain names like "foo.local", and DNS-SD (service dicovery) queries. -See attached example for details. - -## SSDP responder (ESP8266SSDP) - -SSDP is another service discovery protocol, supported on Windows out of the box. See attached example for reference. - -## DNS server (DNSServer library) - -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. -See attached example for details. - -## Servo - -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. -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. - -## Other libraries (not included with the IDE) - -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: - -- [arduinoWebSockets](https://github.com/Links2004/arduinoWebSockets) - WebSocket Server and Client compatible with ESP8266 (RFC6455) -- [aREST](https://github.com/marcoschwartz/aREST) REST API handler library. -- [Blynk](https://github.com/blynkkk/blynk-library) - easy IoT framework for Makers (check out the [Kickstarter page](http://tiny.cc/blynk-kick)). -- [DallasTemperature](https://github.com/milesburton/Arduino-Temperature-Control-Library.git) -- [DHT-sensor-library](https://github.com/adafruit/DHT-sensor-library) - Arduino library for the DHT11/DHT22 temperature and humidity sensors. Download latest v1.1.1 library and no changes are necessary. Older versions should initialize DHT as follows: `DHT dht(DHTPIN, DHTTYPE, 15)` -- [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). -- [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. -- [PubSubClient](https://github.com/Imroy/pubsubclient) MQTT library by @Imroy. -- [RTC](https://github.com/Makuna/Rtc) - Arduino Library for Ds1307 & Ds3231 compatible with ESP8266. -- [Souliss, Smart Home](https://github.com/souliss/souliss) - Framework for Smart Home based on Arduino, Android and openHAB. -- [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. diff --git a/doc/reference_items.yml b/doc/reference_items.yml new file mode 100644 index 0000000000..342609edd1 --- /dev/null +++ b/doc/reference_items.yml @@ -0,0 +1,15 @@ +# This file defines the order in which documents will appear in the menu + +- path: /doc/installing.html + +- path: /doc/reference.html + +- path: /doc/libraries.html + +- path: /doc/filesystem.html + +- path: /doc/ota_updates/ota_updates.html + +- path: /doc/boards.html + +- path: /doc/changes.html diff --git a/package/esp8266-arudino-doc.bash b/package/esp8266-arudino-doc.bash index 474cf66e92..25e3dc0364 100755 --- a/package/esp8266-arudino-doc.bash +++ b/package/esp8266-arudino-doc.bash @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # # @file esp8266-arudino-doc.bash @@ -11,15 +11,16 @@ # Packages needed by this script: # * linux commands: ln, cp, mkdir, rm, wget # * git -# * jekyll # -# ruby libraries: +# ruby gems: +# * jekyll # * redcarpet # * rb-pygments # # gem install [lib] # +set -e # some variable definitions tmp_path=$1 @@ -37,11 +38,11 @@ echo " version: "$version echo " release date: "$release_date echo " build date: "$build_date echo " put documentation into: "$destination_path -echo "documentatino template url: "$doc_template_url +echo "documentation template url: "$doc_template_url echo " url: "$url # continue? -read -e -p "Dou you wish to continue (y/n)? " -n 1 -i "y" decision +read -e -p "Dou you wish to continue (y/n)? " -n 1 decision if echo "$decision" | grep -iq "^y" ;then echo "okay" else @@ -99,8 +100,10 @@ ln -s ../$version _site # add subtitle and basurl echo "url: \"$url\"" > _config_local.yml -echo "subtitle: \"ver. $version, built on $build_date\"" >> _config_local.yml +echo "version: $version" >> _config_local.yml +echo "build_date: $build_date" >> _config_local.yml echo "baseurl: /Arduino/versions/$version" >> _config_local.yml +mv doc/reference_items.yml _data/reference_items.yml # build with jekyll jekyll build --config _config.yml,_config_local.yml