Project files

Atlas Rover Mk.1 DualEye Firmware V0.1/V0.2 Design Description

1. Version Objectives

The goal of DualEye Firmware V0.1 is not to complete all hardware drivers at once, but to first stabilize the core program framework:

• Dual physical round-screen expression model.
• Page and expression state machine.
• MimiClaw voice event entry.
• UART chassis control protocol.
• Movement safety timeout and AR1,STOP protection.
• Subsequent adaptation boundaries for Waveshare's official dual-screen, touch, and audio drivers.

V0.2 will continue to fill in the framework for "how to configure and debug after flashing":

• NVS storage for Wi-Fi, LLM/API, and security settings.
• SoftAP/STA/APSTA network startup.
• Web management page for mobile/PC.
• Separation of user application page /app and admin backend /admin; root path / defaults to the application page.
• 6-digit pairing code.
• STOP, short-movement, and text intent test APIs.
• Placeholder for MimiClaw adaptation layer.

2. Responsibilities of the Dual Boards

4. Program Structure

The ATLAS_ENABLE_DEV_EVENT_DEMO macro in main.c is enabled by default to observe expression state transitions (listening, thinking, speaking, success) after flashing; it does not send movement commands. After connecting to a real MimiClaw, this macro can be set to 0.

4. Expression States

The current firmware includes the following expression enumerations:

5. Voice-to-Motion Link

flowchart LR
  A["Microphone/Touch Wake-up"] --> B["MimiClaw Understanding"]
  B --> C["atlas_voice_intent_t"]
  C --> D["atlas_ui State Machine"]
  D --> E["Expression Switching"]
  D --> F["AR1 UART Commands"]
  F --> G["Chassis Board"]
  G --> H["DRV8833 / Motors"]
  G --> I["AR1 ACK"]
  I --> D

Example:

6. Safety Policy

1. DualEye only actively sends commands prefixed with AR1,.
2. After power-on, it first sends AR1,STOP.
3. After each movement command, DualEye sends a delayed AR1,STOP based on the action duration.
4. The chassis board must still independently implement a motion cutoff watchdog: each motion command must include duration_ms to automatically stop after the specified time; abnormal commands must stop immediately.
5. The chassis board must ignore any content not prefixed with AR1,.
6. Motor power must not be drawn from DualEye; DualEye, the chassis board, and motor power share only the GND.
7. Web/voice movement is enabled by default for out-of-the-box convenience; it can still be disabled in the management page's security settings.
8. STOP does not require a pairing code; movement, configuration changes, reboots, and configuration clearing require a 6-digit pairing code.
9. LLM/MimiClaw cannot directly output UART strings; they can only output structured intentions, which are then filtered by the local Safety Guard.
10. API keys are not hardcoded, not uploaded to GitHub, and not printed in logs; NVS encryption is not yet enabled in the current prototype phase.
11. The default control mode is manual: web direction buttons can control the rover; switching to ai mode allows voice/mimiClaw movement intentions to control it, while web direction buttons are rejected.

7. Real Machine Adaptation To-Do List

8. Current Verification

This version must at least pass:

cd firmware/dualeye
export IDF_PATH="$HOME/.espressif/esp-idf-v5.5.2"
export IDF_PYTHON_ENV_PATH="$HOME/.espressif/python_env/idf5.5_py3.9_env"
. "$IDF_PATH/export.sh"
idf.py build

After a successful build, the firmware skeleton, module separation, and ESP-IDF configuration are confirmed usable; subsequent steps will involve real-device display/audio adaptation.

The current project configures the Flash as 16 MB according to the DualEye official specifications and uses a custom partition table:

Local build V0.5 passes, with the application image approximately 0x110770 bytes, leaving ample space in the 4 MB app partition. PSRAM still requires further validation in conjunction with the real dual-screen/LVGL buffer strategy.