# circuitsetup/time-circuits-display architecture

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

- Interactive diagram: https://gitdiagram.com/circuitsetup/time-circuits-display
- Repository: https://github.com/circuitsetup/time-circuits-display

## Overview

The repository contains firmware for CircuitSetup’s Time Circuits Display. Its central workflow is device startup and clock/time-travel operation, with keypad or network configuration, time sources and peripheral inputs, then display and audio output. The graph also preserves documented networking, music, sensors and speedometer capabilities. Several implementation files are unsampled, so links for those subsystems are limited to README-documented behavior or marked unverified rather than inferred from filenames.

Main entry points: [`Software/src/tc_main.cpp`](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_main.cpp) (Clock runtime), [`Software/src/tc_wifi.cpp`](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_wifi.cpp) (Wi-Fi portal), [`Software/src/tc_audio.cpp`](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_audio.cpp) (Audio features), [`Software/src/tc_kpmenu.cpp`](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_kpmenu.cpp) (Keypad menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clock["Clock and controls"]
  node_main["Clock runtime<br/>[tc_main.cpp]"]
  node_rtc["RTC and calendar<br/>[rtc.cpp]"]
  node_keypad["Keypad input<br/>[tc_keypad.cpp]"]
  node_menu["Keypad menu<br/>[tc_kpmenu.cpp]"]
end

subgraph group_device["Display and peripherals"]
  node_input["Input peripherals<br/>[input.cpp]"]
  node_gps["GPS receiver<br/>[gps.cpp]"]
  node_sensors["Environment sensors<br/>[sensors.cpp]"]
  node_speed["Speedometer<br/>[speeddisplay.cpp]"]
  node_display["Time displays<br/>[tcddisplay.cpp]"]
end

subgraph group_connect["Network and configuration"]
  node_wifi["Wi-Fi portal<br/>[tc_wifi.cpp]"]
  node_wifimanager["Portal service<br/>[WiFiManager.cpp]"]
  node_mqtt["MQTT messaging<br/>[mqtt.cpp]"]
  node_internet(("NTP service"))
end

subgraph group_sound["Audio playback"]
  node_audio["Audio features<br/>[tc_audio.cpp]"]
  node_decoder["Audio decoders"]
  node_codec["MP3 codec<br/>[layer3.c]"]
  node_output["I2S output<br/>[AudioOutputI2S.cpp]"]
end

subgraph group_storage["Media and settings"]
  node_sd[("SD card<br/>[SD.cpp]")]
  node_settings["Settings manager<br/>[tc_settings.cpp]"]
  node_music[("Music files")]
end

node_user(("Device user"))
node_props(("Compatible props"))

node_user -->|"presses keys"| node_keypad
node_user -->|"opens portal"| node_wifi
node_keypad -->|"routes input"| node_menu
node_menu -->|"changes settings"| node_main
node_main -.->|"uses timekeeping"| node_rtc
node_main -.->|"updates displays"| node_display
node_gps -.->|"supplies time"| node_main
node_internet -->|"supplies NTP time"| node_main
node_main -->|"uses network"| node_wifi
node_wifi -->|"configures portal"| node_wifimanager
node_wifi -->|"configures messaging"| node_mqtt
node_mqtt -->|"sends messages"| node_props
node_props -->|"triggers sequences"| node_main
node_main -.->|"handles peripherals"| node_input
node_main -.->|"uses sensor readings"| node_sensors
node_main -.->|"updates speedometer"| node_speed
node_main -->|"requests sound"| node_audio
node_audio -.->|"plays audio"| node_decoder
node_decoder -->|"decodes MP3"| node_codec
node_decoder -.->|"renders audio"| node_output
node_audio -->|"reads sound files"| node_sd
node_audio -->|"plays music"| node_music
node_sd -->|"stores files"| node_music
node_settings -->|"reads and writes"| node_sd
node_wifi -->|"saves portal settings"| node_settings
node_menu -->|"edits settings"| node_settings

click node_main "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_main.cpp"
click node_rtc "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/rtc.cpp"
click node_keypad "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_keypad.cpp"
click node_menu "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_kpmenu.cpp"
click node_input "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/input.cpp"
click node_gps "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/gps.cpp"
click node_sensors "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/sensors.cpp"
click node_speed "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/speeddisplay.cpp"
click node_display "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tcddisplay.cpp"
click node_wifi "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_wifi.cpp"
click node_wifimanager "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/WiFiManager/WiFiManager.cpp"
click node_mqtt "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/mqtt.cpp"
click node_audio "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_audio.cpp"
click node_decoder "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/AudioGeneratorMP3.cpp"
click node_codec "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/libmad/layer3.c"
click node_output "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/AudioOutputI2S.cpp"
click node_sd "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/SD/SD.cpp"
click node_settings "https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_settings.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_main,node_rtc,node_keypad,node_menu,node_user toneBlue
class node_input,node_gps,node_sensors,node_speed,node_display toneAmber
class node_wifi,node_wifimanager,node_mqtt,node_internet toneMint
class node_audio,node_decoder,node_codec,node_output toneRose
class node_sd,node_settings,node_music,node_props toneIndigo
```

## Components

### Clock and controls

- [Clock runtime](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_main.cpp): `Software/src/tc_main.cpp`
- [RTC and calendar](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/rtc.cpp): `Software/src/rtc.cpp`
- [Keypad input](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_keypad.cpp): `Software/src/tc_keypad.cpp`
- [Keypad menu](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_kpmenu.cpp): `Software/src/tc_kpmenu.cpp`

### Display and peripherals

- [Input peripherals](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/input.cpp): `Software/src/input.cpp`
- [GPS receiver](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/gps.cpp): `Software/src/gps.cpp`
- [Environment sensors](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/sensors.cpp): `Software/src/sensors.cpp`
- [Speedometer](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/speeddisplay.cpp): `Software/src/speeddisplay.cpp`
- [Time displays](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tcddisplay.cpp): `Software/src/tcddisplay.cpp`

### Network and configuration

- [Wi-Fi portal](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_wifi.cpp): `Software/src/tc_wifi.cpp`
- [Portal service](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/WiFiManager/WiFiManager.cpp): `Software/src/src/WiFiManager/WiFiManager.cpp`
- [MQTT messaging](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/mqtt.cpp): `Software/src/mqtt.cpp`
- **NTP service**

### Audio playback

- [Audio features](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_audio.cpp): `Software/src/tc_audio.cpp`
- [Audio decoders](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/AudioGeneratorMP3.cpp): `Software/src/src/ESP8266Audio/AudioGeneratorMP3.cpp`
- [MP3 codec](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/libmad/layer3.c): `Software/src/src/ESP8266Audio/libmad/layer3.c`
- [I2S output](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/ESP8266Audio/AudioOutputI2S.cpp): `Software/src/src/ESP8266Audio/AudioOutputI2S.cpp`

### Media and settings

- [SD card](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/src/SD/SD.cpp): `Software/src/src/SD/SD.cpp`
- [Settings manager](https://github.com/circuitsetup/time-circuits-display/blob/master/Software/src/tc_settings.cpp): `Software/src/tc_settings.cpp`
- **Music files**

### Other components

- **Device user**
- **Compatible props**

## Connections

- Device user → Keypad input: presses keys
- Device user → Wi-Fi portal: opens portal
- Keypad input → Keypad menu: routes input (evidence: `Software/src/tc_keypad.cpp`)
- Keypad menu → Clock runtime: changes settings (evidence: `Software/src/tc_kpmenu.cpp`)
- Clock runtime → RTC and calendar: uses timekeeping
- Clock runtime → Time displays: updates displays
- GPS receiver → Clock runtime: supplies time
- NTP service → Clock runtime: supplies NTP time
- Clock runtime → Wi-Fi portal: uses network (evidence: `Software/src/tc_main.cpp`)
- Wi-Fi portal → Portal service: configures portal (evidence: `Software/src/tc_wifi.cpp`)
- Wi-Fi portal → MQTT messaging: configures messaging (evidence: `Software/src/tc_wifi.cpp`)
- MQTT messaging → Compatible props: sends messages
- Compatible props → Clock runtime: triggers sequences
- Clock runtime → Input peripherals: handles peripherals
- Clock runtime → Environment sensors: uses sensor readings
- Clock runtime → Speedometer: updates speedometer
- Clock runtime → Audio features: requests sound (evidence: `Software/src/tc_main.cpp`)
- Audio features → Audio decoders: plays audio
- Audio decoders → MP3 codec: decodes MP3 (evidence: `Software/src/src/ESP8266Audio/AudioGeneratorMP3.cpp`)
- Audio decoders → I2S output: renders audio
- Audio features → SD card: reads sound files
- Audio features → Music files: plays music
- SD card → Music files: stores files
- Settings manager → SD card: reads and writes (evidence: `Software/src/tc_settings.cpp`)
- Wi-Fi portal → Settings manager: saves portal settings (evidence: `Software/src/tc_wifi.cpp`)
- Keypad menu → Settings manager: edits settings (evidence: `Software/src/tc_kpmenu.cpp`)
