@spec change_baud(Esp32.Device.t(), pos_integer()) ::
  {:ok, Esp32.Device.t()} | {:error, term()}

Switches the device to baud, then the host UART.

@spec command(Esp32.Device.t(), Esp32.Protocol.op(), binary(), keyword()) ::
  {:ok, non_neg_integer(), binary()} | {:error, term()}

Sends op and returns {:ok, value, data} once a matching, successful response arrives.

Options: :checksum (0), :timeout (3000 ms), :resp_data_len (0).

Error reasons, returned as {:error, reason}: {op, error_byte} for a failed status, {op, :short_response}, :timeout when no frame arrives, :no_response when 100 frames arrive without a matching response, {:unsupported_command, op} when the loader does not know the command.

@spec detect_chip(Esp32.Device.t()) :: {:ok, Esp32.Chip.name()} | {:error, term()}

Identifies the chip family from the security info, or the ROM magic register on older chips.

@spec erase_flash(Esp32.Device.t()) :: :ok | {:error, term()}

Erases the whole flash chip (stub only).

@spec flash_begin(Esp32.Device.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, pos_integer()} | {:error, term()}

Starts a flash write of size bytes at offset; the ROM erases the region up front.

Writes block seq, retrying up to three times.

@spec flash_block_size(Esp32.Device.t()) :: pos_integer()

Flash write block size: 0x4000 for the stub (0x800 over USB-OTG), 0x400 for the ROM.

@spec flash_end(Esp32.Device.t(), boolean()) :: :ok | {:error, term()}

Leaves flash mode; reboot? resets the chip instead of running the loader.

@spec flash_md5(Esp32.Device.t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, binary()} | {:error, term()}

MD5 digest of size bytes of flash at offset.

@spec get_security_info(Esp32.Device.t()) :: {:ok, map()} | {:error, term()}

Reads the security info block; chip_id is nil on chips that don't report one.

@spec load_stub(Esp32.Device.t()) :: {:ok, Esp32.Device.t()} | {:error, term()}

Uploads the flasher stub for device.chip into RAM and starts it.

@spec mem_end(Esp32.Device.t(), non_neg_integer()) :: :ok | {:error, term()}

Leaves RAM download mode and jumps to entry (0 to stay in the loader).

@spec ram_block_size(Esp32.Device.t()) :: pos_integer()

RAM block size: USB-OTG limits transfers to 0x800 bytes.

@spec spi_attach(Esp32.Device.t()) :: :ok | {:error, term()}

Attaches the SPI flash. Needed on the ROM loader; the stub does this itself.

@spec spi_set_params(Esp32.Device.t(), pos_integer()) :: :ok | {:error, term()}

Tells the loader the flash chip's size; the ROM assumes a small default otherwise.

@spec sync(Esp32.Device.t()) :: {:ok, boolean()} | {:error, term()}

Synchronizes with the loader and returns whether the flasher stub is already running: the ROM answers with non-zero values, the stub with zero.