esp

Platypush documentation

esp#

Description#

This plugin allows you to fully control to ESP8266/ESP32 devices connected over WiFi. It uses the WebREPL interface embedded in MicroPython to communicate with the device.

All you need to do is to flash the MicroPython firmware to your device, enable the WebREPL interface, and you can use this plugin to fully control the device remotely without deploying any code to the controller.

  • Download the MicroPython firmware for your device.

  • Connect your ESP8266/ESP32 via serial/USB port and flash the firmware. For example. using esptool and assuming that you have an ESP8266 device connected on /dev/ttyUSB0:

    # Erase the flash memory
esptool.py --port /dev/ttyUSB0 erase_flash
# Flash the firmware
esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 esp8266-[version].bin

  • Access the MicroPython interpreter over serial/USB port. For example, on Linux:

picocom /dev/ttyUSB0 -b11520

  • Configure the WiFi interface:

>>> import network
>>> wlan = network.WLAN(network.STA_IF)
>>> wlan.active(True)
>>> wlan.connect('YourSSID', 'YourPassword')
>>> # Print the device IP address
>>> wlan.ifconfig()[0]
>>> '192.168.1.23'

Configuration#

esp:
  # [Optional]
  # List of configured device. Pre-configuring devices by name allows you to call the actions
  # directly by device name, instead of specifying ``host``, ``port`` and ``password`` on each call. It
  # also allows you to interact with PINs by name, if you specified names for them, instead of using the
  # PIN number on your calls. Example configuration:
  #
  # .. code-block:: yaml
  #
  #     devices:
  #         - host: 192.168.1.23
  #           port: 8266        # WebREPL websocket port
  #           password: pwd1    # Device password
  #           name: smoke_detector
  #           pins:
  #             - number: 14
  #               name: smoke_sensor
  #               pwm: False
  #
  #         - host: 192.168.1.24
  #           port: 8266
  #           password: pwd2
  #           name: smart_switch
  #           pins:
  #             - number: 13
  #               name: relay
  #               pwm: True
  # devices:   # type=Optional[List[Union[platypush.plugins.esp.models.device.Device, dict]]]

Actions#

Module reference#

class platypush.plugins.esp.EspPlugin(devices: List[Device | dict] | None = None, **kwargs)[source]#

Bases: Plugin

This plugin allows you to fully control to ESP8266/ESP32 devices connected over WiFi. It uses the WebREPL interface embedded in MicroPython to communicate with the device.

All you need to do is to flash the MicroPython firmware to your device, enable the WebREPL interface, and you can use this plugin to fully control the device remotely without deploying any code to the controller.

  • Download the MicroPython firmware for your device.

  • Connect your ESP8266/ESP32 via serial/USB port and flash the firmware. For example. using esptool and assuming that you have an ESP8266 device connected on /dev/ttyUSB0:

    # Erase the flash memory
esptool.py --port /dev/ttyUSB0 erase_flash
# Flash the firmware
esptool.py --port /dev/ttyUSB0 --baud 115200 write_flash --flash_size=detect 0 esp8266-[version].bin

  • Access the MicroPython interpreter over serial/USB port. For example, on Linux:

picocom /dev/ttyUSB0 -b11520

  • Configure the WiFi interface:

>>> import network
>>> wlan = network.WLAN(network.STA_IF)
>>> wlan.active(True)
>>> wlan.connect('YourSSID', 'YourPassword')
>>> # Print the device IP address
>>> wlan.ifconfig()[0]
>>> '192.168.1.23'
__init__(devices: List[Device | dict] | None = None, **kwargs)[source]#
Parameters:

devices –

List of configured device. Pre-configuring devices by name allows you to call the actions directly by device name, instead of specifying host, port and password on each call. It also allows you to interact with PINs by name, if you specified names for them, instead of using the PIN number on your calls. Example configuration:

