circuitpython/ports/esp8266/README.md

164 lines
5.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

MicroPython port to ESP8266
===========================
This is an experimental port of MicroPython for the WiFi modules based
on Espressif ESP8266 chip.
WARNING: The port is experimental and many APIs are subject to change.
Supported features include:
- REPL (Python prompt) over UART0.
- Garbage collector, exceptions.
- Unicode support.
- Builtin modules: gc, array, collections, io, struct, sys, esp, network,
many more.
- Arbitrary-precision long integers and 30-bit precision floats.
- WiFi support.
- Sockets using modlwip.
- GPIO and bit-banging I2C, SPI support.
- 1-Wire and WS2812 (aka Neopixel) protocols support.
- Internal filesystem using the flash.
- WebREPL over WiFi from a browser (clients at https://github.com/micropython/webrepl).
- Modules for HTTP, MQTT, many other formats and protocols via
https://github.com/micropython/micropython-lib .
Work-in-progress documentation is available at
http://docs.micropython.org/en/latest/esp8266/ .
Build instructions
------------------
The tool chain required for the build is the OpenSource ESP SDK, which can be
found at <https://github.com/pfalcon/esp-open-sdk>. Clone this repository and
run `make` in its directory to build and install the SDK locally. Make sure
to add toolchain bin directory to your PATH. Read esp-open-sdk's README for
additional important information on toolchain setup.
Add the external dependencies to the MicroPython repository checkout:
```bash
$ git submodule update --init
```
See the README in the repository root for more information about external
dependencies.
The MicroPython cross-compiler must be built to pre-compile some of the
built-in scripts to bytecode. This can be done using:
```bash
$ make -C mpy-cross
```
Then, to build MicroPython for the ESP8266, just run:
```bash
$ cd ports/esp8266
$ make axtls
$ make
```
This will produce binary images in the `build/` subdirectory. If you install
MicroPython to your module for the first time, or after installing any other
firmware, you should erase flash completely:
```
esptool.py --port /dev/ttyXXX erase_flash
```
Erase flash also as a troubleshooting measure, if a module doesn't behave as
expected.
To flash MicroPython image to your ESP8266, use:
```bash
$ make deploy
```
This will use the `esptool.py` script to download the images. You must have
your ESP module in the bootloader mode, and connected to a serial port on your PC.
The default serial port is `/dev/ttyACM0`, flash mode is `qio` and flash size is
`detect` (auto-detect based on Flash ID). To specify other values, use, eg (note
that flash size is in megabits):
```bash
$ make PORT=/dev/ttyUSB0 FLASH_MODE=qio FLASH_SIZE=32m deploy
```
The image produced is `build/firmware-combined.bin`, to be flashed at 0x00000.
__512KB FlashROM version__
The normal build described above requires modules with at least 1MB of FlashROM
onboard. There's a special configuration for 512KB modules, which can be
built with `make 512k`. This configuration is highly limited, lacks filesystem
support, WebREPL, and has many other features disabled. It's mostly suitable
for advanced users who are interested to fine-tune options to achieve a required
setup. If you are an end user, please consider using a module with at least 1MB
of FlashROM.
First start
-----------
Be sure to change ESP8266's WiFi access point password ASAP, see below.
__Serial prompt__
You can access the REPL (Python prompt) over UART (the same as used for
programming).
- Baudrate: 115200
Run `help()` for some basic information.
__WiFi__
Initially, the device configures itself as a WiFi access point (AP).
- ESSID: MicroPython-xxxxxx (xs are replaced with part of the MAC address).
- Password: micropythoN (note the upper-case N).
- IP address of the board: 192.168.4.1.
- DHCP-server is activated.
- Please be sure to change the password to something non-guessable
immediately. `help()` gives information how.
__WebREPL__
Python prompt over WiFi, connecting through a browser.
- Hosted at http://micropython.org/webrepl.
- GitHub repository https://github.com/micropython/webrepl.
Please follow the instructions there.
__upip__
The ESP8266 port comes with builtin `upip` package manager, which can
be used to install additional modules (see the main README for more
information):
```
>>> import upip
>>> upip.install("micropython-pystone_lowmem")
[...]
>>> import pystone_lowmem
>>> pystone_lowmem.main()
```
Downloading and installing packages may requite a lot of free memory,
if you get an error, retry immediately after the hard reset.
Documentation
-------------
More detailed documentation and instructions can be found at
http://docs.micropython.org/en/latest/esp8266/ , which includes Quick
Reference, Tutorial, General Information related to ESP8266 port, and
to MicroPython in general.
Troubleshooting
---------------
While the port is in beta, it's known to be generally stable. If you
experience strange bootloops, crashes, lockups, here's a list to check against:
- You didn't erase flash before programming MicroPython firmware.
- Firmware can be occasionally flashed incorrectly. Just retry. Recent
esptool.py versions have --verify option.
- Power supply you use doesn't provide enough power for ESP8266 or isn't
stable enough.
- A module/flash may be defective (not unheard of for cheap modules).
Please consult dedicated ESP8266 forums/resources for hardware-related
problems.
Additional information may be available by the documentation links above.