m5/MicroPythonOS

Fork 0

mirror of https://github.com/m5stack/MicroPythonOS.git synced 2026-05-20 11:51:27 -07:00

Files

T

Thomas Farstrike 6096f4ced5 Update CLAUDE.md

2025-11-23 05:47:06 +01:00

29 KiB

Raw Blame History

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MicroPythonOS is an embedded operating system that runs on ESP32 hardware (particularly the Waveshare ESP32-S3-Touch-LCD-2) and desktop Linux/macOS. It provides an LVGL-based UI framework with an Android-inspired app architecture featuring Activities, Intents, and a PackageManager.

The OS supports:

Touch and non-touch input devices (keyboard/joystick navigation)
Camera with QR decoding (using quirc)
WiFi connectivity
Over-the-air (OTA) firmware updates
App installation via MPK packages
Bitcoin Lightning and Nostr protocols

Repository Structure

Core Directories

internal_filesystem/: The runtime filesystem containing the OS and apps
- boot.py: Hardware initialization for ESP32-S3-Touch-LCD-2
- boot_unix.py: Desktop-specific boot initialization
- main.py: UI initialization, theme setup, and launcher start
- lib/mpos/: Core OS library (apps, config, UI, content management)
- apps/: User-installed apps (symlinks to external app repos)
- builtin/: System apps frozen into the firmware (launcher, appstore, settings, etc.)
- data/: Static data files
- sdcard/: SD card mount point
lvgl_micropython/: Submodule containing LVGL bindings for MicroPython
micropython-camera-API/: Submodule for camera support
micropython-nostr/: Submodule for Nostr protocol
c_mpos/: C extension modules (includes quirc for QR decoding)
secp256k1-embedded-ecdh/: Submodule for cryptographic operations
manifests/: Build manifests defining what gets frozen into firmware
freezeFS/: Files to be frozen into the built-in filesystem
scripts/: Build and deployment scripts
tests/: Test suite (both unit tests and manual tests)

Key Architecture Components

App System: Similar to Android

Apps are identified by reverse-domain names (e.g., com.micropythonos.camera)
Each app has a META-INF/MANIFEST.JSON with metadata and activity definitions
Activities extend mpos.app.activity.Activity class (import: from mpos.app.activity import Activity)
Apps implement onCreate() to set up their UI and onDestroy() for cleanup
Activity lifecycle: onCreate() → onStart() → onResume() → onPause() → onStop() → onDestroy()
Apps are packaged as .mpk files (zip archives)
Built-in system apps (frozen into firmware): launcher, appstore, settings, wifi, osupdate, about

UI Framework: Built on LVGL 9.3.0

mpos.ui.topmenu: Notification bar and drawer (top menu)
mpos.ui.display: Root screen initialization
Gesture support: left-edge swipe for back, top-edge swipe for menu
Theme system with configurable colors and light/dark modes
Focus groups for keyboard/joystick navigation

Content Management:

PackageManager: Install/uninstall/query apps
Intent: Launch activities with action/category filters
SharedPreferences: Per-app key-value storage (similar to Android)

Hardware Abstraction:

boot.py configures SPI, I2C, display (ST7789), touchscreen (CST816S), and battery ADC
Platform detection via sys.platform ("esp32" vs others)
Different boot files per hardware variant (boot_fri3d-2024.py, etc.)

Build System

Building Firmware

The main build script is scripts/build_mpos.sh:

# Development build (no frozen filesystem, requires ./scripts/install.sh after flashing)
./scripts/build_mpos.sh unix dev

# Production build (with frozen filesystem)
./scripts/build_mpos.sh unix prod

# ESP32 builds (specify hardware variant)
./scripts/build_mpos.sh esp32 dev waveshare-esp32-s3-touch-lcd-2
./scripts/build_mpos.sh esp32 prod fri3d-2024

Build types:

dev: No preinstalled files or builtin filesystem. Boots to black screen until you run ./scripts/install.sh
prod: Files from manifest*.py are frozen into firmware. Run ./scripts/freezefs_mount_builtin.sh before building

