@spec claim_gpio_pin(id(), pin(), pin_direction(), 0..1) :: :ok | {:error, term()}

Claims pin for GPIO use in the given direction. Fails if the pin is already claimed, if it's reserved by the active protocol, or if pin is out of range.

On success the pin is initialised — direction set, and for outputs the initial value driven.

@spec claim_mode(id(), :i2c | :spi, [pin()]) ::
  :ok | {:error, {:mode_busy, mode()} | {:pin_busy, pin()}}

Claims one of the mutually-exclusive protocol modes for the chip.

Returns :ok if the chip is currently unclaimed (or already claimed in the requested mode), or {:error, {:mode_busy, current_mode}} otherwise. Also fails with {:error, {:pin_busy, pin}} if any currently-open GPIO pin would conflict with the new mode.

extra_pins lets a backend reserve additional pins beyond the protocol's defaults — e.g. the I2C backend reserves AD7 when clock stretching is enabled, so a GPIO consumer can't grab the SCL-feedback pin.

@spec find_or_start(
  CircuitsFT232H.USB.Descriptor.t(),
  keyword()
) :: {:ok, pid()} | {:error, term()}

Starts a Device under CircuitsFT232H.DeviceSupervisor if one isn't already running for the descriptor's id.

Returns the existing pid if one is found. Use this from the I2C/SPI/GPIO backends — multiple buses may map to the same physical chip.

@spec gpio_pin_direction(id(), pin()) :: pin_direction() | nil

Returns the direction currently configured for pin, or nil if the pin isn't open.

@spec id_for(CircuitsFT232H.USB.Descriptor.t()) :: id()

Returns the canonical id for a USB descriptor.

@spec mode(id()) :: mode()

Returns the current protocol mode the chip is locked into.

@spec protocol_pins(mode()) :: [pin()]

Returns the list of pins reserved by the given protocol mode. Pins outside this list are available for GPIO use.

@spec read_gpio_bytes(id()) :: {:ok, {byte(), byte()}} | {:error, term()}

Reads the current state of the low-byte (ADBUS0..7) and high-byte (ACBUS0..7) ports in a single USB round-trip. Used by the GPIO poller to detect edges across many pins without paying per-pin latency.

@spec read_gpio_pin(id(), pin()) :: 0..1 | {:error, term()}

Reads the current logic level of a previously-opened GPIO pin.

@spec release_gpio_pin(id(), pin()) :: :ok

Releases a previously-claimed GPIO pin and switches it back to input.

@spec release_mode(id()) :: :ok

Releases whichever mode the chip is currently locked into.

@spec set_gpio_pin_direction(id(), pin(), pin_direction()) :: :ok | {:error, term()}

Changes the direction of an already-opened GPIO pin. The pin keeps its current driven value when switching to output.

@spec start_link(keyword()) :: GenServer.on_start()

Starts a Device server for the FT232H described by :descriptor.

Registers under the device's id in CircuitsFT232H.Registry. Subsequent callers can locate the server via whereis/1 or by referring to it by id in any of the public functions on this module.

Options:

• :descriptor (required) — the CircuitsFT232H.USB.Descriptor for the chip.
• :latency_ms (default 16) — USB latency timer.

@spec stop(id()) :: :ok

Stops the Device server for the given id.

@spec transaction(id(), iodata(), non_neg_integer(), timeout()) ::
  :ok | {:ok, binary()} | {:error, term()}

Sends command (an MPSSE byte stream) to the chip and optionally reads response_length bytes back.

command may be any iodata. If response_length is 0 the call returns :ok once the bytes have been queued to the chip. Otherwise it returns {:ok, binary} of exactly response_length payload bytes (the USB status prefix is stripped).

Use this for protocol-level MPSSE sequences. For pin-level operations, prefer write_gpio_pin/3, read_gpio_pin/2, and friends — they share the Device's pin-state tracking so GPIO and protocol traffic don't trample each other's bytes.

@spec validate(id()) :: :ok | {:error, term()}

Verifies the chip is in MPSSE mode and responding to commands by issuing an unrecognised opcode and checking for the standard 0xFA <opcode> echo.

@spec whereis(id()) :: {:ok, pid()} | {:error, :not_started}

Finds the pid of the Device server with the given id, if one is running.

@spec write_gpio_pin(id(), pin(), 0..1) :: :ok | {:error, term()}

Writes value (0 or 1) to a previously-opened GPIO output pin.