circuitpython/ports/esp8266
Damien George ad7213d3c3 py: Add mp_raise_msg_varg helper and use it where appropriate.
This commit adds mp_raise_msg_varg(type, fmt, ...) as a helper for
nlr_raise(mp_obj_new_exception_msg_varg(type, fmt, ...)).  It makes the
C-level API for raising exceptions more consistent, and reduces code size
on most ports:

   bare-arm:   +28 +0.042%
minimal x86:  +100 +0.067%
   unix x64:   -56 -0.011%
unix nanbox:  -300 -0.068%
      stm32:  -204 -0.054% PYBV10
     cc3200:    +0 +0.000%
    esp8266:   -64 -0.010% GENERIC
      esp32:  -104 -0.007% GENERIC
        nrf:  -136 -0.094% pca10040
       samd:    +0 +0.000% ADAFRUIT_ITSYBITSY_M4_EXPRESS
2020-02-13 11:52:40 +11:00
..
boards esp8266: Put mp_keyboard_interrupt in IRAM. 2020-02-07 16:08:31 +11:00
modules esp8266/modules/ntptime.py: Add comment about configuring NTP host. 2020-01-31 23:54:11 +11:00
Makefile ports: Allow overriding CROSS_COMPILE in a custom makefile. 2019-12-27 23:53:16 +11:00
README.md esp8266: Add per-board configs, following other ports. 2019-10-10 16:32:25 +11:00
esp_init_data.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
esp_mphal.c py/scheduler: Add "raise_exc" argument to mp_handle_pending. 2020-02-07 16:08:20 +11:00
esp_mphal.h esp8266/esp_mphal: Provide mp_hal_pin_od_high_dht so DHT works reliably. 2019-01-22 00:26:04 +11:00
espapa102.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
espapa102.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
espneopixel.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
espneopixel.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
esppwm.c esp8266/esppwm: Always start timer to avoid glitch from full to nonfull. 2018-03-05 11:39:44 +11:00
esppwm.h esp8266/esppwm: Clip negative duty numbers to 0. 2018-02-15 11:12:41 +11:00
ets_alt_task.c esp8266: Fix ticks_ms to correctly handle wraparound of system counter. 2019-05-24 15:37:34 +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: Make function prototypes compatible with ESP SDK 2.1.0+. 2017-11-05 00:29:33 +02:00
fatfs_port.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
gccollect.c esp8266: Remove scanning of GC pointers in native code block. 2018-09-27 23:46:09 +10:00
gccollect.h esp8266: Remove scanning of GC pointers in native code block. 2018-09-27 23:46:09 +10:00
gchelper.s ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
help.c py/builtinhelp: Change signature of help text var from pointer to array. 2017-09-12 16:03:52 +10:00
hspi.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
hspi.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
hspi_register.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
intr.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
lexerstr32.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
machine_adc.c py: Add mp_raise_msg_varg helper and use it where appropriate. 2020-02-13 11:52:40 +11:00
machine_hspi.c esp8266/modmachine: Allow I2C and SPI to be configured out of the build. 2018-05-17 23:37:12 +10:00
machine_pin.c all: Convert nlr_raise(mp_obj_new_exception_msg(x)) to mp_raise_msg(x). 2019-11-05 11:35:45 +11:00
machine_pwm.c py: Add mp_raise_msg_varg helper and use it where appropriate. 2020-02-13 11:52:40 +11:00
machine_rtc.c all: Remove inclusion of internal py header files. 2017-10-04 12:37:50 +11:00
machine_uart.c py: Add mp_raise_msg_varg helper and use it where appropriate. 2020-02-13 11:52:40 +11:00
machine_wdt.c esp8266: Let machine.WDT trigger the software WDT if obj is not fed. 2018-07-03 15:31:10 +10:00
main.c various: Add and update my copyright line based on git history. 2019-05-17 18:04:15 +10:00
makeimg.py ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
modesp.c py: Add mp_raise_msg_varg helper and use it where appropriate. 2020-02-13 11:52:40 +11:00
modmachine.c esp8266/machine_adc: Rename pyb_adc_* to machine_adc_*. 2019-09-04 16:17:10 +10:00
modmachine.h esp8266/machine_adc: Rename pyb_adc_* to machine_adc_*. 2019-09-04 16:17:10 +10:00
modnetwork.c all: Convert nlr_raise(mp_obj_new_exception_msg(x)) to mp_raise_msg(x). 2019-11-05 11:35:45 +11:00
modpyb.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
moduos.c esp8266/moduos: Add optional support for VfsLfs1 and VfsLfs2. 2019-11-07 18:44:16 +11:00
modutime.c py: Add mp_raise_msg_varg helper and use it where appropriate. 2020-02-13 11:52:40 +11:00
mpconfigport.h esp8266: Put mp_keyboard_interrupt in IRAM. 2020-02-07 16:08:31 +11:00
posix_helpers.c py/mpconfig: Introduce reusable MP_HTOBE32(), etc. macros. 2017-11-08 19:47:37 +02:00
qstrdefsport.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
strtoll.c ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10:00
uart.c esp8266/uart: Fix invalid ringbuf name when event driven REPL enabled. 2019-06-17 12:34:10 +10:00
uart.h esp8266/machine_uart: Add rxbuf keyword arg to UART constructor/init. 2018-12-05 23:31:24 +11:00
uart_register.h ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +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 ports: Make new ports/ sub-directory and move all ports there. 2017-09-06 13:40:51 +10: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 .

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:

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

$ make -C mpy-cross

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

$ cd ports/esp8266
$ make

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

Erase flash also as a troubleshooting measure, if a module doesn't behave as expected.

To flash MicroPython image to your ESP8266, use:

$ 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):

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

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.