Files
wadamesh/tanmatsu/tools
Kaj SchittecatandClaude Opus 5 a6c447e7d7 docs + tools: sideloading wadamesh on the Tanmatsu
There was no way for anyone but me to put a self-built wadamesh on a Tanmatsu.
The repo carried tanmatsu/build.sh and nothing that could install what it built:
the AppFS writer lived only on my machine, so a fresh clone produced a binary and
no path onto the device. Anyone trying would land on `idf.py flash`, which
replaces the launcher OS.

tanmatsu/tools/ now carries the loop, generalised out of my local copy:

  fetch-appfs.sh     one-time, clones badge.team's esp32-component-appfs
  dump-pristine.sh   one-time, dumps YOUR device's AppFS partition as the baseline
  tan_deploy.py      builds the write-images and works out the changed sectors
  tan_flash.sh       detects the P4, writes app then metadata, verifies the commit
  sermon.py          non-resetting serial monitor

Three things had to change before this could work for anybody else. Absolute
paths to my checkout are gone. The hardcoded MAC of MY Tanmatsu is replaced by
detecting whichever port answers as an ESP32-P4, which is also more robust since
the board exposes two ports whose names move between replugs. And tan_flash.sh no
longer invokes tan_deploy.py twice: the second run would have read the metadata
the first had just written and bumped the version an extra time.

appfs.py is deliberately NOT vendored. It is badge.team's and the copy in
circulation has no licence header, so it is cloned instead. dev_appfs.bin is not
committed either: it is 8 MB and device-specific, and using someone else's dump
risks overwriting apps you have, since the deploy writes only what differs from
it. Both are gitignored.

Written up in TANMATSU_SIDELOAD.md and as a page on the site, linked from the
user guide, the homepage resources section and the README. The guide leads with
the model rather than the commands, because the failure that matters is not a
typo, it is not knowing that this board runs wadamesh as an app under a launcher
and that flashing it normally destroys that launcher.

Not re-verified on hardware: the tooling is the same loop that has been deploying
to my Tanmatsu, with the paths and device detection generalised. The first person
to run it on another machine is the real test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-21 19:32:50 +02:00
..