Repository navigation
docs: the READMEs' architecture figure, drawn from the source (#58) - #330
Merged
Merged
Conversation
Svg wrote the manual's 720 px in two places, the right bound a text may reach and the viewBox. Both read self.largura now, a class attribute that is LARGURA, so a subclass can draw at another width: tools/readme_diagram.py, which draws the README's architecture figure at 832 px. Refactor, behaviour unchanged: the 28 SVG that manual_diagramas.py --write draws are sha256-equal to the committed ones, --check finds nothing (Python 3.14 and 3.11), and tools/test_manual_diagramas.py passes its 884 controls. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
The three READMEs showed an ASCII sketch of the firmware. It had drifted
from the code: it put TouchPriority on Core 1, which only Core 0's
LogManager, StorageManager and WebManager read, and the issue that asked
for an SVG quoted it with moved lines, a DHT22 on I2C and a Bluetooth
console on BLE (the console is classic SPP, SerialBT).
tools/readme_diagram.py draws the figure from the sources at the commit,
with the builder and the readers of tools/manual_diagramas.py, and writes
six files: docs/images/architecture{,-dark}{,.pt-BR,.es-ES}.svg, one per
README language and Ângulo theme. Each README shows its pair through
<picture> and prefers-color-scheme, as it shows the wordmark (GitHub wraps
it in <themed-picture>, so it follows GitHub's theme), at the drawing's
width, with an alt text and a paragraph that keeps the split between the
cores in searchable text.
What it reads, and stops on when the code moves:
- every src/*Manager.h, each declaring its class; the role the figure
gives a manager is prose pinned to a phrase of the header's @brief, and
a manager without a role, or a role without its manager, stops the draw;
- the two cores: main.cpp's loop( ) feeds the watchdog and runs
app.loop( ), whose loop calls LogManager's checkCrossCoreHealth( );
Core 1 is launched on core1Entry( ), runs loopCore1( ) and reads the
touch there; docs/CONCURRENCY.md still says Core 0 runs everything but
the display, Core 1 never touches the flash and a flash write stalls it;
- between them: the snapshot under _stateMutex; the lock-free ring of
UI_EV_RING (16) events that Core 0 drains; and the log and history
writes Core 0 holds for TOUCH_PRIORITY_MS (5 s) after a touch, through
AppManager::isUserInteracting( ), which TouchPriority reads. What Core 0
checks of each event is not drawn: docs/AUTHORIZATION.md holds that,
with the events left ungated and four saves registered as deviations,
and no short line in a figure says it without hiding those;
- the boards and images from the build profiles (Pico W, Pico 2 W, the
Wire's plain Pico and ENC28J60; 16 slots on every published image and 11
on the Wire; the panel each published image draws; the buzzer on every
image but the Air; MQTT, TLS, /metrics and syslog on every image drawn), the
sensor buses from each driver's @brief, the panel's 320x240 and SPI0,
the network's peers from the manual's readers (two telemetry transports,
MQTT Discovery, GET /metrics, RFC 5424 over UDP) and NTP.
The path of the Ângulo's stylesheet is FOLHA_ANGULO: named TOKENS, a quoted
string assigned to it read as a literal credential to scan_secrets.sh.
The colours are the Ângulo's: the values come from docs/assets/angulo.css
and the rules of the dg-* classes from the manual's CSS in
tools/build_manual.py, written into each SVG's <style> with the theme's
values, since an SVG behind <img> cannot see the page's CSS. Each file
carries the manual's frame (.moldura-svg: the surface, a 1 px line, the
card's corner) as its background, so it reads when opened alone and every
text sits on a background of the Ângulo's table of combinations. Six token
roles per theme, nothing else. The issue asked for four colours, one per
block; the Ângulo, which postdates it, keeps colour for action.
832 px wide: GitHub's README column is 838 px in 1280, 1440 and 1920 px
windows (measured 2026-11-07, Chrome, signed out), so the 13 px text is
shown at 13 px; --check holds each README's <img> to that width. --check
redraws the six and reads the three READMEs: 0 findings on this tree
(Python 3.14 and 3.11); check_angulo.py, check_readme_numbers.py and
scan_secrets.sh pass.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
tools/test_readme_diagram.py puts one fault at a time into a scratch copy of the six figures, the three READMEs or the sources the figure reads, never into the tree, and requires exactly the findings that fault is about: one character of each file, a file that is not UTF-8 and each file deleted give one finding; in the READMEs, the <picture> removed, a <source> or the <img> on another file, the alt empty or gone, the <img> narrower than the drawing or without its width, the section renamed and a box-drawing character in the section give one each, and the same character in another section none; in the sources, the slots, the ring and the touch's window changed change all six drawings and what they say, a token colour changes its theme's three files and not the others, a manager without a role, a role without its manager and each of the 11 @brief reworded stop the draw, and each of the 127 patterns the tool reads, mangled, and each of the 45 files it reads, deleted, exit 2 naming it. The line breaker keeps code whole; two draws, and two --write with different hash seeds, give the same bytes. 342 controls, 0 failed, 5.4 s (Python 3.14; 5.7 s under 3.11, CI's). The controls bite: with the README reader returning nothing, 44 fail; with the image comparison returning nothing, 18; with the premises switched off, 11. The tree's figures, READMEs and tokens are the same bytes after a run as before it. The gates job runs readme_diagram.py --check and this file after the manual's diagrams. Locally (ci_gates_local.py --quick in a depth-1 clone), the branch fails the same ten steps as origin/main, all for this machine's missing pio and libraries, and passes the two new ones. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
The console behind SIMUT_BLUETOOTH is classic Bluetooth over SPP (SerialBT, RFCOMM), as the section's own header and BluetoothManager say; the comment on the #define said "Bluetooth BLE CLI". Comment only, same line count; no image rebuilt for it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
… indexes and AGENTS.md CHANGELOG and CHANGELOG.pt-BR say what the figure shows, how it stays true and the BLE comment; tools/README.md lists readme_diagram.py and its controls under "Called by CI" (235 scripts, 94 there; CLAUDE.md quotes the total); docs/images/README.md names the six files and their tool, and says that the brand, the figure and the manual's diagrams are drawn by code rather than that every file in the folder is a capture; AGENTS.md section 7 adds the figure to the copies of the tokens and what to do when one changes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS
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
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.
Closes #58.
The three READMEs showed an ASCII sketch of the firmware. This replaces it with an SVG figure, in the READMEs' three languages and the Ângulo's two themes, drawn from the source by a new tool and checked in CI.
Why it is drawn by code
The sketch had drifted from the code, and the issue itself carried the drift: it quoted the sketch at lines that had moved, with a DHT22 on I2C and a Bluetooth console on BLE, and the sketch put
TouchPriorityon Core 1, which only Core 0 reads. A hand-drawn SVG would drift the same way.tools/readme_diagram.pydraws the figure from the sources at the commit, with the builder and the readers oftools/manual_diagramas.py, which draws the manual's 28 diagrams the same way, and thegatesjob runs its--check.What the figure says, and where each claim comes from
src/main.cpp(loop( )),src/AppManager_Loop.cpp(checkCrossCoreHealth( )),docs/CONCURRENCY.md(the model, invariant 1)DisplayManager::loopCore1( ), reads the touch there, and a flash write pauses itsrc/DisplayManager.cpp(core1Entry( ), the touch read),docs/CONCURRENCY.mdsrc/DisplayManager.h(_stateMutex,UI_EV_RING),src/DisplayManager.cpp(pullSnapshot( )),src/AppManager_Events.cppTouchPriority)TOUCH_PRIORITY_MSinsrc/AppManager.h,AppManager::isUserInteracting( ), the provider insrc/AppManager_Boot.cpp,src/LogManager.cpp,src/StorageManager.cppsrc/*Manager.h; each role is pinned to a phrase of the header's@brief/metricsand syslog on every image drawntools/generated/profiles.ini,platformio.ini,src/simut_config.h,src/ui/UiCaps.h,src/net/NetCaps.h,tools/release_manifest.py@brief,src/display/*.h,src/BluetoothManager.h(SerialBT)GET /metrics, RFC 5424 over UDP, NTPtools/manual_diagramas.py,src/NetworkManager.hEach claim is a pattern the code has to keep. When one is gone, the tool exits 2 naming the file and the pattern, and draws nothing.
Where it departs from the issue
docs/assets/angulo.cssand the rules of the manual's diagrams, six token roles per theme and nothing else.TouchPriorityis drawn as the rule Core 0 keeps, the console's Bluetooth is classic SPP, the DHT22 has its own single-wire protocol, and the Wire has 11 slots. Themes and i18n are not drawn as Core 1 components: Core 0 loads the language pack (invariant 1), and Core 1 only draws. What Core 0 checks of each panel event is not drawn either:docs/AUTHORIZATION.mdholds that, with the events left ungated and four saves registered as deviations, and no short line in a figure says it without hiding those.<picture>, as it shows the wordmark; GitHub wraps it in<themed-picture>, so the figure follows GitHub's theme, not the operating system's. Each file also carries the manual's frame as its background, so it reads when opened alone.Also in this PR
tools/manual_diagramas.py:Svgtakes its canvas width from the class, so the README's figure can draw at 832 px. Refactor: the 28 manual SVG are sha256-equal to the committed ones, andtest_manual_diagramas.pypasses its 884 controls.src/simut_config.h: the inline comment ofSIMUT_BLUETOOTHsaid BLE; the console is classic SPP, as the section's header says. Comment only.tools/README.md(235 scripts),docs/images/README.md,AGENTS.md§7 andCLAUDE.md.Tests
manual_diagramas.py --checkfinds nothing andtest_manual_diagramas.pypasses its 884 controls.readme_diagram.py --check: 0 findings, under Python 3.14 and 3.11 (CI's).test_readme_diagram.py: 342 controls, 0 failed, 5.4 s (3.14) and 5.7 s (3.11). They bite: with the README reader returning nothing, 44 fail; with the image comparison returning nothing, 18; with the premises switched off, 11.check_angulo.py,check_readme_numbers.pyandscan_secrets.shpass. The last one first failed this branch: it readTOKENS = 'docs/assets/angulo.css'as a literal credential, and the constant isFOLHA_ANGULOnow.ci_gates_local.py --quick, in a depth-1 clone of cc4e42b: 83 steps. This branch fails the same 10 steps as origin/main does on this machine, nine Ângulo host tests and the feature model, all for the missingpioand Adafruit GFX of a fresh worktree; the two new steps pass.width, and the images index.<picture>picks its language's file for the theme (architecture{,.pt-BR,.es-ES}.svgin light,architecture-dark…in dark), shown at 832 px, 1:1, on#ffffffand#0d1117.Not verified
src/simut_config.h.src/is a comment. CI runs them.🤖 Generated with Claude Code
https://claude.ai/code/session_01Uy7K2qG2dULk2EBnwkCyZS