devices:
    - host: 192.168.1.23
      port: 8266        # WebREPL websocket port
      password: pwd1    # Device password
      name: smoke_detector
      pins:
        - number: 14
          name: smoke_sensor
          pwm: False

    - host: 192.168.1.24
      port: 8266
      password: pwd2
      name: smart_switch
      pins:
        - number: 13
          name: relay
          pwm: True

adc_read(pin: int = 0, **kwargs) → int[source]#

Read an analog value from a PIN. Note that the ESP8266 only has one analog PIN, accessible on the channel 0. If you are interested in the actual voltage that is measured then apply V = Vcc * (value/1024), where Vcc is the supply voltage provided to the device (usually 3V if connected to the Vcc PIN of an ESP8266).

Parameters:
Returns:

A value between 0 and 1024.

ap_config(ip: str | None = None, netmask: str | None = None, gateway: str | None = None, dns: str | None = None, essid: str | None = None, passphrase: str | None = None, channel: int | None = None, hidden: bool | None = None, **kwargs) → dict | None[source]#

Get or set network properties for the WiFi access point interface. If called with no arguments it will return the configuration of the interface.

Parameters:

  • ip – IP address.

  • netmask – Netmask.

  • gateway – Default gateway address.

  • dns – Default DNS address.

  • essid – ESSID of the access point.

  • passphrase – Password/passphrase.

  • channel – WiFi channel.

  • hidden – Whether the network is hidden.

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

Returns:

{
  "active": true,
  "channel": 6,
  "dns": "1.1.1.1",
  "essid": "MyNetwork",
  "gateway": "192.168.1.1",
  "hidden": "Whether the Wi-Fi network is hidden.",
  "ip": "192.168.1.10",
  "mac": "00:11:22:33:44:55",
  "netmask": "255.255.255.0"
}

ap_disable(**kwargs)[source]#

Disable the device WiFi access point interface.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

ap_enable(**kwargs)[source]#

Enable the device WiFi access point interface.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

chdir(directory: str, **kwargs)[source]#

Move to the specified directory.

Parameters:
close(device: str | None = None, host: str | None = None, port: int = 8266)[source]#

Close an active connection to a device.

Parameters:

  • device – Configured device name. Either device or host and port must be provided.

  • host – ESP host.

  • port – ESP port.

connect(device: str | None = None, host: str | None = None, port: int = 8266, password: str | None = None, timeout: float | None = 10.0)[source]#

Open a connection to an ESP device.

Parameters:

  • device – Configured device name. Either device or host and port must be provided.

  • host – ESP host.

  • port – ESP port (default: 8266).

  • password – ESP WebREPL password.

  • timeout – Connection timeout (default: 10 seconds).

db_get(dbfile: str, key: str, **kwargs) → Any[source]#

Set a value on an internal B-Tree file database.

Parameters:
Returns:

Whichever value is stored as output, or null if the key doesn’t exist.

db_items(dbfile: str, **kwargs) → Dict[str, str][source]#

Get a key->value mapping of the items stored in a B-Tree file database.

Parameters:
Returns:

Whichever value is stored as output, or null if the key doesn’t exist.

db_keys(dbfile: str, **kwargs) → List[str][source]#

Get the list of keys stored on an internal B-Tree file database.

Parameters:
db_set(dbfile: str, key: str, value: Any, **kwargs)[source]#

Set a value on an internal B-Tree file database.

Parameters:
db_values(dbfile: str, **kwargs) → List[str][source]#

Get the list of item values stored on an internal B-Tree file database.

Parameters:
deep_sleep(seconds: float | None = None, **kwargs)[source]#

Stops execution in an attempt to enter a low power state. A deepsleep may not retain RAM or any other state of the system (for example peripherals or network interfaces). Upon wake execution is resumed from the main script, similar to a hard or power-on reset.

Parameters:
dht11_get_humidity(pin: int | str, **kwargs) → float[source]#

Get the humidity value in percentage (0-100) from a connected DHT11 sensor.

Parameters:
dht11_get_temperature(pin: int | str, **kwargs) → float[source]#

