Esp32

A library for managing ESP32 firmware on Nerves and other Elixir systems. This package implements the ESP32 serial bootloader protocol and handles hardware reset and strapping pins to automate entry into bootloader mode.

Features

• Supports all families of ESP32 chips
• Two stage bootloader, including stub loading for flash programming
• Automatic discovery and reset of USB-connected ESP32 devices

Usage

To use Esp32, you need to provide the UART port and reset/boot options. For many development boards, you can use the automatic reset feature via DTR/RTS.

# Automatic discovery and reset (common for devboards via DTR/RTS)
{:ok, uart} = Esp32.connect("auto", auto_reset: true, baud_rate: 921600)

# Detect the chip family
{:ok, chip} = Esp32.detect_chip(uart)
IO.puts("Connected to: #{chip}")

# Flash a firmware file (patches header metadata if written to bootloader offset)
:ok = Esp32.flash_file(uart, "firmware.bin", 0x10000, reboot: true)

# Flash a raw binary blob
binary_data = <<...>>
:ok = Esp32.flash(uart, binary_data, 0x8000)

# Erase the entire flash chip
:ok = Esp32.erase(uart)

# Close the connection when done
Esp32.UART.close(uart)

Connection Options

When calling Esp32.connect/2, you can specify several options:

• :initial_baud_rate - The baud rate used for the initial synchronization and loading the flasher stub (default: 115200).
• :baud_rate - The target baud rate to use after the flasher stub is loaded. This is typically much higher (e.g., 921600) to speed up flashing.
• :auto_reset - When set to true, the library will use the DTR and RTS lines to automatically put the ESP32 into bootloader mode. This is common for most USB-based development boards.
• :reset - When set to false, the library will skip the hardware reset sequence and attempt to synchronize with an already running bootloader. (default: true).
• :reset_pin and :boot_pin - GPIO pin names to use for manual reset and strapping pin control (e.g., for custom Nerves hardware).

Common Firmware Offsets

When flashing your device, ensure you use the correct memory offsets. These offsets vary depending on the chip family:

Note: For chips with a 0x0 bootloader offset, the library automatically handles header patching if you use flash_file/4 at that address.

Installation

Add esp32 to your list of dependencies in mix.exs:

def deps do
  [
    {:esp32, "~> 0.1.0"},
  ]
end

Documentation can be generated with ExDoc and published on HexDocs. Once published, the docs can be found at https://hexdocs.pm/esp32.

License

MIT License. The ESP32 stub firmware binaries found in priv/stubs are from the esptool project and are licensed separately (GPL-2.0). Please see the source repository for more details