docs: layered architecture wiki#48
Draft
anpeaco wants to merge 2 commits into
Draft
Conversation
A multi-layer guide under docs/ explaining FreeJoyX from first principles down to register-level detail: the mental model, STM32 fundamentals, flash layout & boot, the runtime model, the input subsystems (axes/buttons/ encoders), USB/HID, the configuration model, wire-format versioning, flashing/DFU, the F103-vs-F411 board seam, and repo/build/CI. Plus two end-to-end deep-dive traces (button press, config write) and a glossary. Grounded in the actual source (analog.c pipeline, main.c superloop, common_types.h structs) with file references throughout.
New docs/state-machines.md collecting the state-machine pattern that recurs across subsystems: the lookup-table quadrature encoder decoder, the logical button family (NORMAL/TOGGLE/TAP/DOUBLE_TAP) over one debounced input, and the USB-enumeration and DFU chunked-flash protocols. Grounded in encoders.c and the logical_buttons_state_t / encoder_state_t structs. Linked from the index and cross-referenced from the buttons and encoders layers.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a layered architecture wiki under
docs/— a from-scratch guide to how FreeJoyX works, written so a reader can stop at whatever depth they need.Structure (17 files, ~1,400 lines):
01-what-is-freejoyx,02-stm32-fundamentals03-memory-and-boot(3-region flash + boot decision + warm jump),04-runtime-model(setup sequence + superloop vs timer tick)05-axes(the fullanalog.cpipeline),06-buttons(sources, debounce, logical types, LOGIC, gestures),07-encoders,08-usb-hid(descriptors, enumeration, report IDs, the two report structs)09-configuration(dev_config_t, flash storage, R/W protocol),10-wire-format-and-versioning(the& 0xFFF0generation mask, the_Static_asserttrip-wire, the legacy-migrator/archival rule, header-sync),11-flashing-and-dfu(the chunked HID protocol + CRC + the Device gets stuck after flash, requires manual unplug to recover #36 clean-disconnect),12-f103-vs-f411(the BSP seam, StdPeriph vs HAL/LL),13-repos-and-buildglossary.mdEach layer links to the next and cites real files/functions so the docs are a map into the source, not a substitute for it. The deadband-on-inverted-axes work (PR #47) is used as a teaching case study in the axes layer.
Notes
analog.c,main.c,common_types.h). If prose and code ever diverge, the code wins — treat it as a docs bug.Test plan
docs/README.mdand confirm the layering / reading path makes sense.Generated by Claude Code