# Changelog

All notable changes to this project will be documented in this file.

## [1.7.6] - 2026-01-28

### Changed
- **Documentation Overhaul**: Consolidated and reorganized the entire documentation suite. Migrated to Sphinx with the Furo theme and added support for PDF generation.
- **Language Standardization**: All documentation and comments have been reviewed and standardized to English.
- **Project Structure**: Cleaned up the `docs/` directory, removing redundant and overlapping files in favor of a structured Sphinx hierarchy.

## [1.7.5] - 2026-01-27

### Added
- **Standalone Simulator Integration**: Switched the standard validation and testing workflow to use the `caux-sim` standalone simulator. This provides higher protocol faithfulness and better parity with real hardware.
- **Experimental Test Pool**: Created `tests/experimental/` to host tests requiring specialized synchronization with external simulators.

### Changed
- **Async Driver Architecture**: Refactored `GOTO` and `SYNC` operations into non-blocking background tasks. The driver now remains fully responsive to INDI commands (like `ABORT`) during movement.
- **Improved Abort Logic**: The `TELESCOPE_ABORT_MOTION` command now immediately cancels any active background movement tasks for instant response.
- **Test Robustness**: Updated integration tests with increased timeouts and better state transition awareness to accommodate standalone simulator latency.

### Fixed
- **Race Conditions**: Resolved a race condition where GoTo status could blink between `Busy` and `Idle` due to task completion timing.
- **Sync Point Management**: Fixed a coordinate capturing bug in the `SYNC` command by ensuring RA/Dec are cached at the exact moment the command is received.

## [1.7.0] - 2026-01-20

### Changed
- **Configuration Format**: Migrated from YAML (`config.yaml`) to TOML (`config.default.toml`, `config.toml`). This utilizes the standard library `tomllib` in Python 3.11+, reducing external dependencies.
- **Logging System**: Replaced all `print()` statements with the standard `logging` module. Logs are now properly routed to `stderr` with appropriate levels (INFO, ERROR, DEBUG), ensuring compliance with INDI protocol requirements.
- **Import Structure**: Cleaned up internal imports in `celestron_indi_driver.py` and other modules, removing defensive `try...except` blocks in favor of standard relative imports.
- **Script Updates**: Updated all validation scripts (`hit_validation.py`, `ppt_accuracy.py`, `pec_measure.py`) to support the new TOML configuration and hierarchical loading.

### Fixed
- **Test Stability**: Resolved import errors in the test suite caused by circular or incorrect relative imports.
- **Dependency Bloat**: Removed `pyyaml` and `types-PyYAML` from project dependencies.

## [1.6.5] - 2026-01-12

### Added
- **Type Hints**: Added comprehensive type annotations to all core modules and simulator components for better maintainability and robustness.
- **GitHub Actions CI**: Set up a professional CI pipeline verifying tests and type correctness on Python 3.11, 3.12, and 3.13.
- **Adaptive Alignment Model**: The mathematical model now scales with the number of alignment points (SVD for 1-2 pts, 4-parameter for 3-5 pts, 6-parameter for 6+ pts).
- **Sub-step Rate Estimation**: Maintains floating-point precision during velocity calculation to eliminate quantization drift.
- **Simulation Backdoor**: Added `SIM_GET_SKY_POSITION` (0xFF) for ground-truth verification in simulation.

### Fixed
- **Non-Sidereal Tracking**: Fixed a bug where Moon and Planet tracking used stale target coordinates. The loop now correctly re-calculates target positions at each tick.
- **Iterative GoTo**: Corrected the two-stage slew implementation (Fast + Precision) and fixed coordinate synchronization during Sync operations.
- **CI Compatibility**: Removed hardcoded `venv` references in test suites, enabling execution in containerized environments.
- **Driver Robustness**: Fixed property inheritance and added safety checks for hardware communicator connection state.
- **Tracking Stability**: Switched to a 30s differentiation window, matching the reference driver's high-inertia approach.
- **Documentation**: Updated `DEVELOPMENT_PLAN.md` and `GEMINI.md` to reflect the latest project status. Added MathJax and MyST dollarmath extensions for professional LaTeX rendering.

## [1.6.4] - 2026-01-09

