|
| 1 | +````instructions |
| 2 | +# OpenAstroFirmware AI Agent Instructions |
| 3 | +
|
| 4 | +This is firmware for DIY astronomical telescope mounts, built on Zephyr RTOS. It's a modern C++20 rewrite of the successful OpenAstroTracker v1 firmware, emphasizing maintainability and advanced features. |
| 5 | +
|
| 6 | +## Architecture Overview |
| 7 | +
|
| 8 | +**Build System**: Zephyr RTOS v4.1.0 with west build tool |
| 9 | +**Target Hardware**: MKS Robin Nano (STM32F407-based) boards |
| 10 | +**Languages**: C++20 primary, with C for low-level protocol implementations |
| 11 | +**Structure**: Dual-app architecture - `app/` (main firmware) + `lib/` (reusable components) |
| 12 | +
|
| 13 | +Key directories: |
| 14 | +- `app/` - Main Zephyr application with mount control logic |
| 15 | +- `lib/lx200/` - LX200 telescope protocol implementation (C) |
| 16 | +- `boards/mks/robin_nano/` - Custom board definition and device tree |
| 17 | +- `tests/` - Comprehensive test suites using Zephyr Twister |
| 18 | +- `zephyr/module.yml` - Zephyr module configuration |
| 19 | +
|
| 20 | +## Development Workflow |
| 21 | +
|
| 22 | +### Building & Testing |
| 23 | +```bash |
| 24 | +west build -b robin_nano # Standard build |
| 25 | +west build -b robin_nano -- -DEXTRA_CONF_FILE=debug.conf # Debug build |
| 26 | +west twister -T . -p robin_nano # Run all tests |
| 27 | +west twister -T tests/lib/lx200/ # Run specific test suite |
| 28 | +``` |
| 29 | +
|
| 30 | +### Configuration Layers |
| 31 | +- **Kconfig**: `prj.conf` (base) + `debug.conf` (debug overlay) |
| 32 | +- **Device Tree**: Custom STM32F407 board in `boards/mks/robin_nano/` |
| 33 | +- **Build Configs**: Use `-DEXTRA_CONF_FILE=debug.conf` for development |
| 34 | +
|
| 35 | +## Code Patterns & Conventions |
| 36 | +
|
| 37 | +### Language Split Pattern |
| 38 | +**C++20 Application Layer** (`app/src/`): |
| 39 | +```cpp |
| 40 | +#include <mount/Mount.hpp> |
| 41 | +Mount mount; // Main astronomical mount controller |
| 42 | +``` |
| 43 | +
|
| 44 | +**C Protocol Layer** (`lib/lx200/`): |
| 45 | +```c |
| 46 | +lx200_parser_state_t parser_state; |
| 47 | +lx200_parse_command_string(cmd_string, &command); |
| 48 | +``` |
| 49 | +
|
| 50 | +### Logging Infrastructure |
| 51 | +Every module uses Zephyr structured logging: |
| 52 | +```cpp |
| 53 | +LOG_MODULE_REGISTER(ModuleName, CONFIG_APP_LOG_LEVEL); |
| 54 | +// Available: LOG_DBG(), LOG_INF(), LOG_WRN(), LOG_ERR() |
| 55 | +``` |
| 56 | +
|
| 57 | +### LX200 Protocol Implementation |
| 58 | +Commands follow `:COMMAND[params]#` format. Current implementation status: |
| 59 | +- ✅ **Parser Framework**: Command parsing, family classification |
| 60 | +- ⏳ **Coordinate Functions**: All `lx200_parse_*_coordinate()` are stubs |
| 61 | +- ⏳ **Formatting Functions**: All `lx200_format_*()` are stubs |
| 62 | +
|
| 63 | +Example of incomplete implementation pattern: |
| 64 | +```c |
| 65 | +lx200_parse_result_t lx200_parse_ra_coordinate(const char *str, lx200_coordinate_t *coord) { |
| 66 | + LOG_WRN("Function not implemented yet"); |
| 67 | + return LX200_PARSE_ERROR; // All coordinate functions are stubs |
| 68 | +} |
| 69 | +``` |
| 70 | +
|
| 71 | +## Testing Strategy |
| 72 | +
|
| 73 | +### Test-Driven Development Pattern |
| 74 | +Tests serve as specifications for unimplemented features in `tests/lib/lx200/`: |
| 75 | +
|
| 76 | +**Working Tests** (verify current functionality): |
| 77 | +- Parser state management |
| 78 | +- Command family identification (A,B,C,D,F,G,g,H,I,L,M,P,Q,R,S,T,U) |
| 79 | +- Basic command/parameter separation |
| 80 | +
|
| 81 | +**Specification Tests** (currently failing, define requirements): |
| 82 | +- Coordinate parsing (RA: `HH:MM:SS`, Dec: `sDD*MM:SS`) |
| 83 | +- Time/date parsing (`HH:MM:SS`, `MM/DD/YY`) |
| 84 | +- Response formatting functions |
| 85 | +
|
| 86 | +Run with: `west twister -T tests/lib/lx200/` |
| 87 | +
|
| 88 | +### Configuration Testing |
| 89 | +Two build configurations tested via `sample.yaml`: |
| 90 | +- `app.default`: Production configuration |
| 91 | +- `app.debug`: Debug configuration with `CONFIG_APP_LOG_LEVEL_DBG=y` |
| 92 | +
|
| 93 | +## Project-Specific Context |
| 94 | +
|
| 95 | +### Astronomical Domain Knowledge |
| 96 | +- **Coordinate Systems**: RA/Dec (celestial), Alt/Az (horizontal) |
| 97 | +- **Precision Modes**: High (`HH:MM:SS`) vs Low (`HH:MM.T`) coordinate formats |
| 98 | +- **LX200 Compatibility**: Industry standard for telescope communication |
| 99 | +- **Mount Types**: Equatorial tracking, Alt-azimuth positioning |
| 100 | +
|
| 101 | +### Critical Implementation Details |
| 102 | +**Parameter Detection Logic** (needs improvement): |
| 103 | +```c |
| 104 | +// Current: oversimplified - only checks 'S' commands |
| 105 | +bool lx200_command_has_parameter(const char *command) { |
| 106 | + return (command[0] == 'S'); // Missing many parameter commands |
| 107 | +} |
| 108 | +``` |
| 109 | +
|
| 110 | +**Command Parsing Edge Cases**: |
| 111 | +- Special commands: `B+`, `B-`, `F+`, `F-`, `T+`, `T-` |
| 112 | +- Rate commands: `R0` through `R9` |
| 113 | +- Library commands and GPS commands also take parameters |
| 114 | +
|
| 115 | +### Development Status |
| 116 | +Early development phase. Focus on: |
| 117 | +1. Implementing coordinate parsing stubs in `lib/lx200/` |
| 118 | +2. Following existing test specifications in `tests/lib/lx200/` |
| 119 | +3. Using C for protocol layer, C++20 for application layer |
| 120 | +4. Maintaining Zephyr module structure for reusability |
| 121 | +
|
| 122 | +When implementing new features, always check corresponding tests first to understand expected behavior and formats. |
| 123 | +
|
| 124 | +```` |
0 commit comments