# clockworkpi/uconsole architecture

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

- Interactive diagram: https://gitdiagram.com/clockworkpi/uconsole
- Repository: https://github.com/clockworkpi/uconsole

## Overview

uConsole is a handheld-computer hardware and software support repository: it provides OS-image release information, keyboard firmware and flashing tools, hardware-specific patches and scripts, and 4G-extension resources. The main user workflow is selecting an OS image, downloading it, and flashing it to the device. The keyboard workflow is firmware source to supplied firmware and a documented flashing script. Keyboard source excerpts show interfaces and state types, but not the implementations that connect scanning, input handling, and USB HID output; those links are therefore omitted. Several README capabilities are documented without corresponding source in the sampled files.

Main entry points: [`Bin/uconsole_keyboard_flash/flash.sh`](https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/flash.sh) (Keyboard flash script), [`README.md`](https://github.com/clockworkpi/uconsole/blob/master/README.md) (Image releases), [`Bin/uconsole_keyboard_flash/maple_upload`](https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/maple_upload) (Keyboard upload utility), [`Bin/4G`](https://github.com/clockworkpi/uconsole/tree/master/Bin/4G) (4G firmware packages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_os["OS and platform"]
  node_release_info["Image releases<br/>[README.md]"]
  node_platform_patches["Platform patches"]
  node_cm4_patch["CM4 patch guidance<br/>[README.md]"]
  node_a06_patch["A06 patch guidance<br/>[README.md]"]
end

subgraph group_keyboard["Keyboard firmware"]
  node_keyboard_source["Keyboard firmware source"]
  node_keyboard_firmware["Keyboard firmware binary"]
  node_flash_script["Keyboard flash script<br/>[flash.sh]"]
  node_flash_utility["Keyboard upload utility"]
end

subgraph group_cellular["4G extension"]
  node_modem_docs["4G usage guidance"]
  node_modem_firmware["4G firmware packages"]
end

subgraph group_hardware["Hardware utilities"]
  node_gearbox["A06 Gearbox<br/>[README.md]"]
  node_audio_patch["Audio jack GPIO helper<br/>[audio_3.5_patch.py]"]
end

node_user(("uConsole user"))
node_image_host["Image download host"]
node_flash_os["OS image flasher"]
node_uconsole["uConsole device"]
node_keyboard_device["Keyboard hardware"]
node_modem_hardware["4G extension"]
node_gpio["Device GPIO"]

node_user -->|"selects release"| node_release_info
node_release_info -->|"provides download details"| node_image_host
node_user -->|"downloads image"| node_image_host
node_user -->|"flashes image"| node_flash_os
node_flash_os -->|"writes image"| node_uconsole
node_user -.->|"consults guidance"| node_cm4_patch
node_user -.->|"consults guidance"| node_a06_patch
node_keyboard_source -.->|"build artifact"| node_keyboard_firmware
node_user -->|"runs script"| node_flash_script
node_flash_script -.->|"invokes uploader"| node_flash_utility
node_flash_script -->|"flashes firmware"| node_keyboard_firmware
node_flash_utility -.->|"uploads firmware"| node_keyboard_device
node_user -->|"consults guidance"| node_modem_docs
node_user -->|"obtains firmware"| node_modem_firmware
node_modem_firmware -.->|"upgrades"| node_modem_hardware
node_user -->|"sets CPU gear"| node_gearbox
node_audio_patch -->|"reads and controls"| node_gpio

click node_release_info "https://github.com/clockworkpi/uconsole/blob/master/README.md"
click node_platform_patches "https://github.com/clockworkpi/uconsole/tree/master/Code/patch"
click node_cm4_patch "https://github.com/clockworkpi/uconsole/blob/master/Code/patch/cm4/20230630/README.md"
click node_a06_patch "https://github.com/clockworkpi/uconsole/blob/master/Code/patch/a06/20230630/README.md"
click node_keyboard_source "https://github.com/clockworkpi/uconsole/tree/master/Code/uconsole_keyboard"
click node_keyboard_firmware "https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/uconsole_keyboard.ino.bin"
click node_flash_script "https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/flash.sh"
click node_flash_utility "https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/maple_upload"
click node_modem_docs "https://github.com/clockworkpi/uconsole/blob/master/wiki/How-to-use-the-4G-extension.md"
click node_modem_firmware "https://github.com/clockworkpi/uconsole/tree/master/Bin/4G"
click node_gearbox "https://github.com/clockworkpi/uconsole/blob/master/README.md"
click node_audio_patch "https://github.com/clockworkpi/uconsole/blob/master/Code/scripts/audio_3.5_patch.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_release_info,node_platform_patches,node_cm4_patch,node_a06_patch,node_user toneBlue
class node_keyboard_source,node_keyboard_firmware,node_flash_script,node_flash_utility toneAmber
class node_modem_docs,node_modem_firmware toneMint
class node_gearbox,node_audio_patch toneRose
class node_image_host,node_flash_os,node_uconsole,node_keyboard_device,node_modem_hardware,node_gpio toneIndigo
```

## Components

### OS and platform

- [Image releases](https://github.com/clockworkpi/uconsole/blob/master/README.md): `README.md`
- [Platform patches](https://github.com/clockworkpi/uconsole/tree/master/Code/patch): `Code/patch`
- [CM4 patch guidance](https://github.com/clockworkpi/uconsole/blob/master/Code/patch/cm4/20230630/README.md): `Code/patch/cm4/20230630/README.md`
- [A06 patch guidance](https://github.com/clockworkpi/uconsole/blob/master/Code/patch/a06/20230630/README.md): `Code/patch/a06/20230630/README.md`

### Keyboard firmware

- [Keyboard firmware source](https://github.com/clockworkpi/uconsole/tree/master/Code/uconsole_keyboard): `Code/uconsole_keyboard`
- [Keyboard firmware binary](https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/uconsole_keyboard.ino.bin): `Bin/uconsole_keyboard_flash/uconsole_keyboard.ino.bin`
- [Keyboard flash script](https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/flash.sh): `Bin/uconsole_keyboard_flash/flash.sh`
- [Keyboard upload utility](https://github.com/clockworkpi/uconsole/blob/master/Bin/uconsole_keyboard_flash/maple_upload): `Bin/uconsole_keyboard_flash/maple_upload`

### 4G extension

- [4G usage guidance](https://github.com/clockworkpi/uconsole/blob/master/wiki/How-to-use-the-4G-extension.md): `wiki/How-to-use-the-4G-extension.md`
- [4G firmware packages](https://github.com/clockworkpi/uconsole/tree/master/Bin/4G): `Bin/4G`

### Hardware utilities

- [A06 Gearbox](https://github.com/clockworkpi/uconsole/blob/master/README.md): `README.md`
- [Audio jack GPIO helper](https://github.com/clockworkpi/uconsole/blob/master/Code/scripts/audio_3.5_patch.py): `Code/scripts/audio_3.5_patch.py`

### Other components

- **uConsole user**
- **Image download host**
- **OS image flasher**
- **uConsole device**
- **Keyboard hardware**
- **4G extension**
- **Device GPIO**

## Connections

- uConsole user → Image releases: selects release
- Image releases → Image download host: provides download details
- uConsole user → Image download host: downloads image
- uConsole user → OS image flasher: flashes image
- OS image flasher → uConsole device: writes image
- uConsole user → CM4 patch guidance: consults guidance
- uConsole user → A06 patch guidance: consults guidance
- Keyboard firmware source → Keyboard firmware binary: build artifact
- uConsole user → Keyboard flash script: runs script
- Keyboard flash script → Keyboard upload utility: invokes uploader
- Keyboard flash script → Keyboard firmware binary: flashes firmware
- Keyboard upload utility → Keyboard hardware: uploads firmware
- uConsole user → 4G usage guidance: consults guidance
- uConsole user → 4G firmware packages: obtains firmware
- 4G firmware packages → 4G extension: upgrades
- uConsole user → A06 Gearbox: sets CPU gear
- Audio jack GPIO helper → Device GPIO: reads and controls