### Added
- **Real-World Validation Script**: New standalone routine `scripts/real_world_validation.py` for testing 4-star local alignment and tracking accuracy under simulated mechanical imperfections (Periodic Error, Cone Error, Backlash).

### Fixed
- **Sub-step Precision in Rate Estimation**: Refined guide rate conversion to minimize truncation errors by maintaining floating-point precision during velocity calculation before rounding to 24-bit AUX commands.

## [1.6.3] - 2026-01-09

### Added
- **High-Accuracy Dead Reckoning**: Optimized tracking loop for sub-arcsecond stability.
- **Improved Differentiation**: Increased sampling interval ($dt=5.0s$) to reduce quantization noise in velocity estimation.

### Fixed
- **Rate Quantization**: Reduced tracking drift by an order of magnitude through smoother numerical derivatives.

## [1.6.2] - 2026-01-09

### Added
- **Automated Tracking Accuracy Test**: New test suite `tests/test_tracking_accuracy.py` that programmatically measures drift, jitter, and pointing error.
- **Target Locking**: Implemented `current_target_ra/dec` to prevent feedback drift during sidereal tracking.

### Fixed
- **Iterative GoTo Refinement**: Improved absolute pointing accuracy by implementing a two-stage slew (Fast Approach + Precision Centering).
- **GoTo Jumping**: Eliminated redundant slew iterations and refined anti-backlash suppression during the fast phase.
- **Tracking Stability**: Improved tracking rate derivative calculation by reducing the sample interval ($dt=0.1s$) and using a consistent time base.
- **Web Console Precision**: Increased telemetry display precision for velocities to 4 decimal places, enabling visualization of sidereal rates.

## [1.6.1] - 2026-01-08

### Added
- **Visual Digital Twin Finalization**: Completed the integration of Three.js visualization with real-time driver telemetry.
- **Enhanced Sky View**: Verified FOV representation against bright stars (Polaris, Sirius, Vega).

## [1.6.0] - 2026-01-08

### Added
- **Visual Digital Twin Enhancements**:
  - Added **Angle Indicators**: Compass ring and N/S markers in the 3D view.
  - Added **Schematic Sky View**: A real-time 10° field-of-view display showing nearby bright stars (using `ephem` data).
  - Expanded Telemetry: Added velocities and power consumption to the web console.
- **Improved Packaging**: Support for `[simulator]` and `[web]` optional extras.

### Fixed
- Refined Evolution 8" dimensions for better faithfulness to real hardware.
- Synchronized coordinate systems between physics engine and 3D visualization.

## [1.5.1] - 2026-01-08

### Added
- **Web Console & Digital Twin**: Implemented an optional 3D visualization console using Three.js and FastAPI.
- **Evolution 8" Model**: Added a faithful geometric model of the Evolution 8 mount for visual validation.
- **Collision Visualization**: Real-time visual warnings in the web console if the camera clearance is insufficient.
- **Optional Dependencies**: Support for `[simulator]` and `[web]` extras in the Python package.

## [1.4.0] - 2026-01-07

### Added
- **PyPI Packaging**: Refactored project to modern `src` layout and added `pyproject.toml` for standard distribution.
- **CLI Entry Points**: Added `indi-celestron-aux` and `celestron-aux-simulator` as standalone commands.
- **Centralized Configuration**: All driver and validation settings are now managed via a single `config.yaml` with support for CLI and Environment overrides.
- **Internal INDI Server**: Integrated `indipyserver` allowing the driver to run as a standalone network server.

## [1.3.0] - 2026-01-07

### Added
- **Homing Support**: Implemented `HOME` INDI property for automated homing/leveling sequences.
- **Reference Parity**: Verified protocol parity with `indi-celestronaux` C++ driver.
- **Improved Test Suite**: Added `test_11_homing` and improved wrap-around awareness in assertions.

## [1.2.0] - 2026-01-07

### Added
- **Dynamic Mount Detection**: Implemented a capabilities matrix mapping Model IDs to mount types (Alt-Az, GEM) and features.
- **RTC Management**: Support for reading and writing Real-Time Clock data to the mount (`GPS_SET_TIME`, `GPS_SET_DATE`).
- **Site Management**: Implemented writing Latitude/Longitude back to the mount hardware.
- **Power Management**: New `AUX_POWER` property for reporting supply voltage and current consumption (Evolution battery module).
- **Extended GPS Status**: Added satellite count reporting.
- **Simulator Upgrades**: Added support for RTC, Location setting, and Battery telemetry commands.

