# `LIS3DH.Fifo`

FIFO protocol encoding and decoding for the LIS3DH.

The chip has a 32-level FIFO. Each level holds one X/Y/Z sample (6 bytes
total, all three axes read out from `OUT_X_L..OUT_Z_H`). Four FIFO modes
are supported, selected by `FIFO_CTRL_REG.FM[1:0]`:

  * `:bypass` — FIFO disabled. Reads of `OUT_*` return the latest sample
    live, no buffering.
  * `:fifo` — fills until full (32 samples) and stops collecting until the
    buffer is reset (by re-entering Bypass).
  * `:stream` — overwrites oldest sample once full (continuous streaming).
  * `:stream_to_fifo` — runs in Stream until an interrupt on the chosen
    trigger pin, then switches to FIFO mode (useful for capturing the
    history around an event).

The watermark interrupt fires when the number of stored samples reaches
`FTH[4:0] + 1`. Overrun (full) is a separate flag.

References: *LIS3DH Datasheet DocID17530 Rev 2* §5.1 and §8.19.

# `mode`

```elixir
@type mode() :: :bypass | :fifo | :stream | :stream_to_fifo
```

FIFO operating mode for `FIFO_CTRL_REG.FM`.

# `source_flags`

```elixir
@type source_flags() :: %{
  watermark_reached: boolean(),
  overrun: boolean(),
  empty: boolean(),
  stored: 0..32
}
```

Decoded FIFO source register flags.

# `trigger`

```elixir
@type trigger() :: :int1 | :int2
```

Trigger pin used by Stream-to-FIFO mode (and not used by the others).

# `watermark`

```elixir
@type watermark() :: 1..32
```

Watermark threshold (number of stored samples that triggers the WTM flag).

# `decode_fifo_ctrl_reg`

```elixir
@spec decode_fifo_ctrl_reg(<<_::8>>) :: %{
  mode: mode(),
  trigger: trigger(),
  watermark: watermark()
}
```

Decode a `FIFO_CTRL_REG` byte into a map of its fields.

# `decode_fifo_src_reg`

```elixir
@spec decode_fifo_src_reg(<<_::8>>) :: source_flags()
```

Decode the read-only `FIFO_SRC_REG` byte.

# `encode_fifo_ctrl_reg`

```elixir
@spec encode_fifo_ctrl_reg(keyword()) :: <<_::8>>
```

Encode a `FIFO_CTRL_REG` byte from keyword options.

## Options

  * `:mode` — `t:mode/0` (required).
  * `:trigger` — `t:trigger/0` (default `:int1`). Only meaningful in
    `:stream_to_fifo` mode; ignored otherwise.
  * `:watermark` — `t:watermark/0` (default `16`). Stored as `watermark - 1`
    in the 5-bit FTH field.

---

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