# Enigma Witness Vault Wiring

This document defines the default wiring for the Raspberry Pi Zero 2 W Witness Vault appliance. Keep all Pi GPIO signals at 3.3 V logic. The Pi GPIO header is not 5 V tolerant.

Hard rule: a breakout may advertise `3-5 V` power compatibility and still expose signal pins that can damage the Pi if pulled to 5 V. For this appliance, SDA, SCL, SPI, button, IRQ, reset, and all other GPIO-connected lines must be 3.3 V logic.

Short form warning for labels and reviews: 3.3V GPIO only.

## Electrical rules

- Power the ATECC608A and SSD1306 OLED from Pi 3.3 V.
- Use a common ground for every module.
- Do not connect 5 V module outputs to Pi GPIO.
- Keep I2C leads short. If a lid-mounted OLED makes the run longer, route SDA with ground and SCL with ground.
- Avoid conductive or carbon-filled filament near antennas and exposed contacts.
- Disconnect power before moving jumpers or changing PN532 mode switches.
- If a module has its own pull-ups, confirm they pull to 3.3 V, not 5 V.

## Raspberry Pi Zero 2 W I2C bus and Pi pin table

Default I2C bus uses GPIO2/GPIO3.

| Function | Pi GPIO | Physical pin | Connects to | Notes |
|---|---:|---:|---|---|
| 3.3 V | — | 1 | ATECC VCC, OLED VCC | Use 3.3 V for these I2C modules. |
| SDA1 | GPIO2 | 3 | ATECC SDA, OLED SDA | Shared I2C data. |
| SCL1 | GPIO3 | 5 | ATECC SCL, OLED SCL | Shared I2C clock. |
| Ground | — | 6 | ATECC GND, OLED GND | Any Pi ground pin is acceptable. |

Expected addresses:

| Module | Interface | Expected address | Notes |
|---|---|---:|---|
| ATECC608A breakout | I2C | `0x60` | Fixed on common Adafruit breakout. |
| SSD1306 OLED | I2C | `0x3C` or `0x3D` | Address depends on module solder bridge. |

If the OLED disappears when the ATECC is attached, inspect wiring first: swapped SDA/SCL, bad ground, and 5 V pull-ups are more likely than address conflict.

## ATECC608A sidecar wiring

| ATECC608A pin | Pi physical pin | Pi signal | Required |
|---|---:|---|---|
| VCC | 1 | 3.3 V | Yes |
| GND | 6, 9, 14, 20, 25, 30, 34, or 39 | Ground | Yes |
| SDA | 3 | GPIO2 / SDA1 | Yes |
| SCL | 5 | GPIO3 / SCL1 | Yes |

Sidecar semantics:

- The ATECC608A is a hardware key custody sidecar, not a full hardware security module.
- It can hold or derive device-bound key material depending on provisioning.
- It can support signing or attestation flows for vault records.
- It does not prove that any AI provider deleted data, forgot training influence, or told the truth.
- It does not make the enclosure tamper-proof.

## OLED wiring

| OLED pin label | Pi physical pin | Pi signal | Required |
|---|---:|---|---|
| VCC / VDD | 1 | 3.3 V | Yes |
| GND | 6, 9, 14, 20, 25, 30, 34, or 39 | Ground | Yes |
| SDA | 3 | GPIO2 / SDA1 | Yes |
| SCL / SCK | 5 | GPIO3 / SCL1 | Yes |

Notes:

- Many SSD1306 boards tolerate 3.3-5 V power, but the safe default for Pi GPIO is 3.3 V.
- Some boards label SCL as SCK. For I2C OLED modules, connect that pin to Pi SCL1.
- If the display flickers during NFC reads or Wi-Fi bursts, improve power/ground routing before changing software.

## Optional buttons

Use momentary normally-open buttons from GPIO to ground, with internal pull-ups enabled in software. Do not wire buttons to 5 V.

Suggested assignments:

| Button | Pi GPIO | Physical pin | Other side | Suggested action |
|---|---:|---:|---|---|
| Action / confirm | GPIO17 | 11 | Ground | Confirm export, rotate display page, or acknowledge warning. |
| Back / cancel | GPIO27 | 13 | Ground | Cancel local action or return to status page. |
| Service / safe mode | GPIO22 | 15 | Ground | Enter local-only/service mode when held at boot. |

Button wiring rules:

- One side of each switch goes to the GPIO pin.
- The other side goes to ground.
- Configure software pull-ups; pressed reads low.
- Add small labels inside the enclosure if buttons are service-only.
- If buttons are on the lid, use a connector and strain relief.