Targets:

esp32: ESP32-S3 hardware (requires subtarget: waveshare-esp32-s3-touch-lcd-2 or fri3d-2024)
unix: Linux desktop
macOS: macOS desktop

The build system uses lvgl_micropython/make.py which wraps MicroPython's build system. It:

Fetches SDL tags for desktop builds
Patches manifests to include camera and asyncio support
Creates symlinks for C modules (secp256k1, c_mpos)
Runs the lvgl_micropython build with appropriate flags

ESP32 build configuration:

Board: ESP32_GENERIC_S3 with SPIRAM_OCT variant
Display driver: st7789
Input device: cst816s
OTA enabled with 4MB partition size (16MB total flash)
Dual-core threading enabled (no GIL)
User C modules: camera, secp256k1, c_mpos/quirc

Desktop build configuration:

Display: sdl_display
Input: sdl_pointer, sdl_keyboard
Compiler flags: -g -O0 -ggdb -ljpeg (debug symbols enabled)
STRIP is disabled to keep debug symbols

Building and Bundling Apps

Apps can be bundled into .mpk files:

./scripts/bundle_apps.sh

Running on Desktop

# Run normally (starts launcher)
./scripts/run_desktop.sh

# Run a specific Python script directly
./scripts/run_desktop.sh path/to/script.py

# Run a specific app by name
./scripts/run_desktop.sh com.micropythonos.camera

Important environment variables:

HEAPSIZE: Set heap size (default 8M, matches ESP32-S3 PSRAM). Increase for memory-intensive apps
SDL_WINDOW_FULLSCREEN: Set to true for fullscreen mode

The script automatically selects the correct binary (lvgl_micropy_unix or lvgl_micropy_macOS) and runs from the internal_filesystem/ directory.

Deploying to Hardware

Flashing Firmware

# Flash firmware over USB
./scripts/flash_over_usb.sh

Installing Files to Device

# Install all files to device (boot.py, main.py, lib/, apps/, builtin/)
./scripts/install.sh waveshare-esp32-s3-touch-lcd-2

# Install a single app to device
./scripts/install.sh waveshare-esp32-s3-touch-lcd-2 camera

Uses mpremote from MicroPython tools to copy files over serial connection.

Testing

Running Tests

Tests are in the tests/ directory. There are two types: unit tests and manual tests.

Unit tests (automated, run on desktop or device):

# Run all unit tests on desktop
./tests/unittest.sh

# Run a specific test file on desktop
./tests/unittest.sh tests/test_shared_preferences.py
./tests/unittest.sh tests/test_intent.py
./tests/unittest.sh tests/test_package_manager.py
./tests/unittest.sh tests/test_graphical_start_app.py

# Run a specific test on connected device (via mpremote)
./tests/unittest.sh tests/test_shared_preferences.py --ondevice

# Run all tests on connected device
./tests/unittest.sh --ondevice

The unittest.sh script:

Automatically detects the platform (Linux/macOS) and uses the correct binary
Sets up the proper paths and heapsize
Can run tests on device using mpremote with the --ondevice flag
Runs all test_*.py files when no argument is provided
On device, assumes the OS is already running (boot.py and main.py already executed), so tests run against the live system
Test infrastructure (graphical_test_helper.py) is automatically installed by scripts/install.sh

Available unit test modules:

test_shared_preferences.py: Tests for mpos.config.SharedPreferences (configuration storage)
test_intent.py: Tests for mpos.content.intent.Intent (intent creation, extras, flags)
test_package_manager.py: Tests for PackageManager (version comparison, app discovery)
test_graphical_start_app.py: Tests for app launching (graphical test with proper boot/main initialization)
test_graphical_about_app.py: Graphical test that verifies About app UI and captures screenshots

Graphical tests (UI verification with screenshots):

# Run graphical tests on desktop
./tests/unittest.sh tests/test_graphical_about_app.py

