# `EHLS.GPIO`
[🔗](https://github.com/elixir-hls/elixir-hls/blob/v0.1.0/lib/ehls/backend/gpio.ex#L1)

Pins read and written from Elixir: generic, knowing no board; a block package of the LiteX SoC
backend (FPGA side: `priv/backend/litex/ehls_gpio.py`).

Not everything between the CPU and the FPGA is a stream. An LED or a switch has only a current
value, which a later value simply overwrites, so it needs no instance and no process:
`EHLS.GPIO` is a package whose pins are read and written with plain function calls. What must not
be lost, such as a button press, is an event: a pin's changes published by an instance (below).

```elixir
use EHLS, blocks: [{EHLS.GPIO,
  out:   [relay: "j5:3"],
  in:    [door: {"j5:4", pull: :up}],
  inout: [sda: {"j5:5", pull: :up}],
  board: [:led0, :button0]}]

EHLS.GPIO.write(:relay, 1)
EHLS.GPIO.read(:door)
EHLS.GPIO.direction(:sda, :out)    # inout only, while running
```

- **Direction:** decides the circuit at synthesis. Only an `inout` has a tristate buffer and can
  change direction while running. It starts as an input, driving nothing; a `write` meanwhile
  is kept for when it turns to an output.
- **Options per pin** (`{pin, options}`): `pull: :up | :down | :none` (a pin constraint, fixed at
  build time) and `active_low: true` (values inverted at the pin, so that 1 means on).
- **`board:`** names the target's parts. Their pins, pulls and polarity come from the target
  (`EHLS_BOARD_GPIO`, a JSON file), so application code does not depend on the board.
- **Errors:** options that cannot be built stop the compile; so does a call with a literal name
  that cannot work (`mix ehls.compile`). At run time a call returns `{:error, reason}`.
- **Events:** a pin's changes are published by an instance, each edge with its exact kind and the time
  it came (`EHLS.Pipeline`, "Events"):

  ```elixir
  definstance door do
    changes(:door, :both) |> EHLS.PubSub.broadcast(:door)
  end

  EHLS.PubSub.subscribe(:door, timestamps: true)   # {:door, 1 | 0, t} for each edge
  ```

  A mechanical switch bounces, so one press can bring several events: debounce in the instance
  (`sample` below), or take them with `active: :once`.
- **In an instance:** `changes(pin, edge)` (`:rising`, `:falling`, `:both`) is a source: one value per
  edge, the pin's new level, without the CPU. An edge arriving before the next function in the pipe took the last
  value is not counted, and a mechanical switch's bounces are edges. `hold(name)`, a built-in block,
  keeps the latest value as a level, read with `f(:value, name)`; it is 0 from reset or `:start` until
  the first value. Together, a counter of button presses in the FPGA:

  ```elixir
  defhls count(_press :: u1, n :: u16) :: {u16, u16} do
    {n + 1, n + 1}
  end

  definstance presses do
    changes(:button0, :rising) |> transform(0, &count/2) |> hold(:count)
  end

  presses(:value, :count)
  ```

- **Reading a switch:** `sample(pin)` reads the pin's level at each value of the stream, so with a slow
  source the bounces are not seen, and an ordinary function decides what a press is. `pin_out(pin)`
  puts the low bit of the latest value on an `:out`, 0 from each start until the first value; the pin
  is then no more the CPU's to write, and a literal `write` to it stops `mix ehls.compile`.

  ```elixir
  definstance presses do
    ticks(1000) |> sample(:button0) |> transform({0, 0}, &debounce/2) |> transform(0, &count/2) |> pin_out(:led1)
  end
  ```

- **A pin's level as an argument:** in a `definstance`, `EHLS.GPIO.read(pin)` as an argument of a function
  placed in the stream is the pin's level, read when the function takes a value (`EHLS.Pipeline`,
  "Instances of levels"); an out pin gives what is written to it.

  ```elixir
  defhls gate(x :: s16, on :: u1) :: s16 do
    if on == 1, do: x, else: 0
  end

  definstance gated(words) do
    words |> map(&gate(&1, EHLS.GPIO.read(:button0)))
  end
  ```

- **Limits:** one module declares the pins, 32 pins at most. Calls from Elixir are slow compared
  with the circuit: a bus at speed belongs in a block with its own circuit.

A sample application: [`gpio_demo.ex`](https://github.com/elixir-hls/atomvm-tang25k-hls/blob/main/examples/lib/gpio_demo.ex)
in atomvm-tang25k-hls, the board's LEDs and buttons, and
[`button_counter.ex`](https://github.com/elixir-hls/atomvm-tang25k-hls/blob/main/examples/lib/button_counter.ex), a counter of button presses with `debounce`.

# `direction`

Turns an `:inout` pin into an `:out` or `:in`: `:ok`, or `{:error, reason}`.

# `read`

The pin's level, 0 or 1 (of an `:out`: the value written), or `{:error, reason}`.

# `write`

Sets an `:out` or `:inout` pin to 0 or 1: `:ok`, or `{:error, reason}`.

---

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