EPIC 1: Platform Foundation & System Infrastructure

[andre-stefanov]

EPIC 1: Platform Foundation & System Infrastructure

Zephyr RTOS foundation with hardware support and safety systems

Overview

This EPIC establishes the foundational Zephyr RTOS platform with primary hardware support, safety systems, power management, and development infrastructure for the OpenAstroFirmware project.

Epic Components

1.1 Zephyr RTOS Platform Setup

🔴 priority:critical
Requirements: REQ-SYS-002, REQ-SYS-003, REQ-HW-001, REQ-HW-002

Acceptance Criteria:

• REQ-SYS-002: 32-bit microcontroller platform support verified #32
• REQ-SYS-003: UART communication interface operational #27
• REQ-HW-001: MKS Robin Nano (STM32F407xx) board support functional #34
• REQ-HW-002: Native simulation capabilities for development and testing #33

1.2 Hardware Abstraction & Extensibility

🟠 priority:high
Requirements: REQ-HW-004, REQ-HW-EXT-001, REQ-HW-EXT-002, REQ-HW-EXT-003, REQ-HW-EXT-004

Acceptance Criteria:

• REQ-HW-004: Multiple hardware variations supported through compile-time configuration
• REQ-HW-EXT-001: Hardware abstraction layer allows new microcontroller boards without core changes
• REQ-HW-EXT-002: Board-specific configuration files define hardware capabilities and pin mappings
• REQ-HW-EXT-003: Zephyr device tree system enables hardware-specific configurations
• REQ-HW-EXT-004: Standardized interfaces for new hardware platforms maintain firmware compatibility

1.3 Safety & Emergency Systems

🔴 priority:critical
Requirements: REQ-SAF-001, REQ-SAF-002, REQ-SAF-003, REQ-SAF-004, REQ-SAF-005

Acceptance Criteria:

• REQ-SAF-001: Software limits implemented to prevent mechanical damage
• REQ-SAF-002: Emergency stop functionality immediately halts all motor movements
• REQ-SAF-003: Collision detection and prevention mechanisms active
• REQ-SAF-004: End switch detection supported for RA and DEC axes
• REQ-SAF-005: Timeout mechanisms implemented for command responses

1.4 Power Management & System Monitoring

🔴 priority:critical
Requirements: REQ-PWR-001, REQ-PWR-002, REQ-MON-001, REQ-REL-001 through REQ-REL-007

Acceptance Criteria:

• REQ-PWR-001: Basic power management capabilities implemented
• REQ-PWR-002: Graceful shutdown procedures functional
• REQ-MON-001: System status monitoring and error reporting active
• REQ-REL-001: Comprehensive error handling implemented for all major subsystems
• REQ-REL-002: Meaningful error messages and status codes provided
• REQ-REL-003: Graceful recovery from communication errors implemented
• REQ-REL-004: System state consistency maintained during error conditions
• REQ-REL-005: Continued operation with non-critical errors supported
• REQ-REL-006: Input parameter validation implemented for all interfaces
• REQ-REL-007: Watchdog mechanisms implemented for critical operations

1.5 Development & Testing Infrastructure

🟠 priority:high
Requirements: REQ-DEV-001, REQ-DEV-002, REQ-DEV-003, REQ-DEV-004, REQ-TEST-001, REQ-TEST-002, REQ-TEST-003

Acceptance Criteria:

• REQ-DEV-001: West build system support for project management
• REQ-DEV-002: CMake build system integration functional
• REQ-DEV-003: Comprehensive logging capabilities implemented for debugging
• REQ-DEV-004: In-hardware debugging capabilities supported
• REQ-TEST-001: Automated test suites included for major components
• REQ-TEST-002: Unit testing supported for individual modules
• REQ-TEST-003: Integration testing with hardware simulation supported

Implementation Context

Current State

• Zephyr RTOS v4.1.0 is currently configured (needs upgrade to v4.2.0)
• MKS Robin Nano board support exists in boards/mks/robin_nano/
• Basic west build system and CMake integration functional
• Zephyr logging infrastructure established with LOG_MODULE_REGISTER pattern

Architecture Requirements

• Dual-app architecture: app/ (main firmware) + lib/ (reusable components)
• C++20 for application layer, C for low-level implementations
• Zephyr module structure for reusability (zephyr/module.yml)

Build & Test Infrastructure

west build -b robin_nano                    # Standard build
west build -b robin_nano -- -DEXTRA_CONF_FILE=debug.conf  # Debug build
west twister -T . -p robin_nano             # Run all tests

Success Metrics

• Zephyr RTOS v4.2.0 successfully integrated manifest: update west.yml to point to v4.2 #6
• Safety systems prevent hardware damage
• Comprehensive error handling with graceful recovery
• Development environment supports efficient debugging and testing
• Foundation supports future EPIC implementations

Dependencies

None - This is the foundation EPIC that enables all other EPICs

Next Steps

Upon completion of this EPIC, the following EPICs can begin:

• EPIC 2: LX200 Protocol Implementation (after 1.1)
• EPIC 3: Stepper Motor Control System (after 1.1)
• EPIC 5: Configuration & Persistence Systems (after 1.1)