# Run graphical tests on device
./tests/unittest.sh tests/test_graphical_about_app.py --ondevice

# Convert screenshots from raw RGB565 to PNG
cd tests/screenshots
./convert_to_png.sh  # Converts all .raw files in the directory

Graphical tests use tests/graphical_test_helper.py which provides utilities like:

wait_for_render(): Wait for LVGL to process UI events
capture_screenshot(): Take screenshot as RGB565 raw data
find_label_with_text(): Find labels containing specific text
verify_text_present(): Verify expected text is on screen

Screenshots are saved as .raw files (RGB565 format) and can be converted to PNG using tests/screenshots/convert_to_png.sh

Manual tests (interactive, for hardware-specific features):

manual_test_camera.py: Camera and QR scanning
manual_test_nostr_asyncio.py: Nostr protocol
manual_test_nwcwallet*.py: Lightning wallet connectivity (Alby, Cashu)
manual_test_lnbitswallet.py: LNbits wallet integration
test_websocket.py: WebSocket functionality
test_multi_connect.py: Multiple concurrent connections

Run manual tests with:

./scripts/run_desktop.sh tests/manual_test_camera.py

Writing New Tests

Unit test guidelines:

Use Python's unittest module (compatible with MicroPython)
Place tests in tests/ directory with test_*.py naming
Use setUp() and tearDown() for test fixtures
Clean up any created files/directories in tearDown()
Tests should be runnable on desktop (unix build) without hardware dependencies
Use descriptive test names: test_<what_is_being_tested>
Group related tests in test classes
IMPORTANT: Do NOT end test files with if __name__ == '__main__': unittest.main() - the ./tests/unittest.sh script handles running tests and capturing exit codes. Including this will interfere with test execution.

Example test structure:

import unittest
from mpos.some_module import SomeClass

class TestSomeClass(unittest.TestCase):
    def setUp(self):
        # Initialize test fixtures
        pass

    def tearDown(self):
        # Clean up after test
        pass

    def test_some_functionality(self):
        # Arrange
        obj = SomeClass()
        # Act
        result = obj.some_method()
        # Assert
        self.assertEqual(result, expected_value)

Development Workflow

Creating a New App

Create app directory: internal_filesystem/apps/com.example.myapp/
Create META-INF/MANIFEST.JSON with app metadata and activities
Create assets/ directory for Python code
Create main activity file extending Activity class
Implement onCreate() method to build UI
Optional: Create res/ directory for resources (icons, images)

Minimal app structure:

com.example.myapp/
├── META-INF/
│   └── MANIFEST.JSON
├── assets/
│   └── main_activity.py
└── res/
    └── mipmap-mdpi/
        └── icon_64x64.png

Minimal Activity code:

from mpos.app.activity import Activity
import lvgl as lv

class MainActivity(Activity):
    def onCreate(self):
        screen = lv.obj()
        label = lv.label(screen)
        label.set_text('Hello World!')
        label.center()
        self.setContentView(screen)

See internal_filesystem/apps/com.micropythonos.helloworld/ for a minimal example and built-in apps in internal_filesystem/builtin/apps/ for more complex examples.

Testing App Changes

For rapid iteration on desktop:

# Build desktop version (only needed once)
./scripts/build_mpos.sh unix dev

# Install filesystem to device (run after code changes)
./scripts/install.sh waveshare-esp32-s3-touch-lcd-2

# Or run directly on desktop
./scripts/run_desktop.sh com.example.myapp

Debugging

Desktop builds include debug symbols by default. Use GDB:

gdb --args ./lvgl_micropython/build/lvgl_micropy_unix -X heapsize=8M -v -i -c "$(cat boot_unix.py main.py)"

For ESP32 debugging, enable core dumps:

./scripts/core_dump_activate.sh

Important Constraints

Memory Management

ESP32-S3 has 8MB PSRAM. Memory-intensive operations:

Camera images consume ~2.5MB per frame
LVGL image cache must be managed with lv.image.cache_drop(None)
Large UI components should be created/destroyed rather than hidden
Use gc.collect() strategically after deallocating large objects