Get the temperature value in Celsius from a connected DHT11 sensor.

Parameters:
dht22_get_humidity(pin: int | str, **kwargs) → float[source]#

Get the humidity value in percentage (0-100) from a connected DHT22 sensor.

Parameters:
dht22_get_temperature(pin: int | str, **kwargs) → float[source]#

Get the temperature value in Celsius from a connected DHT22 sensor.

Parameters:
disable_irq(**kwargs)[source]#

Disable interrupt requests.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

enable_irq(**kwargs)[source]#

Enable interrupt requests.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

execute(code: str, device: str | None = None, host: str | None = None, port: int = 8266, password: str | None = None, conn_timeout: float | None = 10.0, recv_timeout: float | None = 30.0, wait_response: bool = True, **_) → Response[source]#

Run raw Python code on the ESP device.

Parameters:

  • code – Snippet of code to run.

  • device – Configured device name. Either device or host and port must be provided.

  • host – ESP host.

  • port – ESP port (default: 8266).

  • password – ESP WebREPL password.

  • conn_timeout – Connection timeout (default: 10 seconds).

  • recv_timeout – Response receive timeout (default: 30 seconds).

  • wait_response – Wait for the response from the device (default: True)

Returns:

The response returned by the Micropython interpreter, as a string.

file_download(source: str, destination: str, timeout: float | None = 60.0, **kwargs)[source]#

Download a file from the board to the local machine.

Parameters:

  • source – Name or path of the file to download from the device.

  • destination – Target directory or path on the local machine.

  • timeout – File transfer timeout (default: one minute).

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

file_get(file: str, binary: bool = False, timeout: float | None = 60.0, **kwargs) → str[source]#

Get the content of a file on the board.

Parameters:

  • file – File name/path to get from the device.

  • binary – If True, then the base64-encoded content of the file will be returned.

  • timeout – File transfer timeout (default: one minute).

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.connect().

file_upload(source: str, destination: str | None = None, timeout: float | None = 60.0, **kwargs)[source]#

Upload a file to the board.

Parameters:

  • source – Path of the local file to copy.

  • destination – Target file name (default: a filename will be created under the board’s root folder with the same name as the source file).

  • timeout – File transfer timeout (default: one minute).

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.connect().

get_freq(**kwargs) → int[source]#

Get the frequency of the device in Hz.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

i2c_close(**kwargs)[source]#

Turn off an I2C bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.i2c_open() and platypush.plugins.esp.EspPlugin.execute().

i2c_open(scl: int | None = None, sda: int | None = None, id: int = -1, baudrate: int = 400000, **kwargs)[source]#

Open a connection to an I2C (or “two-wire”) port.

Parameters:

  • scl – PIN number for the SCL (serial clock) line.

  • sda – PIN number for the SDA (serial data) line.

  • id – The default value of -1 selects a software implementation of I2C which can work (in most cases) with arbitrary pins for SCL and SDA. If id is -1 then scl and sda must be specified. Other allowed values for id depend on the particular port/board, and specifying scl and sda may or may not be required or allowed in this case.

  • baudrate – Port frequency/clock rate (default: 400 kHz).

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

i2c_read(address: int, size: int, **kwargs) → str[source]#

Read data from the I2C bus.

Parameters:
Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

i2c_scan(**kwargs) → List[int][source]#

Scan for device addresses on the I2C bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.i2c_open() and platypush.plugins.esp.EspPlugin.execute().

Returns:

List of 7-bit addresses.

i2c_start(**kwargs)[source]#

Generate a START condition on an I2C bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.i2c_open() and platypush.plugins.esp.EspPlugin.execute().

Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

i2c_stop(**kwargs)[source]#

Generate a STOP condition on an I2C bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.i2c_open() and platypush.plugins.esp.EspPlugin.execute().

Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

i2c_write(address: int, data: str, binary: bool = False, **kwargs)[source]#

Write data to the I2C bus.

Parameters:
Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

listdir(directory: str = '/', **kwargs) → List[str][source]#

