# SPDX-FileCopyrightText: 2023 Frank Hunleth
#
# SPDX-License-Identifier: Apache-2.0

defprotocol Circuits.GPIO.Handle do
  @moduledoc """
  Handle for referring to GPIOs

  Use the functions in `Circuits.GPIO` to read and write to GPIOs.
  """

  alias Circuits.GPIO

  # Return the current GPIO state. For a group, this is an integer with one bit per line.
  @doc false
  @spec read(t()) :: GPIO.value()
  def read(handle)

  # Return dynamic GPIO configuration and status information.
  @doc false
  @spec status(t()) :: {:ok, GPIO.status()} | {:error, atom()}
  def status(handle)

  # Set the GPIO state. For a group, this is an integer with one bit per line.
  @doc false
  @spec write(t(), GPIO.value()) :: :ok
  def write(handle, value)

  # Change the direction of the GPIO
  @doc false
  @spec set_direction(t(), GPIO.direction()) :: :ok | {:error, atom()}
  def set_direction(handle, direction)

  # Change the pull mode of an input GPIO
  @doc false
  @spec set_pull_mode(t(), GPIO.pull_mode()) :: :ok | {:error, atom()}
  def set_pull_mode(handle, mode)

  # Set the drive mode
  @doc false
  @spec set_drive_mode(t(), GPIO.drive_mode()) :: :ok | {:error, atom()}
  def set_drive_mode(handle, mode)

  # Free up resources associated with the handle
  #
  # Well behaved backends free up their resources with the help of the Erlang
  # garbage collector. However, it is good practice for users to call
  # `Circuits.GPIO.close/1` (and hence this function) so that limited resources
  # are freed before they're needed again.
  @doc false
  @spec close(t()) :: :ok
  def close(handle)

  @doc false
  @spec set_interrupts(t(), GPIO.trigger(), GPIO.interrupt_options()) :: :ok | {:error, atom()}
  def set_interrupts(handle, trigger, options)

  # Subscribe to change notifications, returning the ref/tag that's included in messages
  @doc false
  @spec subscribe(t(), GPIO.subscribe_options()) :: {:ok, term()} | {:error, atom()}
  def subscribe(handle, options)

  # Stop change notifications started with subscribe/2
  @doc false
  @spec unsubscribe(t()) :: :ok | {:error, atom()}
  def unsubscribe(handle)
end