Thanks for helping. PicoDeck is a PicoPad launcher plus a module, an app SDK and a companion. This page covers the builds, the flash layout rules, the app API compatibility rules and the test checklist.
PicoDeck is derived from the PicoPad Arcade Launcher by MakerClassCZ (https://github.com/MakerClassCZ/picopad-arcade-launcher). The base launcher, UF2 tooling and MakeCode Arcade patching come from there.
Repository map
launcher/ launcher firmware, recovery image, UF2 tooling
wifi_module/ native WiFi module (core 1, Pico SDK)
apps_sdk/ app API, linker script, packer, examples
companion/ Node server + web UI, desktop Electron, Android
themes/ example themes and theme format
esp32/ legacy ESP32 firmware (not built by the launcher)
wifi_link/ standalone WiFi test app (not part of the launcher build)
picolibsdk/ vendored, pruned PicoLibSDK for picopad10
docs/ user and developer docs
.github/ issue templates and PR template
Prerequisites
- ARM GNU Toolchain 12.x or newer (
arm-none-eabi-gcc) - GNU Make, Python 3.8+
- Node.js 18+ for the companion
- Android SDK (build-tools 34, platform android-34) for the APK
- Electron and/or electron-builder for the desktop builds
You need a Pico W PicoPad for native WiFi. The launcher still boots on a non-W PicoPad with WiFi disabled.
Build
Launcher and recovery
source setup_env.sh
cd launcher
EXTRA_CFLAGS="-DLAUNCHER_RELEASE" ./c.sh
Outputs:
PICODECK_install.uf2— boot2 + launcher + recoveryPICODECK_update_1.0.0.uf2— launcher + recovery (andPICODECK_update.uf2)recovery/RECOVERY.uf2
Development builds (omit -DLAUNCHER_RELEASE) include the USB CDC debug shell
and USB MSC. Release builds omit them to save flash.
WiFi module
cd wifi_module
./build.sh
Uses the Pico SDK (PICO_SDK_PATH, default /usr/share/pico-sdk) and board
pico_w. Output: dist/PICODECK_wifimod_1.2.20.uf2.
Apps
cd apps_sdk
./build.sh examples/hello
python3 pack.py examples/hello
Companion
cd companion
node server.js # http://localhost:8787
node desktop/build.js # Linux Electron folder + tarball
node android/build.js # Android APK
Release desktop builds use electron-builder (config in
companion/package.json):
cd companion
npx electron-builder --linux AppImage --win portable --x64
The Windows build skips native module rebuilds; the serialport optional
dependency is not bundled there.
Flash layout (1 MB default)
0x10000000 boot2
0x10000100 game / WiFi module area up to 0x100A0000 (640 KB)
0x10050000 launcher RAM snapshot 0x37800 (while an app runs)
0x100A0000 custom app slot 252 KB
0x100DF000 app install record 4 KB
0x100E0000 launcher 108 KB
0x100FB000 recovery 12 KB
0x100FE000 settings 4 KB
0x100FF000 CF2 4 KB
The 2 MB layout (-DLAUNCHER_2MB=1) moves the launcher to 0x101E0000; the
app SDK currently targets the 1 MB layout.
Invariants — do not break these
- boot2 is the only path to recovery. Never erase sector 0 in the trasher.
- Game flashing writes boot2 first, verifies it, then writes the game.
- Launcher updates write recovery first, then the launcher.
- App installs only touch the app slot and record. Never boot2, recovery, launcher, module or CF2.
- Games/modules must not erase above
GAME_ERASE_HI(the app slot). - The launcher snapshot must be outside the app slot and the module area.
- The launcher and recovery addresses are shared across
launcher/config.h,launcher/*.ld,launcher/recovery/config.h,launcher/c.sh,launcher/merge_install_bin.py,app_shared.handapps_sdk/app.ld. Changing one without the others bricks the chain.
App API compatibility
app_shared.h is the contract between the launcher and apps.
app_info_tis append-only. New fields go at the end, and old apps must still work.APP_API_VERSIONis checked byInfo(). Bump it only with a migration plan.- Extended fields are gated by
APP_INFO_EXT_MAGIC; old launchers don't write them and new apps fall back to defaults. APP_INFO_ADDR,APP_SLOT_BASE,APP_SLOT_SIZE,APP_RECORD_ADDR,APP_NET_BUF_ADDRandLAUNCHER_SNAPSHOT_*are fixed addresses. Changing them requires rebuilding every app and updatingapps_sdk/app.ld.- Keep
app_info_tout of app RAM: the app heap ends at0x20037800.
Coding style
- Match the surrounding file: 4 spaces, C++ for the launcher, C for the app SDK and the module.
- Avoid
printf/mallocin the launcher where a static buffer works. RAM is tight; checkarm-none-eabi-size. - Use the theme colours (
g_theme.*,AppTheme(...)) rather than hard-coded colours in UI. - Keys: no assumptions about B; it may be broken. Use A/X/UP/DOWN/Y.
- Any flash operation must pause core 1 first and resume after (unless the module is being replaced).
- Never call
RuntimeInit/DeviceInit/BatInit/DispInitfrom an app. - Keep new launcher code within the flash budget; release builds are close to the 108 KB launcher image.
Test checklist
Before a release, on real hardware:
- [ ] Install UF2 on a blank device via BOOTSEL.
- [ ] Update from SD; recovery still boots.
- [ ] Boot with no SD → warning; insert card → normal.
- [ ] First boot with
FRESH.TXT→ tutorial; marker deleted. - [ ] Game flash from SD; PLAY works; watchdog reset relaunches.
- [ ] WiFi module install prompt; scan; connect; status stages; link up.
- [ ] Flash a game over the module; PLAY works; reinstall module; WiFi returns.
- [ ] App install from SD folder and
.pap; launch; exit without reboot. - [ ] App manager: reinstall, edit config, clear data, remove.
- [ ] App store online (HTTP) install/update.
- [ ] Crash log: force a BSOD, Y writes
/crash/CRASHnnn.TXT. - [ ] Companion connects without the Companion Link screen; Prepare SD on a spare card.
- [ ] Recovery: UP+X at power-on; BOOTSEL.
- [ ] Power loss during update and during a game flash (expected: recovery).
App store
The catalogue is served at https://pico.msuii.dev. The package tree lives at
http://pico.msuii.dev/assets/apps/ and .../assets/themes/.
- The site and moderation server run separately from this repository; they
write
index.txtand the chunk files, and nginx serves that tree directly. index.txtformat:id|version|size|url|name.- The PicoPad fetches over plain HTTP; package files are split into 3 KB
chunks (
hello.pap.000,.001, ...) because the module's HTTP buffer is 4 KB. Theme packages use the same chunking. assets.msuii.dev/picopadapps/is kept as an alias for firmware 1.0.0, which hardcodes that host. It must stay an alias, not a redirect: the firmware only parses200 OK.- Bump the app's
app.iniversion=and the index version together. - Apps are native ARM code, so review the package contents before approving. Themes cannot execute anything.
Git and releases
- Don't commit build outputs. The repo
.gitignorecoversbuild/, UF2/BIN/ ELF/MAP,*.pap,node_modules,companion/dist. - Commit messages: short imperative summary (
wifi: fix scan completion,apps: add clear data). - Releases: build launcher/module/apps, run
android/build.js, build the AppImage and Windows EXE with electron-builder, generateSHA256SUMS, thengh release create vX.Y.Z --notes-file ...with the assets. - Issue and PR templates live in
.github/.
Reporting issues
Use the GitHub issue templates:
- Bug report — launcher/game/WiFi/companion problems.
- App or store issue — a custom app or the app catalogue.
- Feature request — ideas.
Include the PicoDeck version, module version, hardware (Pico W?), SD size and
the crash log when there is one. Please don't paste secrets from /wifi.cnf.
Credits
- MakerClassCZ/picopad-arcade-launcher — base launcher, UF2 tooling, MakeCode Arcade patching
- Panda381/PicoLibSDK
- Raspberry Pi Pico SDK
- Pajenicko PicoPad
- microsoft/uf2
- microsoft/pxt-arcade