# dakotawolfi/collar-pet architecture

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

- Interactive diagram: https://gitdiagram.com/dakotawolfi/collar-pet
- Repository: https://github.com/dakotawolfi/collar-pet

## Overview

CollarPet is a wearable pet-computing prototype: the Orange Pi runtime combines sensor and connection inputs into reactive behaviour, while the ESP32 handles real-time hardware work and several companion interfaces expose status and controls. The README documents major integrations and responsibilities; sampled source is partial, so links for unsampled subsystems follow those documented roles rather than presumed implementation details.

Main entry points: [`pi/collarpet.py`](https://github.com/dakotawolfi/collar-pet/blob/main/pi/collarpet.py) (CollarPet runtime), [`esp32/CollarPet_ESP32S3_v2_4_HotPlug_PPG.ino`](https://github.com/dakotawolfi/collar-pet/blob/main/esp32/CollarPet_ESP32S3_v2_4_HotPlug_PPG.ino) (ESP32 coprocessor), [`remote/collarpet_remote.ino`](https://github.com/dakotawolfi/collar-pet/blob/main/remote/collarpet_remote.ino) (LoRa remote firmware), [`tools/fan/collarpet-fan.py`](https://github.com/dakotawolfi/collar-pet/blob/main/tools/fan/collarpet-fan.py) (Thermal fan control)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Wearable runtime"]
  node_runtime["CollarPet runtime<br/>[collarpet.py]"]
  node_bleproxy["BLE socket client"]
  node_epaper["E-paper display drivers"]
end

subgraph group_interfaces["Companion interfaces"]
  node_pt35dash["PT35 dashboard<br/>[dashboard.py]"]
  node_pt35link["PT35 link dashboard"]
  node_training["PetMind training UI"]
  node_remote["LoRa remote firmware"]
end

subgraph group_intelligence["Recognition and behaviour"]
  node_music["Song recognition<br/>[songlib.py]"]
  node_musicfeel["Song reactions<br/>[music_feel.py]"]
  node_petmind["PetMind inference<br/>[petmind_nn_v0_3.py]"]
end

subgraph group_hardware["Hardware and integrations"]
  node_esp32["ESP32 coprocessor"]
  node_sensors["Wearable sensors"]
  node_outputs["LEDs and haptics"]
  node_gear["Tail and ear gear"]
  node_fan["Thermal fan control<br/>[collarpet-fan.py]"]
end

node_person(("Wearer"))
node_phone(("Phone BLE owner"))
node_terminaluser(("PT35 user"))

node_sensors -->|"supply readings"| node_esp32
node_esp32 -->|"UART data"| node_runtime
node_runtime -->|"hardware commands"| node_esp32
node_esp32 -->|"drive outputs"| node_outputs
node_runtime -->|"update display"| node_epaper
node_runtime -->|"recognize songs"| node_music
node_runtime -->|"trigger reactions"| node_musicfeel
node_runtime -->|"infer behaviour"| node_petmind
node_runtime -->|"request BLE operations"| node_bleproxy
node_bleproxy -->|"scan and control"| node_gear
node_phone -.->|"connect when idle"| node_gear
node_person -->|"use controls"| node_remote
node_remote -->|"send actions"| node_runtime
node_runtime -->|"publish state"| node_remote
node_terminaluser -->|"view and control"| node_pt35dash
node_pt35dash -->|"request status and actions"| node_runtime
node_pt35link -->|"discover and connect"| node_runtime
node_terminaluser -->|"label events"| node_training
node_training -->|"record training events"| node_runtime
node_fan -->|"read temperatures"| node_sensors
node_fan -->|"set fan state"| node_outputs

click node_runtime "https://github.com/dakotawolfi/collar-pet/blob/main/pi/collarpet.py"
click node_bleproxy "https://github.com/dakotawolfi/collar-pet/blob/main/pi/collarpet_ble_client.py"
click node_epaper "https://github.com/dakotawolfi/collar-pet/blob/main/pi/epaper_driver_select.py"
click node_pt35dash "https://github.com/dakotawolfi/collar-pet/blob/main/pt35/link/dashboard.py"
click node_pt35link "https://github.com/dakotawolfi/collar-pet/blob/main/pt35/link/collarpet_dashboard.py"
click node_training "https://github.com/dakotawolfi/collar-pet/tree/main/pt35/training"
click node_remote "https://github.com/dakotawolfi/collar-pet/blob/main/remote/collarpet_remote.ino"
click node_esp32 "https://github.com/dakotawolfi/collar-pet/blob/main/esp32/CollarPet_ESP32S3_v2_4_HotPlug_PPG.ino"
click node_music "https://github.com/dakotawolfi/collar-pet/blob/main/pi/songlib.py"
click node_musicfeel "https://github.com/dakotawolfi/collar-pet/blob/main/pi/music_feel.py"
click node_petmind "https://github.com/dakotawolfi/collar-pet/blob/main/pi/brain/petmind_nn_v0_3.py"
click node_fan "https://github.com/dakotawolfi/collar-pet/blob/main/tools/fan/collarpet-fan.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_runtime,node_bleproxy,node_epaper,node_terminaluser toneBlue
class node_pt35dash,node_pt35link,node_training,node_remote toneAmber
class node_music,node_musicfeel,node_petmind toneMint
class node_esp32,node_sensors,node_outputs,node_gear,node_fan toneRose
class node_person,node_phone toneIndigo
```

## Components

### Wearable runtime

- [CollarPet runtime](https://github.com/dakotawolfi/collar-pet/blob/main/pi/collarpet.py): `pi/collarpet.py`
- [BLE socket client](https://github.com/dakotawolfi/collar-pet/blob/main/pi/collarpet_ble_client.py): `pi/collarpet_ble_client.py`
- [E-paper display drivers](https://github.com/dakotawolfi/collar-pet/blob/main/pi/epaper_driver_select.py): `pi/epaper_driver_select.py`

### Companion interfaces

- [PT35 dashboard](https://github.com/dakotawolfi/collar-pet/blob/main/pt35/link/dashboard.py): `pt35/link/dashboard.py`
- [PT35 link dashboard](https://github.com/dakotawolfi/collar-pet/blob/main/pt35/link/collarpet_dashboard.py): `pt35/link/collarpet_dashboard.py`
- [PetMind training UI](https://github.com/dakotawolfi/collar-pet/tree/main/pt35/training): `pt35/training`
- [LoRa remote firmware](https://github.com/dakotawolfi/collar-pet/blob/main/remote/collarpet_remote.ino): `remote/collarpet_remote.ino`

### Recognition and behaviour

- [Song recognition](https://github.com/dakotawolfi/collar-pet/blob/main/pi/songlib.py): `pi/songlib.py`
- [Song reactions](https://github.com/dakotawolfi/collar-pet/blob/main/pi/music_feel.py): `pi/music_feel.py`
- [PetMind inference](https://github.com/dakotawolfi/collar-pet/blob/main/pi/brain/petmind_nn_v0_3.py): `pi/brain/petmind_nn_v0_3.py`

### Hardware and integrations

- [ESP32 coprocessor](https://github.com/dakotawolfi/collar-pet/blob/main/esp32/CollarPet_ESP32S3_v2_4_HotPlug_PPG.ino): `esp32/CollarPet_ESP32S3_v2_4_HotPlug_PPG.ino`
- **Wearable sensors**
- **LEDs and haptics**
- **Tail and ear gear**
- [Thermal fan control](https://github.com/dakotawolfi/collar-pet/blob/main/tools/fan/collarpet-fan.py): `tools/fan/collarpet-fan.py`

### Other components

- **Wearer**
- **Phone BLE owner**
- **PT35 user**

## Connections

- Wearable sensors → ESP32 coprocessor: supply readings
- ESP32 coprocessor → CollarPet runtime: UART data
- CollarPet runtime → ESP32 coprocessor: hardware commands
- ESP32 coprocessor → LEDs and haptics: drive outputs
- CollarPet runtime → E-paper display drivers: update display
- CollarPet runtime → Song recognition: recognize songs
- CollarPet runtime → Song reactions: trigger reactions
- CollarPet runtime → PetMind inference: infer behaviour
- CollarPet runtime → BLE socket client: request BLE operations
- BLE socket client → Tail and ear gear: scan and control
- Phone BLE owner → Tail and ear gear: connect when idle
- Wearer → LoRa remote firmware: use controls
- LoRa remote firmware → CollarPet runtime: send actions
- CollarPet runtime → LoRa remote firmware: publish state
- PT35 user → PT35 dashboard: view and control
- PT35 dashboard → CollarPet runtime: request status and actions
- PT35 link dashboard → CollarPet runtime: discover and connect
- PT35 user → PetMind training UI: label events
- PetMind training UI → CollarPet runtime: record training events
- Thermal fan control → Wearable sensors: read temperatures
- Thermal fan control → LEDs and haptics: set fan state