2015-10-12 00:06:25 +01:00
|
|
|
|
MicroPython port to ESP8266
|
|
|
|
|
===========================
|
2014-11-29 15:06:20 +00:00
|
|
|
|
|
2016-07-02 21:13:40 +01:00
|
|
|
|
This is an experimental port of MicroPython for the WiFi modules based
|
2015-06-18 09:46:43 +01:00
|
|
|
|
on Espressif ESP8266 chip.
|
|
|
|
|
|
2016-07-02 21:13:40 +01:00
|
|
|
|
WARNING: The port is experimental and many APIs are subject to change.
|
2014-11-29 15:06:20 +00:00
|
|
|
|
|
2016-07-02 21:13:40 +01:00
|
|
|
|
Supported features include:
|
2014-11-29 15:06:20 +00:00
|
|
|
|
- REPL (Python prompt) over UART0.
|
|
|
|
|
- Garbage collector, exceptions.
|
|
|
|
|
- Unicode support.
|
2016-03-27 14:10:58 +01:00
|
|
|
|
- Builtin modules: gc, array, collections, io, struct, sys, esp, network,
|
|
|
|
|
many more.
|
2016-03-23 10:08:15 +00:00
|
|
|
|
- Arbitrary-precision long integers and 30-bit precision floats.
|
2016-04-17 16:17:49 +01:00
|
|
|
|
- WiFi support.
|
2016-03-27 14:10:58 +01:00
|
|
|
|
- Sockets using modlwip.
|
|
|
|
|
- GPIO and bit-banging I2C, SPI support.
|
|
|
|
|
- 1-Wire and WS2812 (aka Neopixel) protocols support.
|
2014-11-29 15:06:20 +00:00
|
|
|
|
- Internal filesystem using the flash.
|
2016-04-30 21:02:54 +01:00
|
|
|
|
- WebREPL over WiFi from a browser (clients at https://github.com/micropython/webrepl).
|
2016-07-02 21:13:40 +01:00
|
|
|
|
- Modules for HTTP, MQTT, many other formats and protocols via
|
|
|
|
|
https://github.com/micropython/micropython-lib .
|
2014-11-29 15:06:20 +00:00
|
|
|
|
|
2020-03-02 01:05:38 +00:00
|
|
|
|
Documentation is available at http://docs.micropython.org/en/latest/esp8266/quickref.html.
|
2016-04-02 22:01:31 +01:00
|
|
|
|
|
2014-11-29 15:06:20 +00:00
|
|
|
|
Build instructions
|
|
|
|
|
------------------
|
|
|
|
|
|
2022-08-22 02:16:16 +01:00
|
|
|
|
You need the esp-open-sdk toolchain, which provides both the compiler and libraries.
|
|
|
|
|
|
|
|
|
|
There are two ways to do this:
|
|
|
|
|
- By running the toolchain in [Docker](https://www.docker.com/) (**recommended**).
|
|
|
|
|
- By installing a pre-built toolchain and adding it to your `$PATH`.
|
|
|
|
|
|
|
|
|
|
Regardless of which toolchain you use, the first step is to make sure required
|
|
|
|
|
submodules are available:
|
|
|
|
|
|
2016-03-08 07:22:00 +00:00
|
|
|
|
```bash
|
2020-03-02 01:05:38 +00:00
|
|
|
|
$ make -C ports/esp8266 submodules
|
2016-03-08 07:22:00 +00:00
|
|
|
|
```
|
2022-08-22 02:16:16 +01:00
|
|
|
|
|
2016-03-08 07:22:00 +00:00
|
|
|
|
See the README in the repository root for more information about external
|
|
|
|
|
dependencies.
|
|
|
|
|
|
2022-08-22 02:16:16 +01:00
|
|
|
|
__Building with Docker__
|
|
|
|
|
|
|
|
|
|
Once you have installed Docker, you can run all of the following build
|
|
|
|
|
commands inside the Docker container by prefixing them with `docker
|
|
|
|
|
run --rm -v $HOME:$HOME -u $UID -w $PWD larsks/esp-open-sdk ...command...`.
|
|
|
|
|
This will automatically download the Docker image provided by @larsks which
|
|
|
|
|
contains the full toolchain and SDK.
|
|
|
|
|
|
|
|
|
|
Then you need to compile the MicroPython cross-compiler (`mpy-cross`). From
|
|
|
|
|
the root of this repository, run:
|
|
|
|
|
|
2016-06-29 14:25:12 +01:00
|
|
|
|
```bash
|
2022-08-22 02:16:16 +01:00
|
|
|
|
$ docker run --rm -v $HOME:$HOME -u $UID -w $PWD larsks/esp-open-sdk make -C mpy-cross
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Note:** The `mpy-cross` binary will likely only work inside the Docker
|
|
|
|
|
container. This will not be a problem if you're only building ESP8266
|
|
|
|
|
firmware, but if you're also working on other ports then you will need to
|
|
|
|
|
recompile for your host when switching between ports. To avoid this, use
|
|
|
|
|
the local toolchain instead.
|
|
|
|
|
|
|
|
|
|
Then to compile the ESP8266 firmware:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ cd ports/esp8266
|
|
|
|
|
$ docker run --rm -v $HOME:$HOME -u $UID -w $PWD larsks/esp-open-sdk make -j BOARD=GENERIC
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This will produce binary images in the `build-GENERIC/` subdirectory.
|
|
|
|
|
Substitute the board for whichever board you're using.
|
|
|
|
|
|
|
|
|
|
__Building with a local toolchain__
|
|
|
|
|
|
|
|
|
|
First download the pre-built toolchain (thanks to @jepler from Adafruit). You
|
|
|
|
|
will need to find somewhere to put it in your filesystem, e.g. `~/espressif`.
|
|
|
|
|
Create that directory first if necessary.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ cd ~/espressif # Change as necessary
|
|
|
|
|
$ wget https://github.com/jepler/esp-open-sdk/releases/download/2018-06-10/xtensa-lx106-elf-standalone.tar.gz
|
|
|
|
|
$ tar zxvf xtensa-lx106-elf-standalone.tar.gz
|
|
|
|
|
$ rm xtensa-lx106-elf/bin/esptool.py # Use system version of esptool.py instead.
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then append this to your `$PATH` variable so the compiler binaries can be
|
|
|
|
|
found:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
$ export "PATH=$HOME/espressif/xtensa-lx106-elf/bin/:$PATH"
|
2016-06-29 14:25:12 +01:00
|
|
|
|
```
|
|
|
|
|
|
2022-08-22 02:16:16 +01:00
|
|
|
|
(You will need to do this each time you start a new terminal)
|
|
|
|
|
|
|
|
|
|
Then you need to compile the MicroPython cross-compiler (`mpy-cross`). From
|
|
|
|
|
the root of this repository, run:
|
|
|
|
|
|
2014-11-29 15:06:20 +00:00
|
|
|
|
```bash
|
2022-08-22 02:16:16 +01:00
|
|
|
|
$ make -C mpy-cross
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then to compile the ESP8266 firmware:
|
|
|
|
|
|
|
|
|
|
```
|
2018-02-14 20:40:16 +00:00
|
|
|
|
$ cd ports/esp8266
|
2022-08-22 02:16:16 +01:00
|
|
|
|
$ make -j BOARD=GENERIC
|
2014-11-29 15:06:20 +00:00
|
|
|
|
```
|
2020-03-02 01:05:38 +00:00
|
|
|
|
|
2022-08-22 02:16:16 +01:00
|
|
|
|
This will produce binary images in the `build-GENERIC/` subdirectory.
|
|
|
|
|
Substitute the board for whichever board you're using.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installing MicroPython
|
|
|
|
|
----------------------
|
|
|
|
|
|
|
|
|
|
To communicate with the board you will need to install `esptool.py`. This can
|
|
|
|
|
be obtained from your system package manager or from PyPi via `pip`.
|
|
|
|
|
|
|
|
|
|
If you install MicroPython to your module for the first time, or after
|
|
|
|
|
installing any other firmware, you should erase flash completely:
|
|
|
|
|
|
2019-09-18 06:08:06 +01:00
|
|
|
|
```bash
|
|
|
|
|
$ esptool.py --port /dev/ttyXXX erase_flash
|
2016-03-23 10:32:27 +00:00
|
|
|
|
```
|
|
|
|
|
|
2020-03-02 01:05:38 +00:00
|
|
|
|
Erasing the flash is also useful as a troubleshooting measure, if a module doesn't
|
|
|
|
|
behave as expected.
|
2016-03-23 10:32:27 +00:00
|
|
|
|
|
|
|
|
|
To flash MicroPython image to your ESP8266, use:
|
2014-11-29 15:06:20 +00:00
|
|
|
|
```bash
|
|
|
|
|
$ make deploy
|
|
|
|
|
```
|
2022-08-22 02:16:16 +01:00
|
|
|
|
|
|
|
|
|
(If using the Docker instructions above, do not run this command via Docker as
|
|
|
|
|
it will need access to the serial port. Run it directly instead.)
|
2020-03-02 01:05:38 +00:00
|
|
|
|
|
2014-11-29 15:06:20 +00:00
|
|
|
|
This will use the `esptool.py` script to download the images. You must have
|
2016-03-23 10:32:27 +00:00
|
|
|
|
your ESP module in the bootloader mode, and connected to a serial port on your PC.
|
2016-11-08 01:52:07 +00:00
|
|
|
|
The default serial port is `/dev/ttyACM0`, flash mode is `qio` and flash size is
|
2020-03-02 01:05:38 +00:00
|
|
|
|
`detect` (auto-detect based on Flash ID).
|
|
|
|
|
|
|
|
|
|
To specify other values for `esptool.py`, use, e.g.:
|
2014-11-29 15:06:20 +00:00
|
|
|
|
```bash
|
2016-11-08 01:52:07 +00:00
|
|
|
|
$ make PORT=/dev/ttyUSB0 FLASH_MODE=qio FLASH_SIZE=32m deploy
|
2014-11-29 15:06:20 +00:00
|
|
|
|
```
|
2020-03-02 01:05:38 +00:00
|
|
|
|
(note that flash size is in megabits)
|
2014-11-29 15:06:20 +00:00
|
|
|
|
|
2020-03-02 01:05:38 +00:00
|
|
|
|
If you want to flash manually using `esptool.py` directly, the image produced is
|
|
|
|
|
`build-GENERIC/firmware-combined.bin`, to be flashed at 0x00000.
|
2019-09-18 06:08:06 +01:00
|
|
|
|
|
|
|
|
|
The default board definition is the directory `boards/GENERIC`.
|
|
|
|
|
For a custom configuration you can define your own board in the directory `boards/`.
|
|
|
|
|
|
|
|
|
|
The `BOARD` variable can be set on the make command line, for example:
|
|
|
|
|
```bash
|
|
|
|
|
$ make BOARD=GENERIC_512K
|
|
|
|
|
```
|
2016-04-06 22:21:04 +01:00
|
|
|
|
|
2017-04-13 23:03:46 +01:00
|
|
|
|
__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
|
2019-09-18 06:08:06 +01:00
|
|
|
|
built with `make BOARD=GENERIC_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.
|
2017-04-13 23:03:46 +01:00
|
|
|
|
|
2016-05-12 10:13:10 +01:00
|
|
|
|
First start
|
|
|
|
|
-----------
|
|
|
|
|
|
2017-11-12 16:29:27 +00:00
|
|
|
|
Be sure to change ESP8266's WiFi access point password ASAP, see below.
|
|
|
|
|
|
2016-05-12 10:13:10 +01:00
|
|
|
|
__Serial prompt__
|
|
|
|
|
|
|
|
|
|
You can access the REPL (Python prompt) over UART (the same as used for
|
|
|
|
|
programming).
|
|
|
|
|
- Baudrate: 115200
|
|
|
|
|
|
2017-11-12 16:29:27 +00:00
|
|
|
|
Run `help()` for some basic information.
|
|
|
|
|
|
2016-05-12 10:13:10 +01:00
|
|
|
|
__WiFi__
|
|
|
|
|
|
2017-05-29 08:08:14 +01:00
|
|
|
|
Initially, the device configures itself as a WiFi access point (AP).
|
2016-05-12 10:13:10 +01:00
|
|
|
|
- ESSID: MicroPython-xxxxxx (x’s 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.
|
2017-11-12 16:29:27 +00:00
|
|
|
|
- Please be sure to change the password to something non-guessable
|
|
|
|
|
immediately. `help()` gives information how.
|
2016-05-12 10:13:10 +01:00
|
|
|
|
|
|
|
|
|
__WebREPL__
|
|
|
|
|
|
|
|
|
|
Python prompt over WiFi, connecting through a browser.
|
|
|
|
|
- Hosted at http://micropython.org/webrepl.
|
|
|
|
|
- GitHub repository https://github.com/micropython/webrepl.
|
2017-11-12 16:29:27 +00:00
|
|
|
|
Please follow the instructions there.
|
2016-05-12 10:13:10 +01:00
|
|
|
|
|
2017-11-12 16:34:18 +00:00
|
|
|
|
__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.
|
|
|
|
|
|
2017-06-24 15:38:53 +01:00
|
|
|
|
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.
|
2016-05-12 10:13:10 +01:00
|
|
|
|
|
2016-04-06 22:21:04 +01:00
|
|
|
|
Troubleshooting
|
|
|
|
|
---------------
|
|
|
|
|
|
2017-04-13 22:56:41 +01:00
|
|
|
|
While the port is in beta, it's known to be generally stable. If you
|
2016-04-06 22:21:04 +01:00
|
|
|
|
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.
|
2017-06-24 15:38:53 +01:00
|
|
|
|
|
|
|
|
|
Additional information may be available by the documentation links above.
|