# johnscotttt/witrn_hid_api architecture

> Architecture diagram of the GitHub repository johnscotttt/witrn_hid_api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/johnscotttt/witrn_hid_api
- Repository: https://github.com/johnscotttt/witrn_hid_api

## Overview

WITRN HID is a small Python API for reading WITRN USB HID messages and decoding them into metadata. The main workflow is to open a device, read a 64-byte HID report, then dispatch it to general-message or USB-PD decoding. General reports are decoded locally; PD parsing and the shared metadata model come from usbpdparser. The README also documents metadata inspection, context helpers, and rendering. The graph reflects sampled core code and documented capabilities; external dependency internals are not shown.

Main entry points: [`witrnhid/core.py`](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py) (WITRN_DEV), [`witrnhid/__init__.py`](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/__init__.py) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_device["HID Access"]
  node_api["Public API<br/>[__init__.py]"]
  node_device_class["WITRN_DEV<br/>[core.py]"]
  node_hidapi["hidapi"]
end

subgraph group_decode["Message Decoding"]
  node_dispatch["auto_unpack<br/>[core.py]"]
  node_general_unpack["general_unpack<br/>[core.py]"]
  node_general_msg["General report decoder<br/>[core.py]"]
  node_pd_unpack["pd_unpack<br/>[core.py]"]
  node_parser["USB PD Parser"]
end

subgraph group_results["Metadata Tools"]
  node_metadata["metadata"]
  node_context_helpers["PDO/RDO helpers"]
  node_renderer["Metadata renderer"]
end

node_user(("Python caller"))
node_witrn_device["WITRN HID device"]

node_user -->|"imports"| node_api
node_user -->|"creates and calls"| node_device_class
node_device_class -->|"opens, reads, closes"| node_hidapi
node_hidapi -->|"accesses"| node_witrn_device
node_witrn_device -->|"HID reports"| node_hidapi
node_device_class -->|"unpacks"| node_dispatch
node_dispatch -->|"dispatches general"| node_general_unpack
node_dispatch -->|"dispatches PD"| node_pd_unpack
node_general_unpack -->|"decodes report"| node_general_msg
node_general_msg -->|"builds fields"| node_metadata
node_pd_unpack -->|"calls parse"| node_parser
node_parser -->|"returns parsed data"| node_metadata
node_user -->|"checks context"| node_context_helpers
node_user -->|"renders metadata"| node_renderer

click node_api "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/__init__.py"
click node_device_class "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py"
click node_dispatch "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py"
click node_general_unpack "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py"
click node_general_msg "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py"
click node_pd_unpack "https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_device_class,node_hidapi toneBlue
class node_dispatch,node_general_unpack,node_general_msg,node_pd_unpack,node_parser toneAmber
class node_metadata,node_context_helpers,node_renderer toneMint
class node_user,node_witrn_device toneIndigo
```

## Components

### HID Access

- [Public API](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/__init__.py): `witrnhid/__init__.py`
- [WITRN_DEV](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py): `witrnhid/core.py`
- **hidapi**

### Message Decoding

- [auto_unpack](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py): `witrnhid/core.py`
- [general_unpack](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py): `witrnhid/core.py`
- [General report decoder](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py): `witrnhid/core.py`
- [pd_unpack](https://github.com/johnscotttt/witrn_hid_api/blob/main/witrnhid/core.py): `witrnhid/core.py`
- **USB PD Parser**

### Metadata Tools

- **metadata**
- **PDO/RDO helpers**
- **Metadata renderer**

### Other components

- **Python caller**
- **WITRN HID device**

## Connections

- Python caller → Public API: imports
- Python caller → WITRN_DEV: creates and calls
- WITRN_DEV → hidapi: opens, reads, closes
- hidapi → WITRN HID device: accesses
- WITRN HID device → hidapi: HID reports
- WITRN_DEV → auto_unpack: unpacks
- auto_unpack → general_unpack: dispatches general
- auto_unpack → pd_unpack: dispatches PD
- general_unpack → General report decoder: decodes report
- General report decoder → metadata: builds fields
- pd_unpack → USB PD Parser: calls parse
- USB PD Parser → metadata: returns parsed data
- Python caller → PDO/RDO helpers: checks context
- Python caller → Metadata renderer: renders metadata