cardputer-sim

A desktop "simulator" for @echo-lalia's MicroHydra APIs, built on top of pygame. It lets you develop and debug MicroHydra/Cardputer-style apps on your PC before deploying them to real hardware.

Note

Parts of this software, such as the lib.hydra libraries were written by @echo-lalia.

Requirements

• Python 3.10 or newer
• Desktop OS with Python and pip (tested on Windows, should also work on Linux/macOS)
• For 3D examples (moderngl-based apps), a GPU/driver with OpenGL 3.3+ support

Quick start

Installation

python3 -m venv venv
pip3 install -r requirements.txt

Usage

To start the launcher:

python3 applauncher.py

To launch a specific app:

python3 applauncher.py snake

Commander app

The repository includes a dual-pane file manager app:

python3 applauncher.py Commander

Controls:

• TAB switch active pane
• UP/DOWN (or ;/.) move cursor
• ENT (or RIGHT) open directory
• LEFT/BSPC go to parent
• C copy selected item to opposite pane
• M move selected item to opposite pane
• D delete selected item (with confirmation)
• N create directory
• R rename selected item
• P connect to Cardputer over serial
• O disconnect serial
• I install current Commander app to Cardputer (/apps/Commander/__init__.py) over standard MicroPython REPL
• ESC exit to launcher

Serial mode (real board over USB serial):

• Run Commander on the Cardputer.
• Run Commander on the PC simulator, then press P to open port selection.
• The right pane (on the PC) is the remote Cardputer filesystem when connected.
• On Cardputer, Commander still works as a local file manager while also responding to PC requests.
• Press O on PC to disconnect.
• If Display/UserInput are unavailable, Commander automatically runs in headless server-only mode.

Adding your own apps

Put your apps in rootfs/apps. An example app demonstrating display and keyboard APIs can be found in rootfs/apps/example/__init__.py

Each app is either:

• a single .py file in rootfs/apps, e.g. snake.py → python3 applauncher.py snake, or
• a package directory in rootfs/apps with an __init__.py, e.g. example/ → python3 applauncher.py example. These apps can also include icons for the launcher.

Inside your app you can use the same APIs that exist on the MicroHydra/Cardputer (e.g. Display, UserInput, audio helpers, etc.). When you are ready to move to real hardware, you can usually copy the code with minimal or no changes.

Repository layout

• applauncher.py – entry point and app launcher
• libraries/ – MicroPython compatibility layer and extra libraries (including 3D helpers in libraries/custom)
• libraries/lib/ – higher-level helpers: display, audio, UI components, input handling
• rootfs/apps/ – built-in and user apps (games, demos, tools)
• rootfs/config.json – configuration for the launcher (colors, language, volume, etc.)

Versions

microhydra

This branch only has the APIs that MicroHydra (and micropython) has, and nothing more. Useful for writing apps only for MicroHydra/Cardputer/micropython.

master (this branch)

This branch includes the MicroHydra APIs, but also has some extra ones, such as 3D rendering using moderngl. You can find these in libraries/custom. Useful for writing desktop apps/games

Differences vs real hardware

• Timing and performance may differ slightly from the real device.
• Hardware emulation is configurable and currently includes I2C emulation for M5Stack ENV3 (SHT30 + QMP6988).
• Additional bus emulation is available for ADC, SPI, GPIO, UART, and I2S.
• I2S includes functional speaker (playback) and microphone (PCM capture waveform) emulated devices.
• The goal is to make app logic and rendering portable, not to be a cycle-accurate emulator.

Hardware emulation settings

simulator_settings.json supports a Hardware section with per-bus and per-device enable flags.

Example:

"Hardware": {
	"enabled": true,
	"thread_hz": 20,
	"I2C": {
		"enabled": true,
		"devices": {
			"M5Stack_ENV3": {
				"enabled": true,
				"bus": 0,
				"scl": 1,
				"sda": 2,
				"sht30_address": 68,
				"qmp6988_address": 112
			}
		}
	}
}

The emulator runs in a dedicated background thread and can be accessed through normal machine.I2C calls (scan, writeto, readfrom, readfrom_mem, writeto_mem). For other buses, machine.ADC, machine.Pin, machine.SPI, machine.UART, and machine.I2S also route through the emulator runtime.

App troubleshooting

My app doesn't start/My app quits immediately

If you have something like if __name__ == "__main__", then it won't work, as your __name__ is never __main__. Simply remove the if statement, and run the code directly.

My app is not responding

Make sure you run UserInput.get_pressed_keys() in your loop.

The colors are messed up

MicroHydra (therefore this simulator) uses RGB565 colors instead of RGB888. So for example red in RGB888 is 0xFF0000, but in RGB565 its 0xF800. I recommend using the color_picker or hexto565 app.

I'm not seeing anything on the screen

Make sure you're running Display.show().

License

This project is distributed under the terms of the license in LICENSE. Please see that file for details.