已发布项目

mosaico-gamer-mosaico-51f0f5d0

Revision 2

Mosaico Gamer · 关于我在 Mosaico 上爽玩童年游戏这件事

把 ESP-Mosaico 变成一台掌机：一套固件里装着四个引擎，GBA（gpSP）、Game Boy / Game Boy Color（gnuboy）、Doom 和 Quake 1。游戏文件存在板载 NAND 上，在游戏列表里选一个就能开玩。有声音，GBA 存档会自动写回 NAND，关机也不会丢。

需要至少插一个摇杆子板才能玩，插两个体验更好：左边管移动，右边管按键和视角，握起来和双手柄掌机差不多。固件不附带任何游戏，请自备合法取得的 ROM、WAD 或 PAK 文件。

操作指南

准备：插上摇杆子板

  1. 一个摇杆子板
    插在左槽或右槽都可以。画面会跟着摇杆转到你握着的那一侧。摇杆控制方向，旁边一圈四个按键依次是 A、Start、Select、B，方向和你看到的画面一致。

  2. 两个摇杆子板（推荐）
    左右各插一个，画面回到正放。左摇杆控制方向或移动，右子板的四个按键是 A / Start / Select / B，右摇杆在 Quake 里用来转视角。左子板的四个按键另有用途，见下文 Quake 部分。同一对摇杆也可以玩 Mosaico 上的另一款应用《浴火木星》（Jupiter on Fire）：左摇杆驾驶，右摇杆环视。

  3. 首次校准
    插上后先松手，别碰摇杆，固件会用大约半秒测量摇杆的中心位置。然后把摇杆沿边缘转满一圈，摇杆的行程范围会被记住，下次开机直接沿用。

放入游戏文件

两种方式任选一种。

  1. Upload over Wi-Fi

    • 配网：在游戏列表里选中「Upload over Wi-Fi」，按 A。从扫描结果里选一个网络，用屏幕键盘输入密码：可以点按屏幕上的字母，也可以用摇杆移动再按 A 输入；B 删除一个字符，Select 切换输入框，Start 开始连接。Wi-Fi 密码会被记住。连上之后，电脑打开上传页时会把自己的时间写回设备，快捷设置里的时钟就对上了。
    • 网页上传：配网成功后屏幕显示一个 http:// 地址。在同一网络下的电脑上用浏览器打开它，选文件上传。传完后回到游戏列表就能看到。

  2. USB disk on PC
    选中「USB disk on PC」，按 A，用 USB 线连接电脑。这里用的是 ESP-MSC：设备通过 USB 把自己报成一块移动磁盘，电脑按普通 U 盘来读写；每一次读写都落到板载 SPI NAND 的对应扇区上，上面是一个 FAT 卷。整片 NAND 都交给这块盘，容量大约 120 MB。把文件直接拖进去即可。

两种方式都认这些文件：.gb、.gbc、.gba、.wad，以及 Quake 的 .pak。Quake 的数据包要保持原名 pak0.pak、pak1.pak……放在磁盘根目录。引擎从 pak0.pak 开始按编号依次加载，所以 pak0.pak 必须有，编号中间不能断。游戏列表里选任意一个 .pak 都能启动 Quake。

游戏列表

  1. 选择：摇杆上推、下拉移动光标，到顶或到底会循环。
  2. 开始：按 A 或 Start，启动选中的游戏；在上传入口上按则进入对应页面。
  3. 删除：在某个游戏上按 Select，会弹出「THIS CANNOT BE UNDONE」确认框。按 A 确认删除，按 B 或 Select 取消。删掉之后无法恢复。
  4. 退出页面：在上传页面按 B 返回上一级。在屏幕键盘里 B 是删除字符，点按 AI 键取消输入。不要按住 AI 键，按住会进入 Recovery。

GBA / GB / GBC

  1. 方向键：摇杆。需要推过一定幅度才算按下，轻微抖动不会误触。
  2. A / B / Start / Select：按键环上的四个键。
  3. L / R 肩键：按住屏幕底部左半边是 L，右半边是 R。两边可以同时按住。
  4. 存档：游戏里正常存档即可。固件大约每 30 秒把存档写回 NAND 一次，退出游戏时也会写一次。
  5. 退出：点按 AI 键，回到游戏列表。不要按住，按住会进入 Recovery。

