micropython/ports/esp8266
Damien George 8f4c108025 all: Remove MICROPY_PY_IO_FILEIO config option.
Since commit e65d1e69e8 there is no longer an
io.FileIO class, so this option is no longer needed.

This option also controlled whether or not files supported being opened in
binary mode (eg 'rb'), and could, if disabled, lead to confusion as to why
opening a file in binary mode silently did the wrong thing (it would just
open in text mode if MICROPY_PY_IO_FILEIO was disabled).

The various VFS implementations (POSIX, FAT, LFS) were the only places
where enabling this option made a difference, and in almost all cases where
one of these filesystems were enabled, MICROPY_PY_IO_FILEIO was also
enabled.  So it makes sense to just unconditionally enable this feature
(ability to open a file in binary mode) in all cases, and so just remove
this config option altogether.  That makes configuration simpler and means
binary file support always exists (and opening a file in binary mode is
arguably more fundamental than opening in text mode, so if anything should
be configurable then it should be the ability to open in text mode).

Signed-off-by: Damien George <damien@micropython.org>
2022-08-18 11:54:17 +10:00
..
boards extmod/ntptime: Factor out ntptime module from esp8266 port. 2022-08-06 00:08:32 +10:00
modules extmod/ntptime: Factor out ntptime module from esp8266 port. 2022-08-06 00:08:32 +10:00
Makefile ports: Always append to GIT_SUBMODULES. 2022-08-03 00:05:26 +10:00
README.md esp8266/README.md: Add docker build instructions. 2020-03-22 13:26:03 +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: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +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: Reformat remaining C code that doesn't have a space after a comma. 2022-05-05 13:30:40 +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 esp8266/modnetwork: Rename WLAN keyword args to ssid/security/key. 2022-06-17 21:43:44 +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: Add *FORMAT-OFF* in various places. 2020-02-28 10:31:07 +11: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 all: Use MP_ERROR_TEXT for all error messages. 2020-04-05 15:02:06 +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 all: Use mp_obj_malloc everywhere it's applicable. 2022-05-03 22:28:14 +10:00
machine_pin.c esp8266: Use MP_REGISTER_ROOT_POINTER(). 2022-07-18 13:50:34 +10:00
machine_pwm.c all: Use mp_obj_malloc everywhere it's applicable. 2022-05-03 22:28:14 +10:00
machine_rtc.c all: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
machine_uart.c esp8266: Use MP_REGISTER_ROOT_POINTER(). 2022-07-18 13:50:34 +10:00
machine_wdt.c esp8266/machine_wdt: Remove deinit method for watchdog. 2022-05-19 16:40:39 +10:00
main.c py/builtin: Clean up and simplify import_stat and builtin_open config. 2022-05-25 13:04:45 +10:00
makeimg.py esp8266/makeimg.py: Print out info about RAM segments when building fw. 2020-04-04 16:30:39 +11:00
modesp.c all: Remove third argument to MP_REGISTER_MODULE. 2022-06-02 16:31:37 +10:00
modmachine.c all: Remove third argument to MP_REGISTER_MODULE. 2022-06-02 16:31:37 +10:00
modmachine.h extmod/machine_pwm: Factor out machine.PWM bindings to common code. 2021-09-04 16:31:17 +10:00
modnetwork.c esp32,esp8266: Rename WLAN dhcp_hostname config to hostname. 2022-07-05 23:40:32 +10:00
moduos.c esp8266/moduos: Convert module to use extmod version. 2022-03-09 10:03:23 +11:00
modutime.c all: Remove third argument to MP_REGISTER_MODULE. 2022-06-02 16:31:37 +10:00
mpconfigport.h all: Remove MICROPY_PY_IO_FILEIO config option. 2022-08-18 11:54:17 +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: Update to point to files in new shared/ directory. 2021-07-12 17:08:10 +10:00
uart.h all: Format code to add space after C++-style comment start. 2020-04-23 11:24:25 +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 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 .

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), which you can obtain using one of the following two options:

  • Use a Docker image with a pre-built toolchain (recommended). To use this, install Docker, then prepend docker run --rm -v $HOME:$HOME -u $UID -w $PWD larsks/esp-open-sdk to the start of the mpy-cross and firmware make commands below. This will run the commands using the toolchain inside the container but using the files on your local filesystem.

  • or, install the esp-open-sdk directly on your PC, 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. If you use this approach, then the command below will work exactly.

Add the external dependencies to the MicroPython repository checkout:

$ make -C ports/esp8266 submodules

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:

$ make -C mpy-cross

(Prepend the Docker command if using Docker, see above)

Then, to build MicroPython for the ESP8266, just run:

$ cd ports/esp8266
$ make

(Prepend the Docker command if using Docker, see above)

This will produce binary images in the build-GENERIC/ 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

You can install esptool.py either from your system package manager or from PyPi.

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

(This should not be run inside Docker as it will need access to the serial port.)

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.

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.