List the content of a directory.

Parameters:
mkdir(directory: str, **kwargs)[source]#

Create a directory.

Parameters:
pin_off(pin: int | str, pull_up: bool = False, **kwargs)[source]#

Set the specified PIN to LOW.

Parameters:
pin_on(pin: int | str, pull_up: bool = False, **kwargs)[source]#

Set the specified PIN to HIGH.

Parameters:
pin_read(pin: int | str, out: bool = False, pull_up: bool = False, **kwargs) → bool[source]#

Get the ON/OFF value of a PIN.

Parameters:

  • pin – GPIO PIN number or configured name.

  • out – Treat the PIN as an output PIN - e.g. if you usually write to it and now want to read the value. If not set, then the PIN will be treated as an input PIN.

  • pull_up – Set to True if the PIN has a (weak) pull-up resistor attached.

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

pin_toggle(pin: int | str, pull_up: bool = False, **kwargs)[source]#

Toggle a PIN state - to HIGH if LOW, to LOW if HIGH.

Parameters:
pwm_duty(pin: int | str, duty: int | None = None, **kwargs) → int | None[source]#

Get/set the duty cycle of a PWM PIN.

Parameters:
pwm_freq(pin: int | str, freq: int | None = None, **kwargs) → int | None[source]#

Get/set the frequency of a PWM PIN.

Parameters:
pwm_off(pin: int | str, **kwargs)[source]#

Turn off a PWM PIN.

Parameters:
pwm_on(pin: int | str, freq: int | None = None, duty: int | None = None, **kwargs)[source]#

Set the specified PIN to HIGH.

Parameters:
remove(file: str, **kwargs)[source]#

Remove a file.

Parameters:
rename(name: str, new_name: str, **kwargs)[source]#

Rename a file or directory.

Parameters:
reset(**kwargs)[source]#

Perform a device reset, similar to the user pushing the RESET button. :param kwargs: Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

rmdir(directory: str, **kwargs)[source]#

Remove a directory.

Parameters:
set_freq(freq: int, **kwargs)[source]#

Set the frequency of the device. :param freq: New frequency in Hz. :param kwargs: Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

set_ntp_time(**kwargs)[source]#

Set the device time using an NTP server.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

set_password(new_password: str, **kwargs)[source]#

Change the WebREPL password for the device.

Parameters:
sleep(seconds: float, **kwargs)[source]#

Perform a software sleep (i.e. time.sleep()).

Parameters:
soft_reset(**kwargs)[source]#

Performs a soft reset of the interpreter, deleting all Python objects and resetting the Python heap. :param kwargs: Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

soft_sleep(seconds: float | None = None, **kwargs)[source]#

Stops execution in an attempt to enter a low power state. A light-sleep has full RAM and state retention. Upon wake execution is resumed from the point where the sleep was requested, with all subsystems operational.

Parameters:
spi_close(**kwargs)[source]#

Turn off an SPI bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.spi_open() and platypush.plugins.esp.EspPlugin.execute().

spi_open(id=1, baudrate: int = 1000000, polarity: int = 0, phase: int = 0, bits: int = 8, sck: int | None = None, mosi: int | None = None, miso: int | None = None, **kwargs)[source]#

Open a connection to an SPI port. Note that sck, mosi and miso parameters are only allowed if you’re setting up a software managed SPI connection. If you’re using the hardware SPI implementation then those PINs are pre-defined depending on the model of your board.

Parameters:

  • id – Values of id depend on a particular port and its hardware. Values 0, 1, etc. are commonly used to select hardware SPI block #0, #1, etc. Value -1 can be used for bit-banging (software) implementation of SPI (if supported by a port).

  • baudrate – Port baudrate/SCK clock rate (default: 1 MHz).

  • polarity – It can be 0 or 1, and is the level the idle clock line sits at.

  • phase – It can be 0 or 1 to sample data on the first or second clock edge respectively.

  • bits – Number of bits per character. It can be 7, 8 or 9.

  • sck – SCK PIN number.

  • mosi – MOSI PIN number.

  • miso – MISO PIN number.

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

