# `Esp32`
[🔗](https://github.com/gworkman/esp32/blob/main/lib/esp32.ex#L1)

ESP32 Serial Bootloader management library for Elixir and Nerves.

# `connect`

```elixir
@spec connect(
  String.t(),
  keyword()
) :: {:ok, pid()} | {:error, any()}
```

Connects to an ESP32 device, puts it in bootloader mode, and synchronizes.

Options:
- `:baud_rate` - Final baud rate for communication (default 115200)
- `:initial_baud_rate` - Initial sync baud rate used for loading the flasher stub (default 115200)
- `:use_stub` - If true, load the flasher stub (default true)
- `:reset` - If true, perform the reset into bootloader sequence (default true)
- `:auto_reset` - If true, use UART DTR/RTS signals for reset (default false)
- `:reset_pin` - GPIO pin name for ESP32 reset pin
- `:boot_pin` - GPIO pin name for ESP32 boot pin 

If `uart_port` is "auto", the library will attempt to find a connected ESP32.

# `detect_chip`

```elixir
@spec detect_chip(pid()) :: {:ok, atom()} | {:error, any()}
```

Detects the connected ESP32 chip type.

# `erase`

```elixir
@spec erase(
  pid(),
  keyword()
) :: :ok | {:error, any()}
```

Erases the entire SPI flash memory of the ESP device.

Note: This command is only supported when the flasher stub is loaded.
The operation can take up to 120 seconds depending on the flash chip.

# `find_port`

```elixir
@spec find_port() :: {:ok, String.t()} | {:error, :no_port_found}
```

Attempts to find a connected ESP32 or USB-to-Serial bridge.

Returns `{:ok, port}` if found, or `{:error, :no_port_found}`.

# `flash`

```elixir
@spec flash(pid(), binary(), integer(), keyword()) :: :ok | {:error, any()}
```

Flashes a binary to the ESP32 at the specified memory offset.

Options:
- `:is_stub` - Use stub protocol (default true)
- `:reboot` - Reboot after flash (default false)

# `flash_file`

```elixir
@spec flash_file(pid(), String.t(), integer(), keyword()) :: :ok | {:error, any()}
```

Flashes a firmware image file (.bin) to the ESP32.

This function reads the file from disk, performs a safety check to ensure
it is a valid ESP32 image, and then flashes it.

If the `offset` matches the chip's bootloader offset, the header is patched
with the provided `:flash_mode`, `:flash_freq`, and `:flash_size` options.

Options:
- `:flash_mode` - "qio", "qout", "dio", "dout" (default: "keep")
- `:flash_freq` - "40m", "26m", "20m", "80m" (default: "keep")
- `:flash_size` - "1MB", "2MB", "4MB", "8MB", "16MB" (default: "keep")
- `:is_stub` - Use stub protocol (default true)
- `:reboot` - Reboot after flash (default false)

# `parse_image`

```elixir
@spec parse_image(binary()) :: {:ok, map(), binary()} | {:error, any()}
```

Parses an ESP32 firmware image (.bin).

# `read_reg`

```elixir
@spec read_reg(pid(), integer()) :: {:ok, integer()} | {:error, any()}
```

Reads a 32-bit register from the ESP32.

# `sync`

```elixir
@spec sync(pid()) :: :ok | {:error, any()}
```

Synchronizes with the ESP32 bootloader.

---

*Consult [api-reference.md](api-reference.md) for complete listing*