Document Version: 1.0
Date: August 2, 2025
Project: OpenAstroFirmware - Zephyr RTOS-based Telescope Mount Control System
Requirements Reference: specs/requirements.md
This document defines the high-level architectural design for OpenAstroFirmware, establishing the fundamental system structure, architectural patterns, and design principles that guide the implementation of requirements specified in the OpenAstroFirmware Requirements Specification.
The OpenAstroFirmware architecture is founded on the following core principles:
- Layered Architecture: Clear separation of concerns through well-defined abstraction layers
- Modular Design: Loosely coupled, highly cohesive components with standardized interfaces
- Hardware Abstraction: Platform-independent core logic with pluggable hardware drivers
- Real-time Determinism: Predictable timing behavior for tracking and control operations
- Extensibility by Design: Plugin-based architecture supporting future expansion
- Safety-First Approach: Fail-safe mechanisms and comprehensive error handling integrated at all levels
This document presents the architectural view of the system, focusing on:
- System decomposition and component relationships
- Architectural patterns and design decisions
- Data flow and control flow architectures
- Interface specifications and contracts
- Concurrency and threading models
- Extensibility mechanisms and plugin architectures
OpenAstroFirmware employs a Multi-Layered Service-Oriented Architecture with the following characteristics:
┌─────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ External Protocols │ User Interfaces │ Network Services │
├─────────────────────────────────────────────────────────────┤
│ APPLICATION LAYER │
│ Command Processing │ State Management │ Event Coordination │
├─────────────────────────────────────────────────────────────┤
│ SERVICE LAYER │
│ Mount Control │ Sensor Mgmt │ Config Service │
├─────────────────────────────────────────────────────────────┤
│ CORE LAYER │
│ Tracking Engine │ Safety Monitor │ Hardware Controllers │
├─────────────────────────────────────────────────────────────┤
│ HARDWARE ABSTRACTION LAYER │
│ Driver Interface │ Device Abstraction │ Platform │
├─────────────────────────────────────────────────────────────┤
│ PLATFORM LAYER │
│ Zephyr RTOS │ Hardware Platform │ BSP │
└─────────────────────────────────────────────────────────────┘
Layer Responsibilities:
- Presentation Layer: External communication interfaces and user interaction
- Application Layer: System orchestration and global state management
- Service Layer: Domain-specific business logic and high-level services
- Core Layer: Real-time operations and fundamental system capabilities
- Hardware Abstraction Layer: Platform-independent hardware access
- Platform Layer: Zephyr RTOS and hardware-specific implementations
Architectural Characteristics:
- Unidirectional Dependencies: Higher layers depend only on lower layers
- Interface-Based Communication: Well-defined contracts between layers
- Plugin Integration Points: Extensibility mechanisms at each layer
- Service Composition: Complex operations built from simpler services
Addresses Requirements: REQ-EXT-001, REQ-HW-EXT-001, REQ-STEP-EXT-001, REQ-SNS-EXT-001
The architecture is shaped by the following key requirements and constraints:
Performance Drivers (REQ-PERF-001 to REQ-PERF-007):
- Sub-arcsecond tracking precision
- 100ms command response time
- Real-time deterministic behavior
- Concurrent multi-axis operations
Extensibility Drivers (REQ-EXT-001 to REQ-EXT-012):
- Support for multiple hardware platforms
- Plugin-based driver architecture
- Future feature expansion capability
Safety and Reliability Drivers (REQ-SAF-001 to REQ-REL-007):
- Fail-safe operation modes
- Comprehensive error handling
- System state consistency
- Hardware protection mechanisms
Integration Drivers (REQ-COMPAT-001 to REQ-COMPAT-008):
- LX200 protocol compliance
- Multiple astronomy software compatibility
- Legacy hardware support
Addresses Requirements: REQ-COM-001 to REQ-COM-024, REQ-WEB-001 to REQ-WEB-008, REQ-UI-001 to REQ-UI-003
The presentation layer provides external interfaces and manages all communication with external systems and users.
- LX200 Protocol Engine: Stateless command parser and response generator
- Network Protocol Stack: HTTP/WebSocket services for web-based control
- Extension Protocol Framework: Pluggable protocol support for future additions
- Display Abstraction: Unified interface for various display technologies
- Input Device Framework: Event-driven input handling with device abstraction
- UI State Management: Screen navigation and context preservation
- Command Pattern: LX200 commands as executable objects
- Observer Pattern: UI updates driven by system state changes
- Adapter Pattern: Protocol-specific adapters for unified internal interfaces
Addresses Requirements: REQ-COM-007, REQ-MON-001, REQ-CFG-005 to REQ-CFG-008
The application layer orchestrates system behavior and maintains global state.
- Command Queue Manager: Asynchronous command processing with priority handling
- State Machine Controller: Global system state management and transitions
- Event Dispatcher: Centralized event routing and handling
- Resource Manager: Coordinate access to shared system resources
- Configuration Coordinator: Runtime configuration management and persistence
- Diagnostics Engine: System health monitoring and reporting
- State Pattern: System behavior changes based on operational states
- Mediator Pattern: Component communication through central coordinator
- Chain of Responsibility: Command processing pipeline
Addresses Requirements: REQ-MNT-001 to REQ-MNT-012, REQ-TRK-001 to REQ-COORD-005, REQ-CFG-001 to REQ-NVM-008
The service layer provides high-level domain services and business logic.
- Coordinate Transformation Engine: Celestial to mechanical coordinate conversion
- Motion Planning Service: Trajectory calculation and optimization
- Position Management Service: Current position tracking and synchronization
- Tracking Rate Calculator: Sidereal, solar, and lunar rate computation
- Guiding Correction Engine: Precision adjustment processing
- Time and Location Service: Astronomical time calculations
- Persistent Settings Manager: Non-volatile memory management
- Configuration Validation Engine: Settings validation and migration
- Backup and Restore Service: Configuration data protection
- Strategy Pattern: Different tracking algorithms and mount types
- Template Method: Common configuration management patterns
- Facade Pattern: Simplified interfaces to complex subsystems
Addresses Requirements: REQ-STEP-001 to REQ-STEP-018, REQ-SNS-001 to REQ-SNS-006, REQ-SAF-001 to REQ-SAF-005
The core layer implements fundamental system capabilities and real-time operations.
- Stepper Motor Controller: Abstract motor control with driver plugins
- Axis Control Engine: Independent RA/DEC axis management
- Motion Synchronization Service: Coordinated multi-axis movements
- Sensor Data Pipeline: Unified sensor reading and processing
- Sensor Fusion Engine: Multi-sensor data integration
- Calibration Management: Sensor-specific calibration procedures
- Limit Enforcement Engine: Software and hardware limit checking
- Emergency Stop Controller: Immediate motion cessation capability
- System Health Monitor: Continuous system status evaluation
- Factory Pattern: Driver instantiation based on configuration
- Observer Pattern: Sensor data distribution to interested components
- Proxy Pattern: Safety checks intercept motion commands
Addresses Requirements: REQ-HW-EXT-001 to REQ-HW-EXT-004, REQ-STEP-EXT-001 to REQ-STEP-EXT-005, REQ-SNS-EXT-001 to REQ-SNS-EXT-006
The HAL provides a consistent interface to diverse hardware platforms and devices.
- Device Driver Interface: Standardized contract for all hardware drivers
- Driver Registry: Dynamic driver discovery and registration
- Hardware Abstraction Interface: Platform-independent hardware access
- Board Support Framework: Hardware-specific initialization and configuration
- Peripheral Access Layer: Unified interface to MCU peripherals
- Device Tree Integration: Zephyr device tree utilization for hardware description
- Abstract Factory: Platform-specific driver creation
- Bridge Pattern: Separation of hardware interface from implementation
- Plugin Architecture: Runtime driver loading and registration
Addresses Requirements: REQ-PERF-004, REQ-PERF-007, REQ-STEP-004
The system employs a Priority-Based Multi-Threading Architecture with clear thread responsibilities:
Thread Hierarchy and Communication:
┌─────────────────┬─────────────────┬─────────────────┬──────────────┐
│ Safety Thread │ Tracking Thread │ Control Thread │ Comms Thread │
│ (Highest Prio) │ (High Prio) │ (Medium Prio) │ (Low Prio) │
├─────────────────┼─────────────────┼─────────────────┼──────────────┤
│ • Limit Checks │ • Sidereal │ • Command Exec │ • LX200 │
│ • Emergency Stop│ • Position │ • State Mgmt │ • Network │
│ • Health Monitor│ • Rate Calc │ • Coordination │ • UI Updates │
└─────────────────┴─────────────────┴─────────────────┴──────────────┘
- Lock-Free Queues: High-performance thread communication
- Event Broadcasting: Publish-subscribe event distribution
- Shared Memory Protection: Mutex-protected critical sections
- Priority Inheritance: Prevention of priority inversion
- Timeout-Based Operations: Deadlock prevention mechanisms
- Atomic Operations: Lock-free data access where possible
- Deterministic Scheduling: Predictable thread execution patterns
- Interrupt Service Isolation: Minimal ISR processing with deferred work
- Memory Pool Allocation: Predictable memory allocation patterns
Addresses Requirements: REQ-COM-006, REQ-COORD-001 to REQ-COORD-005, REQ-NVM-001 to REQ-NVM-008
The system processes information through well-defined data pipelines:
External Data Flow:
Commands → Parser → Validator → Executor → Response Generator → Output
Internal Data Flow:
Sensors → Filter → Transform → State Update → Event Broadcast → Actions
- Hierarchical Configuration: Layered settings with inheritance
- Versioned Data Structures: Backward compatibility and migration
- Atomic Updates: Transaction-like configuration changes
- Pipeline Processing: Staged data transformation and filtering
- Temporal Data Handling: Time-series data management
- Data Fusion Patterns: Multi-source data integration
- Centralized State Store: Single source of truth for system state
- State Change Notifications: Event-driven state propagation
- State Persistence: Critical state preservation across power cycles
- Memory Pool Strategy: Fixed-size pools for predictable allocation
- Buffer Management: Circular buffers for streaming data
- Stack Management: Per-thread stack monitoring and protection
Addresses Requirements: REQ-EXT-001 to REQ-EXT-012, REQ-HW-EXT-001 to REQ-HW-EXT-004
The system supports extensibility through a comprehensive plugin architecture:
- Standardized Driver Interface: Common contract for all hardware drivers
- Dynamic Driver Discovery: Runtime detection and registration
- Driver Capability Reporting: Self-describing driver capabilities
- Protocol Handler Registration: Runtime protocol addition
- Command Extension Points: New command family integration
- Response Format Extensibility: Custom response format support
- Service Plugin Interface: High-level feature additions
- Hook Points: Integration points throughout the system
- Dependency Management: Plugin dependency resolution
- Feature Flags: Runtime feature enabling/disabling
- Hardware Capability Detection: Automatic feature adaptation
- Compilation Variants: Build-time feature selection
- Abstract Interface Design: Interfaces designed for extensibility
- Versioning Strategy: Forward and backward compatibility planning
- Migration Framework: Automated upgrade path provision
Addresses Requirements: REQ-SAF-001 to REQ-SAF-005, REQ-REL-001 to REQ-REL-007
- Hardware Safety Layer: Physical limit switches and emergency stops
- Software Safety Layer: Algorithmic limit checking and validation
- Protocol Safety Layer: Command validation and confirmation
- Safe State Definition: Well-defined safe system states
- Graceful Degradation: Reduced functionality under fault conditions
- Recovery Procedures: Automatic and manual recovery mechanisms
- Local Error Handling: Component-level error management
- Service-Level Error Handling: Cross-component error coordination
- System-Level Error Handling: Global error management and recovery
- Error Code Propagation: Structured error information flow
- Exception Safety: Resource management under error conditions
- Error Event Broadcasting: System-wide error notification
- Watchdog Architecture: Multi-level system monitoring
- Health Check Framework: Continuous system health assessment
- Redundancy Patterns: Critical path redundancy where feasible
Addresses Requirements: REQ-PERF-001 to REQ-PERF-007
- Deterministic Execution Paths: Predictable timing behavior
- Priority-Based Scheduling: Critical task prioritization
- Interrupt Management: Minimal interrupt latency patterns
- Memory Pool Strategy: Predictable memory allocation
- CPU Usage Monitoring: Resource utilization tracking
- Resource Contention Resolution: Fair resource access patterns
- Algorithm Selection: Performance-appropriate algorithm choices
- Caching Architecture: Strategic data caching for performance
- Lazy Evaluation: Deferred computation where appropriate
Addresses Requirements: REQ-COMPAT-001 to REQ-COMPAT-008, REQ-COMP-001 to REQ-COMP-003
- Standard Protocol Compliance: Full LX200 protocol implementation
- Extension Protocol Support: Enhanced functionality while maintaining compatibility
- Multiple Client Support: Concurrent connection handling
- Legacy Hardware Support: Backward compatibility with existing hardware
- Modern Hardware Exploitation: Advanced feature utilization
- Cross-Platform Compatibility: Consistent behavior across platforms
- Protocol Compliance Framework: Automated compliance verification
- Testing Architecture: Comprehensive compatibility testing
- Certification Support: Standards compliance documentation
Addresses Requirements: REQ-FW-BUILD-001 to REQ-UX-005, REQ-CFG-001 to REQ-CFG-004
- Platform Abstraction: Single codebase, multiple targets
- Feature Configuration: Compile-time feature selection
- Automated Build Pipeline: Continuous integration and deployment
- Secure Update Mechanism: Signed firmware with verification
- Rollback Capability: Safe update with recovery options
- Configuration Preservation: Settings maintained across updates
- Hierarchical Configuration: Multiple configuration layers
- Dynamic Reconfiguration: Runtime setting changes
- Configuration Validation: Settings verification and migration
ADR-001: Multi-Layered Architecture
- Decision: Adopt layered architecture with clear abstraction boundaries
- Rationale: Separation of concerns, testability, maintainability
- Trade-offs: Performance overhead vs. code organization
ADR-002: Plugin-Based Extensibility
- Decision: Implement comprehensive plugin architecture
- Rationale: Future extensibility, hardware diversity support
- Trade-offs: Complexity vs. flexibility
ADR-003: Priority-Based Threading
- Decision: Use priority-based multi-threading with Zephyr RTOS
- Rationale: Real-time performance, deterministic behavior
- Trade-offs: Complexity vs. performance guarantees
ADR-004: Event-Driven Communication
- Decision: Implement event-driven inter-component communication
- Rationale: Loose coupling, scalability, maintainability
- Trade-offs: Debugging complexity vs. architectural flexibility
The OpenAstroFirmware architecture provides a robust, extensible, and maintainable foundation for telescope mount control systems. The design emphasizes:
- Modularity through clear layer separation and component isolation
- Extensibility via comprehensive plugin architectures
- Performance through real-time design patterns and optimization
- Safety via fail-safe mechanisms and comprehensive error handling
- Standards Compliance through well-defined protocol implementations
This architectural design provides the framework for detailed design and implementation. The next phases should focus on:
- Detailed Interface Specifications: Define precise contracts between components
- Implementation Planning: Break down architecture into implementable components
- Prototype Development: Validate architectural decisions through prototyping
- Testing Strategy: Develop comprehensive testing approaches for each layer
| Version | Date | Author | Description |
|---|---|---|---|
| 1.0 | August 2, 2025 | Andre Stefanov | Initial architectural design specification |
This document establishes the architectural foundation for OpenAstroFirmware implementation, providing guidance for detailed design and development phases.