# `Wafer.Chip`
[🔗](https://harton.dev/james/wafer/src/branch/main/lib/wafer/chip.ex#L1)

A `Chip` is a physical peripheral with registers which can be read from and
written to.

Rather than interacting with this protocol directly, it's a lot easier to use
the macros in `Wafer.Registers` to do it for you.

## Deriving

If you're implementing your own `Conn` type which simply delegates to one of
the lower level drivers then you can derive this protocol automatically:

```elixir
defmodule MyConnection do
  @derive Wafer.Chip
  defstruct [:conn]
end
```

If your type uses a key other than `conn` for the inner connection you can
specify it while deriving:

```elixir
defmodule MyConnection do
  @derive {Wafer.Chip, key: :i2c_conn}
  defstruct [:i2c_conn]
end
```

## A note on SPI devices

You will have to manually implement this protocol for SPI devices as there is
no conventional way to read and write registers over SPI and every device has
their own way of implementing an SPI instruction set.

# `bytes`

```elixir
@type bytes() :: non_neg_integer()
```

# `register_address`

```elixir
@type register_address() :: non_neg_integer()
```

# `t`

```elixir
@type t() :: term()
```

All the types that implement this protocol.

# `read_register`

```elixir
@spec read_register(Wafer.Conn.t(), register_address(), bytes()) ::
  {:ok, data :: binary()} | {:error, reason :: any()}
```

Read the register at the specified address.

## Arguments

  - `conn` a type which implements the `Wafer.Conn` behaviour.
  - `register_address` the address of the register to read from.
  - `bytes` the number of bytes to read from the register.

## Example

    iex> {:ok, conn} = Circuits.I2C.acquire(bus: "i2c-1", address: 0x68)
    ...> Chip.read_register(conn, 0, 1)
    {:ok, <<0>>}

# `swap_register`

```elixir
@spec swap_register(Wafer.Conn.t(), register_address(), new_data :: binary()) ::
  {:ok, data :: binary(), t()} | {:error, reason :: any()}
```

Perform a swap with the register at the specified address.  With some drivers
this is atomic, and with others it is implemented as a register read followed
by a write.

## Arguments

  - `conn` a type which implements the `Wafer.Conn` behaviour.
  - `register_address` the address of the register to swap.
  - `new_data` the data to write to the register.

## Returns

The data that was previously in the register.

## Example

    iex> {:ok, conn} = Circuits.I2C.acquire(bus: "i2c", address: 0x68)
    ...> Chip.swap_register(conn, 0, <<1>>)
    {:ok, <<0>>, conn}

# `write_register`

```elixir
@spec write_register(Wafer.Conn.t(), register_address(), data :: binary()) ::
  {:ok, t()} | {:error, reason :: any()}
```

Write to the register at the specified address.

## Arguments

  - `conn` a type which implements the `Wafer.Conn` behaviour.
  - `register_address` the address of the register to write to.
  - `data` a bitstring or binary of data to write to the register.

## Example

    iex> {:ok, conn} = Circuits.I2C.acquire(bus: "i2c", address: 0x68)
    ...> Chip.write_register(conn, 0, <<0>>)
    {:ok, conn}

---

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