A gated, end-to-end workflow for developing, testing, debugging, and deploying Xianmubox firmware changes safely.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install xianmubox-dev
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install xianmubox-dev using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Xianmubox Development Workflow?
Xianmubox Development Workflow guides an AI coding agent through the full lifecycle of changes to this MicroPython and ESP32-S3 project, from requirements and implementation through simulator checks, device debugging, deployment, documentation, and command-line commits. It helps keep changes aligned with the repository’s existing modes, framework services, hardware constraints, and project conventions.
The workflow enforces practical safeguards: confirm scope before implementation, validate UI changes in the simulator, require python tools/test.py to pass before building, back up device settings before deployment, and update documentation in the same change batch. For Openclaw Skills users working in this repository, it turns project-specific rules into actionable stage gates rather than optional suggestions.
Xianmubox Development Workflow Use Cases
- Add a new mode or feature after confirming its interaction, data source, fonts, hardware requirements, and persistence needs.
- Modify an existing screen, button interaction, data source, or layout while checking simulator behavior and regression tests.
- Investigate a bug or real-device failure by diagnosing serial output and hardware tests before changing code.
- Build and push firmware to an ESP32-S3 device while protecting the existing
settings.jsonconfiguration. - Change hardware, GPIO assignments, settings structure, or architecture using a written and reviewed implementation plan.
- Finish a change with synchronized documentation, command-line Git commits, and a clear report of simulator, test, and device verification results.
How Xianmubox Development Workflow Works
- Apply Stage 0 rules throughout: simulate UI changes before flashing, run the required quality checks, update related documentation in the same batch, and commit only through the command line.
- Choose the entry stage: start new features and modes at Stage 1, device issues and bug fixes at Stage 4, and requests to push code to a device at Stage 5. The final closeout at Stage 6 is always required.
- Clarify requirements: inspect existing profiles, framework services, APIs, font maps, hardware pin documentation, and settings behavior before confirming scope with the user.
- Plan according to change size: small changes can proceed with a clear fix; regular features require an approved plan; major hardware, architecture, or settings changes require a written proposal.
- Implement and register changes: follow the coding rules, implement the mode or service, update the required registration points and build allowlist, and run simulator checks and regression scripts.
- Pass the test gate: run
python tools/test.py; do not proceed to build if it has unexpected failures. The documented missing-secrets.pyfailure is an expected exception. - Diagnose or deploy as appropriate: for device issues, use diagnostic scripts and serial logs to find the root cause. Before deployment, back up device settings, build the selected profile, push the build, and verify settings restoration.
- Close out: perform device regression checks when applicable, synchronize the required documentation, create a command-line commit, and report changes and verification status.
Xianmubox Development Workflow Setup
Use this skill in the Xianmubox repository. Review the project instructions and the relevant reference before the corresponding work: references/coding-rules.md before implementation, references/device-debug.md for device diagnosis, and references/toolchain.md before deployment. Commands below are repository workflows; use the port and profile that match your device.
# Run the project quality gate
python tools/test.py
# Launch the simulator and list available modes
python tools/simulator/run.py --list
python tools/simulator/run.py --mode <x> --zoom 3
# Back up device settings before deployment
python -m mpremote cp :settings.json ./settings.backup.json
# Build and quickly push a profile to an ESP32-S3 device
python tools/build.py --profile full --device esp32s3_n8r8
python tools/fast_push.py COM5 build/esp32s3_n8r8_full /
# Commit changes from the command line using a UTF-8 message file
git add -A
git commit -F <UTF-8-file>
Replace COM5 with the device’s serial port. Do not deploy before backing up settings.json; deployment can overwrite device configuration. After pushing, confirm settings restoration and exercise the target mode on the device.
Xianmubox Development Workflow Data Schema & Taxonomy
The skill describes a repository workflow and existing project data conventions; it does not define a separate skill-owned database or generated metadata format.
| Location or artifact | Purpose |
|---|---|
src/modes/<x>.py |
Mode implementation; follows the BaseMode contract and provides enter() and loop(). |
src/app_config.py and src/modes/registry.py |
Simulator-facing menu and mode registration points. |
profiles/<p>.json |
Feature declarations used by deployment builds; generated build configuration derives from profile features. |
tools/build.py |
FRAMEWORK_FILES allowlist for framework modules required at runtime. |
settings.json |
Device persistence for configuration; updates go through the framework settings service and validation. Temporary state is not persisted. |
designs/*.json |
UI design specifications rendered by the simulator; for major UI work, the saved spec is the implementation alignment reference. |
tools/_sim_<x>.py and tools/shots/ |
Mode regression scripts and simulator screenshots; scripts report pass/fail results and an exit code. |
doc/ and README |
Feature, hardware, firmware-history, project-structure, and other documentation that must be synchronized with relevant changes. |
settings.backup.json |
Local backup created before deployment; device settings must be restored or confirmed afterward. |
Xianmubox Development Workflow Advanced Features
- Routes work into six gated stages and supports targeted entry points for feature work, bug diagnosis, and device pushes while retaining mandatory closeout.
- Uses simulator-rendered UI specifications and automated regression scripts with screenshots, assertions, and pass/fail exit codes.
- Encodes project-specific architecture checks, including mode registration across configuration, registry, and profile files, plus framework build allowlisting.
- Provides hardware diagnosis workflows using
mpremote, self-test scripts, SD diagnostics, MP3 diagnostics, and raw REPL commands. - Supports both fast batch deployment and slower fallback deployment, as well as single-file hot fixes when source and build artifacts remain aligned.
- Protects device state through mandatory settings backups and documents additional safeguards for firmware flashing, partition changes, and restoration.
- Requires documentation to ship alongside code and enforces command-line-only Git commits to avoid known filename encoding damage.
- For Openclaw Skills users, combines repository-specific checks and operational guardrails into a repeatable workflow for AI-assisted firmware development.
SKILL.md
Loading
Related Openclaw Skills
XianMu Comics
Bring 568 classic Chinese picture-story books into chat for discovery, page-by-page reading and narration, and AI conversations with their characters.
MemoryVault
MemoryVault gives AI agents persistent, searchable cloud memory so useful context can carry across sessions, machines, and collaborative workflows.
Qinghu AI WeChat Channels Social Operations Expert
Analyze WeChat Channels accounts, viral content, comments, and livestreams to turn public data into practical social growth strategies.
Fengniao Cloud Number Manager
A Qinghu MCP-powered assistant for selecting, purchasing, managing, renewing, and monitoring Fengniao cloud numbers and physical SIM cards.
AI Opportunity Navigator
Find and screen current paid coding and AI evaluation opportunities against your location, skills, and available time—with original sources and clear eligibility gaps.
Mundane
Mundane connects AI agents with ID-verified local workers for real-world tasks, holding payment in escrow until the user reviews the proof.
Featured*
