From 30e9bdc46c8d8e861137c978875013b438f0fd20 Mon Sep 17 00:00:00 2001 From: Anne Jan Brouwer Date: Fri, 14 Aug 2026 22:52:12 +0200 Subject: [PATCH] docs(mch2022): explain why a Hatchery app's binary must be main.bin Closes #95. The page said to rename the binary to main.bin without saying why, which left people guessing whether AppFS cares about file names. It does not. The badge firmware does. Installing an ESP32 app from the Hatchery walks the app's file list and writes exactly one file into AppFS: the one whose name matches the esp32_bin_fn constant, "main.bin". Everything else lands in the app folder as a data file, so an app whose binary is called myapp.bin installs cleanly and then has nothing to run. The same holds for FPGA apps, where the launcher opens bitstream.bin and looks nowhere else. AppFS keys apps by slug and keeps the file name only as a title, so a push over USB is free to use any file name: app_push.py takes the name as an argument, and an update matches on that name. The page now says all of this and links the three source files it comes from. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_0142DuVFXpWnjeQhZzT3N3nC --- .../software-development/hatchery/_index.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/content/en/docs/Badges/MCH2022/software-development/hatchery/_index.md b/content/en/docs/Badges/MCH2022/software-development/hatchery/_index.md index fad693ad..a727121a 100755 --- a/content/en/docs/Badges/MCH2022/software-development/hatchery/_index.md +++ b/content/en/docs/Badges/MCH2022/software-development/hatchery/_index.md @@ -115,9 +115,40 @@ rename it. In case you're asking yourself: the *.bin file will be named the same way your firmware project is named in the top level "CMakeLists.txt" file: `project(main)` +#### Why it has to be called `main.bin` + +The name is not a convention, and it is not AppFS being fussy. It is the badge +firmware. When you install an ESP32 app from the Hatchery, the badge walks the +list of files the app has and writes exactly one of them into AppFS: the one +called `main.bin`. Every other file is downloaded to the app's folder as a data +file. The check is a plain string comparison against a constant named +`esp32_bin_fn` in +[`main/app_management.c`](https://github.com/badgeteam/mch2022-firmware-esp32/blob/master/main/app_management.c) +and +[`main/menus/hatchery.c`](https://github.com/badgeteam/mch2022-firmware-esp32/blob/master/main/menus/hatchery.c). + +So an app whose binary is called `myapp.bin` installs without an error and then +has nothing to run. + +AppFS itself does not care what your file was called. It stores apps under the +**slug**, with the file name kept only as a title. That is why the name does +not matter when you push over USB: + +``` +python3 app_push.py build/whatever.bin my_app "My App" 1 --run +``` + +Here `my_app` is the AppFS name and the thing an update has to match. Push the +same name again and you replace the app, whatever the file on your computer was +called. Only the Hatchery route, which goes through the badge's installer, needs +`main.bin`. + ### FPGA -If you are uploading an FPGA project, please name it `bitstream.bin`. +If you are uploading an FPGA project, please name it `bitstream.bin`. The same +reasoning applies: the launcher opens `bitstream.bin` in the app's folder, and +looks nowhere else. See +[`main/menus/launcher.c`](https://github.com/badgeteam/mch2022-firmware-esp32/blob/master/main/menus/launcher.c). Once all the relevant stuff is there, click "Save" and if you are feeling brave, check the "Publish" box, this allows others to see your app in the