# tworjaga/esp32gotchi architecture

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

- Interactive diagram: https://gitdiagram.com/tworjaga/esp32gotchi
- Repository: https://github.com/tworjaga/esp32gotchi

## Overview

ESP32Gotchi is autonomous ESP32 firmware for passive Wi-Fi AP monitoring and WPA/WPA2 handshake capture, with PCAP and CSV output to microSD. Its principal workflow receives and queues Wi-Fi frames, parses them for APs and the four EAPOL handshake messages, then writes completed handshakes and periodic logs. GPS can supply location and UTC timestamps; the OLED, LED, and button provide device feedback and controls. The README documents the task layout and optional GPS capability; edges from unsampled firmware setup are limited to those documented relationships.

Main entry points: [`Cheapagotchi/sdlog.cpp`](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp) (SD writer task), [`Cheapagotchi/capture.cpp`](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp) (Packet capture), [`Cheapagotchi/gps.cpp`](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/gps.cpp) (GPS parser and clock), [`Cheapagotchi/Cheapagotchi.ino`](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/Cheapagotchi.ino) (Task setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Firmware runtime"]
  node_firmware["Task setup<br/>[Cheapagotchi.ino]"]
  node_state["Shared state<br/>[state.cpp]"]
  node_gps["GPS parser and clock<br/>[gps.cpp]"]
end

subgraph group_capture["Wi-Fi capture"]
  node_packetcapture["Packet capture<br/>[capture.cpp]"]
  node_packetqueue["Packet queue<br/>[capture.cpp]"]
  node_handshake["Handshake parser<br/>[handshake.cpp]"]
  node_aptable["AP registry<br/>[ap_table.cpp]"]
end

subgraph group_outputs["Storage outputs"]
  node_apqueue["AP log queue<br/>[capture.cpp]"]
  node_writer["SD writer task<br/>[sdlog.cpp]"]
  node_pcap["Handshake PCAP<br/>[pcap.cpp]"]
  node_aplog["AP CSV log<br/>[sdlog.cpp]"]
  node_stats["Stats CSV log<br/>[sdlog.cpp]"]
end

subgraph group_device["Device interface"]
  node_ui["OLED and controls<br/>[ui.cpp]"]
end

node_wifi(("Wi-Fi traffic"))
node_sdcard[("microSD card")]
node_gpsmodule(("GPS receiver"))
node_user(("Device user"))

node_firmware -.->|"starts task"| node_packetcapture
node_firmware -.->|"starts task"| node_writer
node_firmware -.->|"starts task"| node_ui
node_firmware -.->|"starts task"| node_gps
node_wifi -.->|"supplies frames"| node_packetcapture
node_packetcapture -->|"queues packets"| node_packetqueue
node_packetqueue -->|"processes packets"| node_handshake
node_packetcapture -->|"records new APs"| node_aptable
node_handshake -->|"records APs"| node_aptable
node_packetcapture -->|"queues AP logs"| node_apqueue
node_handshake -->|"queues completed slots"| node_writer
node_apqueue -->|"drains log queue"| node_writer
node_writer -->|"writes handshakes"| node_pcap
node_writer -->|"writes AP entries"| node_aplog
node_writer -->|"writes snapshots"| node_stats
node_pcap -->|"writes PCAP"| node_sdcard
node_aplog -->|"writes CSV"| node_sdcard
node_stats -->|"writes CSV"| node_sdcard
node_gpsmodule -.->|"sends NMEA"| node_gps
node_pcap -->|"gets UTC time"| node_gps
node_aplog -->|"gets timestamp"| node_gps
node_stats -->|"gets timestamp"| node_gps
node_gps -.->|"provides fix data"| node_ui
node_user -.->|"presses button"| node_ui
node_state -.->|"shares runtime state"| node_packetcapture
node_state -.->|"shares runtime state"| node_handshake
node_state -.->|"shares runtime state"| node_writer
node_state -.->|"supplies display state"| node_ui

click node_firmware "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/Cheapagotchi.ino"
click node_state "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/state.cpp"
click node_packetcapture "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp"
click node_packetqueue "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp"
click node_handshake "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/handshake.cpp"
click node_aptable "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/ap_table.cpp"
click node_apqueue "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp"
click node_writer "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp"
click node_pcap "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/pcap.cpp"
click node_aplog "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp"
click node_stats "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp"
click node_gps "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/gps.cpp"
click node_ui "https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/ui.cpp"

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_firmware,node_state,node_gps,node_user toneBlue
class node_packetcapture,node_packetqueue,node_handshake,node_aptable,node_sdcard toneAmber
class node_apqueue,node_writer,node_pcap,node_aplog,node_stats toneMint
class node_ui toneRose
class node_wifi,node_gpsmodule toneIndigo
```

## Components

### Firmware runtime

- [Task setup](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/Cheapagotchi.ino): `Cheapagotchi/Cheapagotchi.ino`
- [Shared state](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/state.cpp): `Cheapagotchi/state.cpp`
- [GPS parser and clock](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/gps.cpp): `Cheapagotchi/gps.cpp`

### Wi-Fi capture

- [Packet capture](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp): `Cheapagotchi/capture.cpp`
- [Packet queue](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp): `Cheapagotchi/capture.cpp`
- [Handshake parser](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/handshake.cpp): `Cheapagotchi/handshake.cpp`
- [AP registry](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/ap_table.cpp): `Cheapagotchi/ap_table.cpp`

### Storage outputs

- [AP log queue](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/capture.cpp): `Cheapagotchi/capture.cpp`
- [SD writer task](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp): `Cheapagotchi/sdlog.cpp`
- [Handshake PCAP](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/pcap.cpp): `Cheapagotchi/pcap.cpp`
- [AP CSV log](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp): `Cheapagotchi/sdlog.cpp`
- [Stats CSV log](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/sdlog.cpp): `Cheapagotchi/sdlog.cpp`

### Device interface

- [OLED and controls](https://github.com/tworjaga/esp32gotchi/blob/main/Cheapagotchi/ui.cpp): `Cheapagotchi/ui.cpp`

### Other components

- **Wi-Fi traffic**
- **microSD card**
- **GPS receiver**
- **Device user**

## Connections

- Task setup → Packet capture: starts task (evidence: `README.md`)
- Task setup → SD writer task: starts task (evidence: `README.md`)
- Task setup → OLED and controls: starts task (evidence: `README.md`)
- Task setup → GPS parser and clock: starts task (evidence: `README.md`)
- Wi-Fi traffic → Packet capture: supplies frames (evidence: `README.md`)
- Packet capture → Packet queue: queues packets (evidence: `Cheapagotchi/capture.cpp`)
- Packet queue → Handshake parser: processes packets (evidence: `Cheapagotchi/capture.cpp`)
- Packet capture → AP registry: records new APs (evidence: `Cheapagotchi/capture.cpp`)
- Handshake parser → AP registry: records APs (evidence: `Cheapagotchi/handshake.cpp`)
- Packet capture → AP log queue: queues AP logs (evidence: `Cheapagotchi/capture.cpp`)
- Handshake parser → SD writer task: queues completed slots (evidence: `Cheapagotchi/handshake.cpp`)
- AP log queue → SD writer task: drains log queue (evidence: `Cheapagotchi/sdlog.cpp`)
- SD writer task → Handshake PCAP: writes handshakes (evidence: `Cheapagotchi/sdlog.cpp`)
- SD writer task → AP CSV log: writes AP entries (evidence: `Cheapagotchi/sdlog.cpp`)
- SD writer task → Stats CSV log: writes snapshots (evidence: `Cheapagotchi/sdlog.cpp`)
- Handshake PCAP → microSD card: writes PCAP (evidence: `Cheapagotchi/pcap.cpp`)
- AP CSV log → microSD card: writes CSV (evidence: `Cheapagotchi/sdlog.cpp`)
- Stats CSV log → microSD card: writes CSV (evidence: `Cheapagotchi/sdlog.cpp`)
- GPS receiver → GPS parser and clock: sends NMEA (evidence: `README.md`)
- Handshake PCAP → GPS parser and clock: gets UTC time (evidence: `Cheapagotchi/pcap.cpp`)
- AP CSV log → GPS parser and clock: gets timestamp (evidence: `Cheapagotchi/sdlog.cpp`)
- Stats CSV log → GPS parser and clock: gets timestamp (evidence: `Cheapagotchi/sdlog.cpp`)
- GPS parser and clock → OLED and controls: provides fix data (evidence: `README.md`)
- Device user → OLED and controls: presses button (evidence: `README.md`)
- Shared state → Packet capture: shares runtime state
- Shared state → Handshake parser: shares runtime state
- Shared state → SD writer task: shares runtime state
- Shared state → OLED and controls: supplies display state