### Changed
- **Property Standardization**: Renamed motion switches to standard `SLEW_NORTH/SOUTH/WEST/EAST`.
- **Slew Rate Compliance**: Added standard `TELESCOPE_SLEW_RATE` switch vector (Guide, Centering, Find, Max) mapped to the native 1-9 scale.
- Updated `scripts/hit_validation.py` to match the new property names.

## [1.1.1] - 2026-01-07

### Fixed
- **External Simulator Support**: Resolved test failures occurring when running against an external TUI simulator.
- **Test Robustness**: Increased GoTo step tolerance to 500 steps to account for simulator jitter and Periodic Error.
- **Timing & Timeouts**: Increased test timeouts to 60-90 seconds to accommodate realistic slew speeds (4°/s) and TUI overhead.
- **Test Isolation**: Added explicit mount position and rate reset in `asyncSetUp` for functional and safety tests.
- **Environment Variables**: Ensured `EXTERNAL_SIM` and `SIM_PORT` are respected by all test suites.

## [1.1.0] - 2026-01-07

### Added
- **Hardware Interaction Test (HIT)**: Interactive safety routine for physical mount testing (`scripts/hit_validation.py`).
- **Photography & Pointing Test (PPT)**: Automated accuracy measurement using INDI and ASTAP (`scripts/ppt_accuracy.py`).
- **Emergency Abort**: Support for `TELESCOPE_ABORT_MOTION` in the driver.
- **Residual-Aware Grid Thinning**: Improved alignment point management using consistency-weighted grid sectors.

### Changed
- Updated `AlignmentModel` to use 15° grid sectors for better sky coverage.
- Optimized functional tests for robustness against encoder jitter.

## [1.0.0] - 2026-01-07

### Added
- **Phase 11: Advanced Calibration** implemented.
- **6-Parameter Geometric Model**: Compenses for Rotation, Cone Error ($CH$), Non-Perpendicularity ($NP$), and Altitude Index error ($ID$).
- **Spatial Point Thinning**: Alignment points within 5 degrees are automatically replaced, ensuring even sky coverage and preventing local "clouds" of data from skewing the global model.
- **Refraction Correction**: Switchable atmospheric refraction correction in the driver logic.
- **Calibration Tab**: New INDI tab displaying measured mechanical errors and residuals.
- **Graceful Fallback**: The alignment system automatically switches between Identity, Axis-Angle, SVD, and Full Geometric models depending on the number of available stars.
- New test suite `tests/test_alignment_advanced.py`.

### Changed
- Refactored `AlignmentModel` to use `scipy.optimize.least_squares` for non-linear fitting.
- Updated `celestron_indi_driver.py` to support new calibration properties.
- Formalized dependencies in `requirements.txt` (`scipy`).

## [0.9.0] - 2026-01-07

### Added
- **Phase 9: Comprehensive Test Documentation**: Added detailed Google-style docstrings to all 23+ tests, documenting methodology and expected results.
- **Phase 10: Simulator Realism**: Added tunable imperfections to the NSE Simulator:
  - **Mechanical Backlash**: Simulates gear play when reversing.
  - **Periodic Error (PE)**: Sinusoidal tracking error in RA/Azimuth.
  - **Cone Error**: Mechanical offset in Altitude axis.
  - **Encoder Jitter**: Random Gaussian noise in position reporting.
- **Simulator Core Test Suite**: Added `tests/test_simulator_core.py` to verify simulator physics and protocol compliance.
- New TUI Panel: Displays active imperfections in the simulator interface.

### Changed
- Improved `config.yaml` to support simulator-specific settings.
- Refactored `NexStarScope` to support simulation of mechanical errors.

## [0.8.0] - 2026-01-07