Doom

  1. 移动与转向：摇杆前推前进、后拉后退，左右转身。
  2. A：开火；在菜单里是确认。
  3. B：开门、按开关；在菜单里也是确认。
  4. Start：按住奔跑。
  5. Select：打开或关闭自动地图。
  6. L / R：按住屏幕底部左右两块区域左右平移。
  7. 按下摇杆：摇杆中键。弹出「是否退出」时相当于按 Y 确认。
  8. AI 键：点按打开 Doom 菜单。不要按住，按住会进入 Recovery。

Quake

  1. 移动：左摇杆前后移动和左右平移，推得越远走得越快。
  2. 视角：右摇杆左右转身、上下抬头低头，推得越多转得越快。只插一个子板时没有视角摇杆。
  3. A：攻击。
  4. B：跳跃。
  5. Start：按住奔跑。
  6. Select：查看计分板。
  7. 切换武器：左子板的四个按键里，上和右切到下一把武器，下和左切回上一把。
  8. 按下左摇杆：在退出确认里相当于按 Y。
  9. AI 键：点按打开 Quake 菜单。不要按住，按住会进入 Recovery。

快捷设置（任何时候都能打开）

  1. 打开：从屏幕上边缘往下滑。
  2. 调节：在亮度或音量滑条上左右拖动。设置会被保存，下次开机仍然有效。
  3. 状态：面板上还显示时间和电量。
  4. 关闭：向上滑，或点面板外的区域。面板打开时，游戏列表不响应开始和删除。

后续更新

  • 设备之间的磁吸交互，模仿 GBA / GBC 的联机对战和交换。
  • 继续适配更多模拟器。

技术一览

  • 目标硬件：ESP-Mosaico（ESP32-S31）+ 摇杆子板（至少一个，推荐两个）
  • 引擎：gpSP（GBA）、gnuboy（GB/GBC）、Doom、Quake 1（WinQuake）
  • 分类：显示与 HMI / 音频 / 通信
  • 固件格式：Iris
  • 许可证：GPL-3.0-or-later。各引擎为 GPL-2.0-or-later，应用代码为 Apache-2.0，详见工程里的 NOTICE。
  • 不包含任何游戏 ROM、WAD 或 PAK 文件。

Mosaico Gamer: Replaying My Childhood Games on Mosaico

Mosaico Gamer turns ESP-Mosaico into a handheld console. One firmware carries four engines: GBA (gpSP), Game Boy / Game Boy Color (gnuboy), Doom and Quake 1. Games live on the onboard NAND. Pick one from the game list and play, with sound. GBA saves are written back to NAND automatically, so they survive power-off.

You need at least one joystick sub-board, and two feel better: the left one moves, the right one handles the buttons and the camera, much like a two-handed handheld. The firmware ships with no games. Bring your own legally obtained ROM, WAD or PAK files.

How to play

Setup: attach the joystick sub-boards

  1. One joystick sub-board
    Use either the left or the right slot. The picture turns to follow the side you are holding. The stick is the direction pad. The four-button ring around it is A, Start, Select and B, matching the picture you see.

  2. Two joystick sub-boards (recommended)
    Attach one on each side and the picture sits upright. The left stick is direction or movement. The right module's four buttons are A / Start / Select / B, and the right stick turns the view in Quake. The left module's four buttons have their own use, described under Quake. The same pair also plays Jupiter on Fire, another Mosaico app: the left stick flies, the right stick looks around.

  3. First calibration
    After attaching, let go and leave the stick alone. The firmware measures the stick's centre for about half a second. Then sweep the stick once around its edge. The stick's travel range is saved and reused on the next boot.

Add game files