Threading

Main UI/LVGL operations must run on main thread
Background tasks use _thread.start_new_thread()
Stack size: 16KB for ESP32, 24KB for desktop (see mpos.apps.good_stack_size())
Use mpos.ui.async_call() to safely invoke UI operations from background threads

Async Operations

OS uses uasyncio for networking (WebSockets, HTTP, Nostr)
WebSocket library is custom websocket.py using uasyncio
HTTP uses aiohttp package (in lib/aiohttp/)
Async tasks are throttled per frame to prevent memory overflow

File Paths

Use M:/path/to/file prefix for LVGL file operations (registered in main.py)
Absolute paths for Python imports
Apps run with their directory added to sys.path

Build Dependencies

The build requires all git submodules checked out recursively:

git submodule update --init --recursive

Desktop dependencies: See .github/workflows/build.yml for full list including:

SDL2 development libraries
Mesa/EGL libraries
libjpeg
Python 3.8+
cmake, ninja-build

Manifest System

Manifests define what gets frozen into firmware:

manifests/manifest.py: ESP32 production builds
manifests/manifest_fri3d-2024.py: Fri3d Camp 2024 Badge variant
manifests/manifest_unix.py: Desktop builds

Manifests use freeze() directives to include files in the frozen filesystem. Frozen files are baked into the firmware and cannot be modified at runtime.

Version Management

Versions are tracked in:

CHANGELOG.md: User-facing changelog with release history
App versions in META-INF/MANIFEST.JSON files
OS update system checks hardware_id from mpos.info.get_hardware_id()

Current stable version: 0.3.3 (as of latest CHANGELOG entry)

Critical Code Locations

App lifecycle: internal_filesystem/lib/mpos/apps.py:execute_script()
Activity base class: internal_filesystem/lib/mpos/app/activity.py
Package management: internal_filesystem/lib/mpos/content/package_manager.py
Intent system: internal_filesystem/lib/mpos/content/intent.py
UI initialization: internal_filesystem/main.py
Hardware init: internal_filesystem/boot.py
Config/preferences: internal_filesystem/lib/mpos/config.py
Top menu/drawer: internal_filesystem/lib/mpos/ui/topmenu.py
Activity navigation: internal_filesystem/lib/mpos/activity_navigator.py

Common Utilities and Helpers

SharedPreferences: Persistent key-value storage per app

from mpos.config import SharedPreferences

# Load preferences
prefs = SharedPreferences("com.example.myapp")
value = prefs.get_string("key", "default_value")
number = prefs.get_int("count", 0)
data = prefs.get_dict("data", {})

# Save preferences
editor = prefs.edit()
editor.put_string("key", "value")
editor.put_int("count", 42)
editor.put_dict("data", {"key": "value"})
editor.commit()

Intent system: Launch activities and pass data

from mpos.content.intent import Intent

# Launch activity by name
intent = Intent()
intent.setClassName("com.micropythonos.camera", "Camera")
self.startActivity(intent)

# Launch with extras
intent.putExtra("key", "value")
self.startActivityForResult(intent, self.handle_result)

def handle_result(self, result):
    if result["result_code"] == Activity.RESULT_OK:
        data = result["data"]

UI utilities:

mpos.ui.async_call(func, *args, **kwargs): Safely call UI operations from background threads
mpos.ui.back_screen(): Navigate back to previous screen
mpos.ui.focus_direction: Keyboard/joystick navigation helpers
mpos.ui.anim: Animation utilities

MicroPythonOS supports keyboard/joystick navigation through LVGL's focus group system. This allows users to navigate apps using arrow keys and select items with Enter.

Basic focus handling pattern:

def onCreate(self):
    # Get the default focus group
    focusgroup = lv.group_get_default()
    if not focusgroup:
        print("WARNING: could not get default focusgroup")

    # Create a clickable object
    button = lv.button(screen)

    # Add focus/defocus event handlers
    button.add_event_cb(lambda e, b=button: self.focus_handler(b), lv.EVENT.FOCUSED, None)
    button.add_event_cb(lambda e, b=button: self.defocus_handler(b), lv.EVENT.DEFOCUSED, None)

    # Add to focus group (enables keyboard navigation)
    if focusgroup:
        focusgroup.add_obj(button)

