@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.

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

Detects the connected ESP32 chip type.

@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.

@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}.

@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)

@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)

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

Parses an ESP32 firmware image (.bin).

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

Reads a 32-bit register from the ESP32.

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

Synchronizes with the ESP32 bootloader.