### Added
- **Phase 8: Multi-Point SVD Alignment** implemented.
- Replaced 3-point matrix inversion with a robust **Singular Value Decomposition (SVD)** solver.
- Support for an **unlimited number of alignment stars** with automatic fit optimization.
- **RMS Error** reporting in INDI (arcseconds residual).
- **Proximity Weighting (Local Bias)**: Heavy weighting of points near the target for high-precision local models.
- **Automatic Pruning**: Configurable circular buffer for alignment points (useful for long AP sessions).
- Comprehensive documentation in `docs/` and `simulator/`.
- New test suite `tests/test_alignment_svd.py`.

### Changed
- Refactored `alignment.py` to use `numpy` for linear algebra.
- Updated `celestron_indi_driver.py` to use the new alignment properties and logic.
- Optimized alignment point management (Clear Last, Clear All).

## [0.7.0] - 2026-01-07

### Added
- **Phase 7: Moving Objects Support** implemented.
- Support for tracking **Sun, Moon, and Planets** using `ephem` library.
- Support for **Satellite tracking** using **TLE** data (`TLE_DATA` property).
- New INDI properties: `TARGET_TYPE`, `PLANET_SELECT`, `TLE_DATA`.
- Implemented `_get_target_equatorial` for dynamic coordinate resolution.
- New test suite `tests/test_moving_objects.py` verifying non-sidereal tracking.

### Changed
- **Simulator Calibration**: Adjusted slew speeds to match **Celestron Evolution** ($4^\circ/s$ Fast, $1^\circ/s$ Slow).
- **Test Optimization**: Updated functional tests to use realistic speeds and longer timeouts.

## [0.6.1] - 2026-01-06

### Fixed
- Fixed **Altitude wrap-around bug** in simulator where negative altitudes were reported as large positive values (e.g., 337.5° instead of -22.5°).
- Treated Altitude as a **linear axis** instead of a full circle to avoid incorrect movement directions in GoTo.
- Added support for **signed angle representation** in simulator TUI for Altitude.
- Normalized incoming motor controller coordinates to handle signed values correctly in driver logic.
- All 17 automated tests (Functional, Safety, Math) verified passing.

## [0.6.0] - 2026-01-06

### Added
- **Phase 6: Safety & Accessories** implemented.
- New INDI properties: `TELESCOPE_LIMITS`, `TELESCOPE_CORDWRAP`, `TELESCOPE_CORDWRAP_POS`.
- Support for **Focuser** accessory (`ABS_FOCUS_POSITION`).
- Support for **GPS** module (`GPS_REFRESH`, automatic location sync).
- New test suite `tests/test_safety.py` for safety features.
- Enforced software slew limits in `goto_position` and background monitoring.

### Changed
- **Internationalization**: All documentation, comments, and UI strings translated to **English**.
- Increased simulator slew rates: `GOTO_FAST` at 15 deg/s, `GOTO_SLOW` at 0.5 deg/s.
- Improved AUX command logging in simulator TUI.
- Fixed latitude/longitude parsing from GPS module.

## [0.5.3] - 2026-01-06

### Added
- New functional test `test_6b_robustness_pole` checking driver stability near the celestial pole.

### Fixed
- Increased GoTo speeds in simulator (Fast: 5°/s, Slow: 1°/s) and extended timeouts in the driver, eliminating timeout errors in tests.
- Improved physical motion model in simulator (smoother braking and no oscillations at target).
- Secured mathematical functions against precision errors near singularities (poles, zenith).

## [0.5.2] - 2026-01-06

### Added
- Debug mode (`-d` / `--debug`) in simulator, reporting operation parameters to `stderr`.
- Implementation of a sliding window for sky velocity calculations (vRA, vDec) to eliminate numerical noise.

### Fixed
- Fixed oscillations of displayed vRA/vDec speeds in the TUI interface.
- Improved velocity calculation stability in headless mode.

## [0.5.1] - 2026-01-06

### Added
- Extension of the simulator TUI interface with motor rotation speed display (vAlt, vAzm) in °/s.
- Display of celestial sphere movement speeds (vRA, vDec) in "/s (arcsec/s).
- Improved styling of the Textual interface.

## [0.5.0] - 2026-01-05