Pick one of the two.

  1. Upload over Wi-Fi

    • Join the network: in the game list, select Upload over Wi-Fi and press A. Pick a network from the scan results and type the password on the on-screen keyboard: tap letters on the screen, or move with the stick and press A. B deletes a character, Select switches fields, and Start connects. The Wi-Fi password is saved. After that, opening the upload page from a computer writes the computer's clock back to the device, so the clock in quick settings matches.
    • Upload on the web page: once joined, the screen shows an http:// address. Open it in a browser on a computer on the same network and upload files. They appear in the game list when you go back.

  2. USB disk on PC
    Select USB disk on PC, press A, and connect a USB cable. This uses ESP-MSC: the device presents itself as a removable disk, and the computer reads and writes it like any USB drive. Each transfer lands on a sector of the onboard SPI NAND, which is one FAT volume. The whole NAND is that disk, about 120 MB. Drag files onto it.

Both ways accept .gb, .gbc, .gba and .wad, plus Quake .pak files. Keep the Quake data packs under their original names, pak0.pak, pak1.pak and so on, in the root of the disk. The engine loads them in order starting from pak0.pak, so pak0.pak is required and the numbering must not skip. Selecting any .pak in the game list starts Quake.

Game list

  1. Select: push the stick up or down to move the cursor. It wraps at the top and bottom.
  2. Start: press A or Start to launch the selected game. On an upload entry, the same keys open that page.
  3. Delete: press Select on a game. A "THIS CANNOT BE UNDONE" box appears. A deletes, B or Select cancels. A deleted file cannot be recovered.
  4. Leave a page: on the upload page, B goes back. On the on-screen keyboard, B deletes a character and a tap of the AI key cancels input. Do not hold the AI key; holding it enters Recovery.

GBA / GB / GBC

  1. D-pad: the stick. It has to be pushed past a threshold, so small jitters do not register.
  2. A / B / Start / Select: the four ring buttons.
  3. L / R shoulders: hold the bottom-left part of the screen for L and the bottom-right part for R. You can hold both at once.
  4. Saving: save in the game as usual. The firmware writes the save to NAND about every 30 seconds and once more when you quit.
  5. Quit: tap the AI key to return to the game list. Do not hold it; holding it enters Recovery.

Doom

  1. Move and turn: push the stick forward to walk, back to retreat, left or right to turn.
  2. A: fire; confirm in menus.
  3. B: open doors and use switches; also confirms in menus.
  4. Start: hold to run.
  5. Select: toggle the automap.
  6. L / R: hold the bottom-left or bottom-right screen area to strafe.
  7. Stick click: press the stick in. At the quit prompt this answers Y.
  8. AI key: tap to open the Doom menu. Do not hold it; holding it enters Recovery.

Quake

  1. Move: the left stick walks forward, back and strafes. The further you push, the faster you move.
  2. Look: the right stick turns left and right and looks up and down. The further you push, the faster the view turns. With only one sub-board there is no look stick.
  3. A: attack.
  4. B: jump.
  5. Start: hold to run.
  6. Select: show the scoreboard.
  7. Change weapon: on the left module's four buttons, up and right select the next weapon; down and left select the previous one.
  8. Left stick click: answers Y at the quit prompt.
  9. AI key: tap to open the Quake menu. Do not hold it; holding it enters Recovery.

Quick settings (available at any time)

  1. Open: swipe down from the top edge of the screen.
  2. Adjust: drag left or right on the brightness or volume slider. Settings are saved and persist across reboots.
  3. Status: the panel also shows the time and battery level.
  4. Close: swipe up, or tap outside the panel. While the panel is open, the game list ignores launch and delete.

Later updates

  • Magnetic interaction between devices, in the style of GBA / GBC link play and trading.
  • More emulators.

Specs

  • Hardware: ESP-Mosaico (ESP32-S31) plus joystick sub-boards (at least one, two recommended)
  • Engines: gpSP (GBA), gnuboy (GB/GBC), Doom, Quake 1 (WinQuake)
  • Categories: Display & HMI / Audio / Communication
  • Firmware: Iris
  • License: GPL-3.0-or-later. The engines are GPL-2.0-or-later and the application code is Apache-2.0; see NOTICE in the project.
  • No game ROM, WAD or PAK files are included.