## Optional PN532 NFC I2C/SPI

PN532 boards vary. Confirm the exact board voltage and mode jumpers before wiring. Many compact boards can run I2C or SPI; choose one and do not connect both at the same time.

### PN532 over I2C

I2C is simplest but shares the bus with OLED and ATECC.

| PN532 pin | Pi physical pin | Pi signal | Notes |
|---|---:|---|---|
| VCC | 1 or board-required supply | 3.3 V preferred | Use only 5 V if the PN532 board explicitly level-shifts all logic to 3.3 V. |
| GND | 6 | Ground | Common ground required. |
| SDA | 3 | GPIO2 / SDA1 | Shared bus. |
| SCL | 5 | GPIO3 / SCL1 | Shared bus. |
| IRQ | Optional GPIO | Optional | Only if the driver uses interrupt mode. |
| RSTO / RESET | Optional GPIO | Optional | Useful for recovery from a wedged NFC board. |

PN532 I2C warnings:

- Check that PN532 pull-ups go to 3.3 V.
- Keep the antenna away from Pi Wi-Fi/BLE antenna and metal fasteners.
- If bus reliability suffers, move PN532 to SPI or shorten the lid harness.

### PN532 over SPI

SPI avoids loading the shared I2C bus. This is preferred when the OLED and ATECC must remain simple and deterministic.

| PN532 pin | Pi GPIO | Physical pin | Pi signal |
|---|---:|---:|---|
| VCC | — | 1 or board-required supply | 3.3 V preferred; see board warning. |
| GND | — | 6 | Ground |
| SCK | GPIO11 | 23 | SPI0 SCLK |
| MISO | GPIO9 | 21 | SPI0 MISO |
| MOSI | GPIO10 | 19 | SPI0 MOSI |
| SS / CS | GPIO8 | 24 | SPI0 CE0 |
| IRQ | GPIO24 | 18 | Optional interrupt |
| RESET | GPIO25 | 22 | Optional reset |

PN532 SPI warnings:

- Use 3.3 V logic on all SPI lines.
- Do not share CE0 with another SPI device unless you deliberately reassign chip-selects.
- Keep the SPI harness short and strain-relieved if routed to the lid.

## Power modes

Choose one power mode for the build and label it.

| Mode | Connection | Best for | Notes |
|---|---|---|---|
| USB power only | Pi power USB port from a 5 V supply | Standalone appliance on Wi-Fi or no-network mode | Simple. Use a reliable 5 V supply with enough current for Pi plus OLED/PN532. |
| USB gadget to host | Pi USB data port to host computer | Demos, Windows host service, SSH over USB Ethernet | Can provide both power and data if host port supplies enough current. Avoid weak hubs. |
| Dedicated 5 V input | Regulated 5 V feed to Pi 5 V/GND pins or power board | Enclosed appliance integration | Only use a regulated, protected 5 V input. Do not backfeed host USB unexpectedly. |
| Bench/service power | Known-good USB supply with lid open | Bring-up and diagnostics | Keep this mode for assembly and recovery. |

Power notes:

- Pi 5 V power is separate from GPIO logic voltage. GPIO remains 3.3 V only.
- If using both external 5 V and USB to a host, design for backfeed protection or use a data-only USB cable.
- If PN532 range collapses during reads, check 5 V sag and ground routing.

## Windows host notes

For USB gadget Ethernet demos on Windows:

- Use a data-capable USB cable connected to the Pi USB data/OTG port, not only the power port.
- Windows may enumerate the Pi as a USB Ethernet/RNDIS-style adapter after the Pi gadget configuration is enabled.
- If Windows does not assign a useful address, set a static address on the Windows adapter and the Pi gadget interface in the same private subnet.
- Keep Wi-Fi disabled when demonstrating no-network mode; USB gadget Ethernet is a local cable link, not proof that the device has no other network path unless Wi-Fi/BLE and other interfaces are also disabled by configuration.

## Pre-power checklist

Before first power:

1. Confirm ATECC VCC is on 3.3 V.
2. Confirm OLED VCC is on 3.3 V.
3. Confirm PN532 voltage and logic mode match the chosen wiring.
4. Confirm all grounds are common.
5. Confirm no GPIO is connected to 5 V.
6. Confirm SDA/SCL are not swapped.
7. Confirm button pins short to ground only when pressed.
8. Confirm no loose wire strands or screws can touch the Pi header.