### Added
- Modern simulator TUI interface based on the **Textual** library (replacing curses).
- Advanced **Alignment system** based on 3x3 matrix transformations.
- Support for `TELESCOPE_ON_COORD_SET` property (SLEW, TRACK, SYNC modes).
- Ability to add alignment points (max 3 stars) to correct mount alignment errors.
- New test suite: `test_10_alignment_3star` and alignment math tests (`tests/test_alignment_math.py`).
- Support for `EXTERNAL_SIM` environment variable in functional tests.

### Changed
- Full code documentation (Google Style Docstrings) for all modules.
- Removed deprecated function call warnings (`utcnow`, `get_event_loop`).
- Improved `Park` logic – handling step counter wrap-around.
- Changed configuration format to YAML (`config.yaml`).

## [0.4.0] - 2026-01-05

### Added
- Implementation of **Anti-backlash GoTo** approach logic (Phase 4).
- New INDI properties: `GOTO_APPROACH_MODE` (DISABLED, FIXED_OFFSET, TRACKING_DIRECTION) and `GOTO_APPROACH_OFFSET`.
- Advanced tracking loop based on **2nd order prediction** (Phase 5).
- Angular velocity ($\omega$) determination algorithm using symmetric differential expression.
- New INDI properties: `TELESCOPE_TRACK_MODE` (Sidereal, Solar, Lunar).
- Communication locking mechanism (`asyncio.Lock`) in `AUXCommunicator` to ensure safe concurrent access to the AUX bus.
- New functional tests: `test_7_approach_logic`, `test_8_approach_tracking_direction`, `test_9_predictive_tracking`.

### Changed
- Refactored GoTo method to support multi-stage movement (Stage 1: Fast Approach, Stage 2: Slow Final).
- `equatorial_to_steps` method now supports `time_offset` parameter.

## [0.3.0] - 2026-01-05

### Added
- Integration with `ephem` library for astronomical coordinate transformations.
- Support for INDI property `GEOGRAPHIC_COORD` (Latitude, Longitude, Elevation).
- Support for INDI property `EQUATORIAL_EOD_COORD` (RA/Dec).
- Implementation of GoTo logic for equatorial coordinates (RA/Dec -> Alt/Az -> Encoders).
- Automatic calculation and reporting of current RA/Dec based on encoder position.
- New functional test `test_6_equatorial_goto` verifying transformation correctness.
- Configuration file `config.yaml` support with default location in Bębło.
- Stellarium integration instructions for visual verification.

### Changed
- Improved `handle_equatorial_goto` robustness against missing event data.

## [0.2.1] - 2026-01-05

### Added
- Complete set of functional tests in `tests/` directory based on `unittest`.
- Tests cover: Firmware Info, GoTo Precision, Tracking Logic, Park/Unpark, Connection Robustness.
- Automatic capture of simulator logs during tests (`test_sim.log`).

### Changed
- Improved robustness of `handle_sync`, `handle_park`, `handle_unpark`, `handle_guide_rate` methods against missing event data (facilitates testing).
- Synchronized project state and roadmap.

## [0.2.0] - 2026-01-05

### Added
- TCP connection support in `AUXCommunicator` (URL `socket://host:port`).
- "Echo Skipping" mechanism in the AUX protocol, enabling operation on single-wire buses.
- Headless mode (`-t` / `--text`) in the telescope simulator.
- `ephem` library support in the simulator.
- Implementation of `TELESCOPE_GUIDE_RATE` property in the INDI driver.
- Verified control loop operation (Slew/Read/Tracking) with an extended automated test.

### Changed
- Full refactoring of `celestron_indi_driver.py` to adapt to `indipydriver 3.0.4` API.
- Fixed `NumberMember` constructor errors (argument order).
- Improved AUX frame reading stability (using `readexactly`).
- Removed erroneous null bytes from source files.

## [0.1.0] - 2026-01-05

### Added
- Initial implementation of the Celestron AUX driver in Python.
- Basic INDI properties: `CONNECTION`, `PORT`, `FIRMWARE_INFO`, `MOUNT_POSITION`.
- Motion control: `SLEW_RATE`, `TELESCOPE_MOTION_NS/WE`, `TELESCOPE_ABSOLUTE_COORD`.
- Mount synchronization and parking.
- Telescope simulator with TUI (curses) interface.
- Implementation of binary AUX protocol (packet packing/unpacking, checksums).