How kinesiscorporation/adv360-pro-zmk works
Project type and purpose
• This repository is a firmware‐configuration project for the Kinesis Advantage 360 Pro keyboard, built on top of a custom ZMK fork. It is not a web or mobile app but a specialized build‐system for generating and packaging keyboard firmware for two halves (left/right).
File structure
• Top level:
– Dockerfile & Makefile: define a reproducible containerized build environment.
– bin/: helper scripts (build.sh, get_version.sh).
– config/: all board definitions, keymaps, Kconfig, device trees, west manifest.
– firmware/: output directory for compiled .uf2 files.
– .github/workflows/build.yml: CI pipeline definition.
• config/boards/arm/adv360/: detailed hardware description (Kconfig, dts, yaml).
• config/west.yml: points to the custom ZMK fork and any external repositories.
Extract insights from the README
• Two build modes: cloud (GitHub Actions) and local (Docker/Podman + Make).
• Build produces timestamped artifacts (left.uf2, right.uf2).
• Flashing process targets physical USB‐mountable bootloader on each keyboard half.
Main components
a. Source Repositories & Editors
• Developer’s local clone / web GUI (keymap editor)
• GitHub repo (this config repo)
• External upstream ZMK fork (ReFil’s adv360‐z3.5) & base ZMK
b. Build Infrastructure
• GitHub Actions runner (cloud CI)
• Docker/Podman container (local CI)
• Make & bin/*.sh scripts orchestrating:
– west init/update to fetch ZMK sources
– CMake & Ninja build of firmware for left/right halves
c. Artifacts and Storage
• firmware/ directory in the repo (local builds)
• GitHub Actions artifacts (cloud builds)
d. Hardware Targets
• Left keyboard module (adv360_left.uf2)
• Right keyboard module (adv360_right.uf2)
• USB bootloader interface (drag‑and‑drop .uf2)
e. Documentation & Support
• Quick Start Guide & User Manual (external links)
Relationships and data flow
1. Developer edits config/ keymaps (locally or via web GUI).
2. Commit → push to GitHub → triggers CI pipeline.
3. CI or local Make:
– Launch container (Dockerfile) → mount workspace → run bin/build.sh →
– west fetch ZMK sources → CMake configure → Ninja build → produce UF2 files.
4. Build outputs saved to firmware/ and as GitHub Actions artifacts.
5. User flashes UF2 onto each physical half via USB bootloader.
Architectural patterns & design principles
• Separation of concerns:
• Configuration (config/) vs build orchestration (Makefile, Dockerfile, bin/) vs output (firmware/).
• CI pipeline isolated from local builds but reuses same container definition.
• Reproducibility:
• Containerized builds ensure identical environments across machines.
• west manifest pins external dependencies.
• Extensibility:
• Additional boards or keymaps can be added under config/boards or config/keymap.json.
• Custom build flags in defconfig files.
Final checklist
• Sufficient detail: call out config files (Kconfig, dtsi, defconfig), build scripts, CI workflow.