spi_read(size: int, **kwargs) → str[source]#

Read from an SPI bus.

Parameters:
Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

spi_write(data: str, binary: bool = False, **kwargs)[source]#

Write data to an SPI bus.

Parameters:
uart_close(**kwargs)[source]#

Turn off the UART bus.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.uart_open() and platypush.plugins.esp.EspPlugin.execute().

uart_open(id=1, baudrate: int | None = 9600, bits: int | None = 8, parity: int | None = None, stop: int = 1, tx_pin: int | None = None, rx_pin: int | None = None, timeout: float | None = None, timeout_char: float | None = None, **kwargs)[source]#

Open a connection to a UART port.

Parameters:

  • id – Bus ID (default: 1).

  • baudrate – Port baudrate (default: 9600).

  • bits – Number of bits per character. It can be 7, 8 or 9.

  • parity – Parity configuration. It can be None (no parity), 0 (even) or 1 (odd).

  • stop – Number of stop bits. It can be 1 or 2.

  • tx_pin – Specify the TX PIN to use.

  • rx_pin – Specify the RX PIN to use.

  • timeout – Specify the time to wait for the first character in seconds.

  • timeout_char – Specify the time to wait between characters in seconds.

  • kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

uart_read(size: int | None = None, **kwargs) → str[source]#

Read from a UART interface.

Parameters:
Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

uart_readline(**kwargs) → str[source]#

Read a line (any character until newline is found) from a UART interface.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.uart_open() and platypush.plugins.esp.EspPlugin.execute().

Returns:

String representation of the read bytes, or base64-encoded representation if the data can’t be decoded to a string.

uart_send_break(**kwargs)[source]#

Send a break condition to a UART bus. This drives the bus low for a duration longer than required for a normal transmission of a character.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.uart_open() and platypush.plugins.esp.EspPlugin.execute().

uart_write(data: str, binary: bool = False, **kwargs)[source]#

Write data to the UART bus.

Parameters:
unique_id(**kwargs) → str[source]#

Get the unique ID of the device. t will vary from a board/SoC instance to another, if underlying hardware allows. Length varies by hardware (so use substring of a full value if you expect a short ID). In some MicroPython ports, ID corresponds to the network MAC address..

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

urandom(size: int = 1, **kwargs) → List[int][source]#

Get randomly generated bytes.

Parameters:
wifi_config(ip: str | None = None, netmask: str | None = None, gateway: str | None = None, dns: str | None = None, **kwargs) → dict | None[source]#

Get or set network properties for the WiFi interface.

If called with no arguments it will return the configuration of the interface.

Parameters:
Returns:

{
  "active": true,
  "channel": 6,
  "dns": "1.1.1.1",
  "essid": "MyNetwork",
  "gateway": "192.168.1.1",
  "hidden": "Whether the Wi-Fi network is hidden.",
  "ip": "192.168.1.10",
  "mac": "00:11:22:33:44:55",
  "netmask": "255.255.255.0"
}

wifi_connect(essid: str, passphrase: str, **kwargs)[source]#

Connect the device WiFi interface to the specified access point.

Parameters:
wifi_disable(**kwargs)[source]#

Disable the device WiFi interface.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

wifi_disconnect(**kwargs)[source]#

Disconnect from the currently connected WiFi network

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

wifi_enable(**kwargs)[source]#

Enable the device WiFi interface.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

wifi_scan(**kwargs) → List[dict][source]#

Scan the available networks.

Parameters:

kwargs – Parameters to pass to platypush.plugins.esp.EspPlugin.execute().

Returns:

[
  {
    "auth_mode": 3,
    "bssid": "00:11:22:33:44:55",
    "channel": 6,
    "essid": "MyNetwork",
    "hidden": "Whether the Wi-Fi network is hidden.",
    "rssi": -50
  }
]

Platypush documentation