micropython/ports/esp8266
Jim Mussared 2fbc08c462 extmod/asyncio: Rename uasyncio to asyncio.
The asyncio module now has much better CPython compatibility and
deserves to be just called "asyncio".

This will avoid people having to write `from uasyncio import asyncio`.

Renames all files, and updates port manifests to use the new path. Also
renames the built-in _uasyncio to _asyncio.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2023-06-19 17:33:03 +10:00
..
boards extmod/asyncio: Rename uasyncio to asyncio. 2023-06-19 17:33:03 +10:00
modules esp32,esp8266: Allow Ctrl-C to interrupt the corrupt-fs while loop. 2023-06-15 12:19:57 +10:00
Makefile py/mkrules.mk: Automatically configure frozen options when manifest set. 2023-06-08 23:12:56 +10:00
README.md esp8266/README: Remove notice about port being "experimental". 2023-01-19 14:59:18 +11:00
esp_init_data.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
esp_mphal.c all: Rename mp_umodule*, mp_module_umodule* to remove the "u" prefix. 2023-06-08 17:54:04 +10:00
esp_mphal.h all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
espapa102.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
espapa102.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
esppwm.c all: Fix spelling mistakes based on codespell check. 2023-04-27 18:03:06 +10:00
esppwm.h esp8266/esppwm: Clip negative duty numbers to 0. 2018-02-15 11:12:41 +11:00
ets_alt_task.c all: Format code to add space after C++-style comment start. 2020-04-23 11:24:25 +10:00
ets_alt_task.h esp8266: Fix ticks_ms to correctly handle wraparound of system counter. 2019-05-24 15:37:34 +10:00
etshal.h esp8266/etshal.h: Remove unneeded function declaration. 2022-05-19 16:40:39 +10:00
fatfs_port.c all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
gccollect.c py/gc: Don't include mpconfig.h and misc.h in gc.h. 2021-02-04 22:37:26 +11:00
gccollect.h py/gc: Change include of stdint.h to stddef.h. 2021-02-05 15:46:56 +11:00
gchelper.s ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
help.c ports: Standardise docs link in help text. 2023-06-02 11:48:46 +10:00
hspi.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
hspi.h all: Reformat remaining C code that doesn't have a space after a comma. 2022-05-05 13:30:40 +10:00
hspi_register.h all: Fix spelling mistakes based on codespell check. 2023-04-27 18:03:06 +10:00
lexerstr32.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
machine_adc.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_bitstream.c esp32,esp8266: Remove dead code for end_ticks in machine_bitstream. 2021-08-24 23:55:08 +10:00
machine_hspi.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_pin.c esp8266/machine_pin: Disable open drain when pin becomes input/output. 2022-11-15 12:51:39 +11:00
machine_pwm.c esp8266/machine_pwm: Implement duty_u16() and duty_ns() for consistency. 2023-05-04 13:17:55 +10:00
machine_rtc.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_uart.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
machine_wdt.c py/obj: Convert make_new into a mp_obj_type_t slot. 2022-09-19 19:06:15 +10:00
main.c all: Rename mp_umodule*, mp_module_umodule* to remove the "u" prefix. 2023-06-08 17:54:04 +10:00
makeimg.py top: Update Python formatting to black "2023 stable style". 2023-02-02 12:51:03 +11:00
modesp.c esp8266/modmachine: Move dht_readinto() to the machine module. 2022-11-09 15:58:10 +11:00
modespnow.c esp32,esp8266: Add support for the Espressif ESP-NOW protocol. 2023-05-01 16:47:21 +10:00
modespnow.h esp32,esp8266: Add support for the Espressif ESP-NOW protocol. 2023-05-01 16:47:21 +10:00
modmachine.c all: Use MP_REGISTER_EXTENSIBLE_MODULE for overrideable built-ins. 2023-06-08 17:54:21 +10:00
modmachine.h esp8266/machine_pwm: Enable real open drain output on pin driven by PWM. 2022-11-15 12:51:32 +11:00
modnetwork.h esp32,esp8266: Change network.WLAN from a function to a type. 2023-05-18 14:52:28 +10:00
modnetwork_globals.h esp32,esp8266: Change network.WLAN from a function to a type. 2023-05-18 14:52:28 +10:00
modos.c all: Rename *umodule*.c to remove the "u" prefix. 2023-06-08 17:54:17 +10:00
modtime.c all: Rename *umodule*.c to remove the "u" prefix. 2023-06-08 17:54:17 +10:00
mpconfigport.h py/mpconfig: Enable module delegation if sys needs it. 2023-06-08 17:54:24 +10:00
network_wlan.c esp32,esp8266: Change network.WLAN from a function to a type. 2023-05-18 14:52:28 +10:00
posix_helpers.c py/mpconfig: Introduce reusable MP_HTOBE32(), etc. macros. 2017-11-08 19:47:37 +02:00
qstrdefsport.h all: Add *FORMAT-OFF* in various places. 2020-02-28 10:31:07 +11:00
strtoll.c all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00
uart.c all: Fix spelling mistakes based on codespell check. 2023-04-27 18:03:06 +10:00
uart.h esp8266/machine_uart: Implement uart.flush() and uart.txdone(). 2022-08-31 00:18:27 +10:00
uart_register.h all: Format code to add space after C++-style comment start. 2020-04-23 11:24:25 +10:00
user_config.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
xtirq.h all: Reformat C and Python source code with tools/codeformat.py. 2020-02-28 10:33:03 +11:00

README.md

MicroPython port to ESP8266

This is a port of MicroPython to the Espressif ESP8266 WiFi microcontroller. MicroPython runs on this chip without any underlying operating system, using the ESP8266 NONOS SDK.

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 .

Documentation is available at http://docs.micropython.org/en/latest/esp8266/quickref.html.

Build instructions

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 (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:

$ make -C ports/esp8266 submodules

See the README in the repository root for more information about external dependencies.

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:

$ 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"

(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:

$ make -C mpy-cross

Then to compile the ESP8266 firmware:

$ cd ports/esp8266
$ make -j BOARD=GENERIC

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:

$ esptool.py --port /dev/ttyXXX erase_flash

Erasing the flash is also useful as a troubleshooting measure, if a module doesn't behave as expected.

To flash MicroPython image to your ESP8266, use:

$ make deploy

(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.)

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 for esptool.py, use, e.g.:

$ make PORT=/dev/ttyUSB0 FLASH_MODE=qio FLASH_SIZE=32m deploy

(note that flash size is in megabits)

If you want to flash manually using esptool.py directly, the image produced is build-GENERIC/firmware-combined.bin, to be flashed at 0x00000.

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:

$ make BOARD=GENERIC_512K

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 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.

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.

mip

The ESP8266 port comes with the built-in mip package manager, which can be used to install additional modules:

>>> import mip
>>> mip.install("hmac")
[...]
>>> import hmac
>>> hmac.new(b"1234567890", msg="hello world").hexdigest()

See Package management for more information about mip.

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.