# Aardvark I2C

Read and write I2C registers through a Total Phase Aardvark

- Category: Data acquisition
- Capabilities: Streams, Assets, Commands, Operations, Entities
- Runs on: Linux x64, Linux ARM64, macOS Apple silicon, macOS Intel, Windows x64

Read and write registers on any I2C chip through a **Total Phase Aardvark**
adapter. You describe the chip by pasting its register table from the
datasheet. No code needed.

## What you get

- **Live readings** — each polled register or named bit field is a channel,
  such as `/aardvark/i2c1/gpio/input` or `/aardvark/i2c1/gpio/output/led0`.
- **Writes** — registers marked `writable`, and their bit fields, accept
  values from Trellis via `ch.write(path, value)`. A bit-field write leaves
  the other bits alone. Every write is recorded.
- **One adapter per input**, named by its **Bus name**.

## Setup

1. Install the **Aardvark Software API** from totalphase.com and plug in the
   adapter. Phloem detects it over USB and offers a draft with its serial
   filled in. You still add the register map.
2. In **Inputs**, add **Total Phase Aardvark** and fill in:
   - **Bus name** — a short label, e.g. `i2c1`
   - **Adapter serial** — as printed on the unit, e.g. `2239-764425`. Leave
     empty to use the first adapter found.
   - **Peripherals** — the register map (JSON). For a PCA9554 I/O expander:

     ```json
     [{"name": "gpio", "address": 56,
       "registers": [
         {"alias": "input", "register": 0},
         {"alias": "output", "register": 1, "writable": true,
          "fields": {"led0": {"lsb": 0}}}
       ],
       "poll": ["input", "output.led0"]}]
     ```

     | Key | Value |
     |---|---|
     | `address` | 7-bit I2C address |
     | `addr_width_bytes` | `1` or `2` |
     | `registers` | each with `alias`, `register`, `transfer_bits` (default 8) |
     | `data_width_bits`, `data_lsb`, `signed` | optional |
     | `scale` | optional `{"gain": g, "offset": o}`; value = offset + gain × raw |
     | `endianness` | `big` (default) |
     | `unit`, `writable` | per register |
     | `fields` | `{"name": {"lsb": n, "width": w}}` |
     | `poll` | what to read (`alias` or `alias.field`); omit to read every register |

   - **Bus bitrate / pull-ups / target power** — the bus's electrical
     settings. The adapter rounds the bitrate to the nearest rate it supports.
3. Press **Test connection**. It reads the first polled register, so a pass
   means a chip answered on the bus.
4. Polled channels appear on **Live**. Writable registers are available in
   **Trellis**.

## Notes

- Without the Total Phase library, the connector tells you so.
- Register reads use a repeated START. Bit-field writes read, change and
  rewrite the whole register.
- Chips that take a command byte and reply, with no register addresses, are
  not supported.

## Supports

- Total Phase Aardvark I2C/SPI host adapter (I2C master, USB)
- Any register-based I2C peripheral via a pasted register map

## Connection fields

| Field | Type | Required | Notes |
|---|---|---|---|
| Bus name | Text | Yes |  |
| Adapter serial | Text | No |  |
| Peripherals (JSON register map) | Text | Yes |  |
| Bus bitrate (kHz) | Number | No |  |
| Internal pull-ups | One of | No |  |
| Target power | One of | No |  |
| Poll rate (Hz) | Number | No |  |