def focus_handler(self, obj):
    """Called when object receives focus"""
    obj.set_style_border_color(lv.theme_get_color_primary(None), lv.PART.MAIN)
    obj.set_style_border_width(2, lv.PART.MAIN)
    obj.scroll_to_view(True)  # Scroll into view if needed

def defocus_handler(self, obj):
    """Called when object loses focus"""
    obj.set_style_border_width(0, lv.PART.MAIN)

Key principles:

Get the default focus group with lv.group_get_default()
Add objects to the focus group to make them keyboard-navigable
Use lv.EVENT.FOCUSED to highlight focused elements (usually with a border)
Use lv.EVENT.DEFOCUSED to remove highlighting
Use theme color for consistency: lv.theme_get_color_primary(None)
Call scroll_to_view(True) to auto-scroll focused items into view
The focus group automatically handles arrow key navigation between objects

Example apps with focus handling:

Launcher (builtin/apps/com.micropythonos.launcher/assets/launcher.py): App icons are focusable
Settings (builtin/apps/com.micropythonos.settings/assets/settings_app.py): Settings items are focusable
Connect 4 (apps/com.micropythonos.connect4/assets/connect4.py): Game columns are focusable

Other utilities:

mpos.apps.good_stack_size(): Returns appropriate thread stack size for platform (16KB ESP32, 24KB desktop)
mpos.wifi: WiFi management utilities
mpos.sdcard.SDCardManager: SD card mounting and management
mpos.clipboard: System clipboard access
mpos.battery_voltage: Battery level reading (ESP32 only)

Animations and Game Loops

MicroPythonOS supports frame-based animations and game loops using the TaskHandler event system. This pattern is used for games, particle effects, and smooth animations.

The update_frame() Pattern

The core pattern involves:

Registering a callback that fires every frame
Calculating delta time for framerate-independent physics
Updating object positions and properties
Rendering to LVGL objects
Unregistering when animation completes

Basic structure:

from mpos.apps import Activity
import mpos.ui
import time
import lvgl as lv

class MyAnimatedApp(Activity):
    last_time = 0

    def onCreate(self):
        # Set up your UI
        self.screen = lv.obj()
        # ... create objects ...
        self.setContentView(self.screen)

    def onResume(self, screen):
        # Register the frame callback
        self.last_time = time.ticks_ms()
        mpos.ui.task_handler.add_event_cb(self.update_frame, 1)

    def onPause(self, screen):
        # Unregister when app goes to background
        mpos.ui.task_handler.remove_event_cb(self.update_frame)

    def update_frame(self, a, b):
        # Calculate delta time for framerate independence
        current_time = time.ticks_ms()
        delta_ms = time.ticks_diff(current_time, self.last_time)
        delta_time = delta_ms / 1000.0  # Convert to seconds
        self.last_time = current_time

        # Update your animation/game logic here
        # Use delta_time to make physics framerate-independent

Framerate-Independent Physics

All movement and physics should be multiplied by delta_time to ensure consistent behavior regardless of framerate:

# Example from QuasiBird game
GRAVITY = 200  # pixels per second²
PIPE_SPEED = 100  # pixels per second

def update_frame(self, a, b):
    current_time = time.ticks_ms()
    delta_time = time.ticks_diff(current_time, self.last_time) / 1000.0
    self.last_time = current_time

    # Update velocity with gravity
    self.bird_velocity += self.GRAVITY * delta_time

    # Update position with velocity
    self.bird_y += self.bird_velocity * delta_time

    # Update bird sprite position
    self.bird_img.set_y(int(self.bird_y))

    # Move pipes
    for pipe in self.pipes:
        pipe.x -= self.PIPE_SPEED * delta_time