Human-facing reference documentation, split from AGENTS.md's agent-facing
domain rules and bug history (which stays there, not duplicated here):
- docs/architecture.md: layer diagram, module responsibilities, config
storage location, the three GUI modes, and the port-exclusivity /
multi-process caveats around concurrent access
- docs/data-model.md: the combined and legacy JSON formats, the binary
SDeviceConfig/SDeviceProfile/SMacroTable NVM layout byte-for-byte, action
types, LED fields, macro-slot conventions, button grid geometry
- docs/protocol.md: the 8-byte serial packet format, command/event tables,
the read/write/status-poll flows, connection lifecycle, and error states
README.md now links to all three from a new "Dokumentation" section, and
AGENTS.md's outdated "docs/ tree isn't warranted yet" note is removed now
that it exists on explicit user request.
VersaPadLink never closes itself; get_board_status()/load_from_board()/
write_to_board() were leaving the exclusive COM port open for the rest of
the MCP server process's lifetime after a single call. That locked out
Live-Sync, the official VersaGUI, and even the MCP server's own next call
with "busy", live-observed today after a single write_to_board() call. Each
of the three now closes the link in a finally block regardless of outcome.
Also documented in AGENTS.md: this environment can run several independent
versapad_mcp_server.py processes at once, each with its own in-memory
state, which caused a write_to_board() call to silently write blank data
from a fresh process instead of the config that had just been built up on
another one (ACK still said {"ok": true}). Recommended workaround noted
there: load_local() right before write_to_board(), and read back with
load_from_board() + get_profile() afterwards instead of trusting the ACK.
Lets Claude Code offer the "versapad" MCP server automatically when this
project is opened, instead of requiring a manual `claude mcp add -s user`
per machine. Note: the script path is currently absolute (this machine's
checkout location) rather than relative -- .mcp.json doesn't reliably
support workspace-relative variables across Claude Code environments, so
this only works as-is on this specific checkout path for now.
versapad_combined.DEFAULT_PATH was hardcoded to this one machine's OneDrive
desktop, which made the tool unusable anywhere else. versapad_data.app_dir()
now resolves to the running .exe's own folder when frozen, or the project
directory when run from source, and DEFAULT_PATH hangs off that instead.
load_or_fetch() previously raised when both the file was missing and the
board unreachable, blocking a fresh install with no config and no board
attached. It now falls back to an empty default_combined() in that case, so
the tool is immediately usable either way. desktop_viewer's
_current_profile_view() picks up the same fallback instead of re-implementing
a narrower version of it.
Also drop the hardcoded PROFILE_NAMES dict, which had drifted out of sync
with the profile_names already stored in the combined JSON -- renaming a
profile in Programmiermodus never showed up in the read-only/browser views.
server.py and desktop_viewer.py now read names from the same JSON everywhere.
versapad_data.CONFIG_PATHS (read-only interop with the official C# VersaGUI's
JSON export) is intentionally left on the OneDrive desktop -- nothing in
this codebase writes there, it's not part of this tool's own config.
server.py and desktop_viewer.py read-only mode required the desktop
config JSONs to exist and crashed/showed "Config-Datei fehlt" if one
was deleted, even though the board already holds the config durably
in NVM. Add versapad_combined.fetch_from_board()/load_or_fetch(): a
missing combined JSON is now transparently rebuilt from the board via
serial and cached back to disk, falling back to the legacy per-profile
JSONs (or a clear error) only when the board is unreachable.
_on_toggle_editing() seeded self.combined from default_combined() on first
activation, which reads the stale per-profile JSONs for all 3 profiles
instead of the current versapad_config_all.json. Writing to board while
only editing one profile silently reverted the other two. Now prefers
loading the current combined file, falling back to defaults only if it
doesn't exist.
Also documents the READ_STATUS polling change and the jappel PR workflow
constraint in AGENTS.md.
AGENTS.md now follows the mandated section structure (Project Goal,
Aktuell unterstützte Architektur, Kritische Domänenregeln,
Existing-Codebase-Regel, Implementierungsdisziplin, Naming, Deferred
Work, Dokumentation und Verifikation) instead of an organically grown
set of headings. Folds in all prior technical notes (protocol
validation, network-drive build/runtime gotchas, threading rules)
under the appropriate section, and fixes a stale "no tray icon yet"
line that no longer matched the code. README gets an explicit honest
status paragraph (what's tested, what's not: no automated tests, no
prebuilt exe download, hardcoded paths).
No docs/ tree: project has no database or persistent multi-user
service, so the full doc structure isn't warranted per the standard.
Minimizing or closing hides the window instead of leaving a taskbar
entry; only "Beenden" in the tray right-click menu really exits. Tray
callbacks route through a queue instead of touching Tk directly from
pystray's thread (same pattern as the earlier serial-thread fix).
Also fixes the build script: PyInstaller failed on the network share
while copying Tcl/Tk tzdata (path-length issue), so building now
happens in a local temp copy instead of directly on Z:.
Adds an info button that explains the MCP server's available tools.
Avoids the cmd.exe flash from double-clicking run_desktop.bat and
gives a proper double-click .exe like VersaGUI.exe. Must be deployed
locally (%LOCALAPPDATA%) -- Windows silently refuses to load the
_internal DLLs when the .exe sits on the Z: network share, no error
shown. build_and_deploy.ps1 handles build + local copy in one step.
