Merge pull request #103 from IvanArkhipov1999/time-sync

Add time synchronization example for ESP32

Author: IvanArkhipov1999

c-library/xtensa-esp32/Cargo.lock

@@ -0,0 +1,96 @@
+# Martos RTOS Documentation
+
+Welcome to the Martos RTOS documentation. This directory contains comprehensive documentation for the Martos Real-Time Operating System.
+
+## Table of Contents
+
+1. [Time Synchronization System](./time-synchronization.md) - Complete guide to the distributed time synchronization system
+2. [Time Synchronization Diagrams](./time-sync-diagrams.md) - Visual diagrams and flowcharts for the time synchronization system
+
+## Time Synchronization System
+
+The Martos RTOS implements a sophisticated distributed time synchronization system using ESP-NOW communication protocol. This system enables precise time coordination across multiple ESP32 and ESP32-C6 devices in wireless networks.
+
+### Key Features
+
+- **Local Voting Protocol**: Implements a distributed consensus algorithm for time synchronization
+- **Cross-Platform Compatibility**: Works seamlessly between ESP32 (Xtensa) and ESP32-C6 (RISC-V) platforms
+- **ESP-NOW Communication**: Uses low-latency, broadcast communication for efficient synchronization
+- **Monotonic Time**: Ensures time can only accelerate, never go backwards
+- **Adaptive Quality**: Automatically adjusts synchronization parameters based on network conditions
+
+### Quick Start
+
+```rust
+use martos::time_sync::{TimeSyncManager, SyncConfig};
+
+// Initialize sync manager with defaults
+let mut sync_manager = TimeSyncManager::new(SyncConfig::default());
+
+// Enable synchronization
+sync_manager.enable_sync();
+```
+
+### Documentation Structure
+
+#### [Time Synchronization System](./time-synchronization.md)
+Comprehensive documentation covering:
+- System architecture and components
+- Communication protocol details
+- Local Voting Protocol algorithm
+- Message flow and synchronization cycles
+- Implementation details and virtual time system
+- Configuration parameters and tuning
+- Performance characteristics and metrics
+- Cross-platform compatibility
+- Usage examples and code samples
+- Troubleshooting guide
+
+#### [Time Synchronization Diagrams](./time-sync-diagrams.md)
+Visual documentation including:
+- System architecture overview
+- Message flow sequences
+- Local Voting Protocol algorithm flow
+- Virtual time system operation
+- Network topology examples
+- Performance metrics visualization
+- Cross-platform communication flow
+- Troubleshooting diagnosis flow
+
+## Examples
+
+The time synchronization system includes working examples for both ESP32 and ESP32-C6 platforms:
+
+- [`xtensa-esp32/time-sync`](../examples/rust-examples/xtensa-esp32/time-sync/) - ESP32 (Xtensa) example
+- [`risc-v-esp32-c6/time-sync`](../examples/rust-examples/risc-v-esp32-c6/time-sync/) - ESP32-C6 (RISC-V) example
+
+## API Reference
+
+The complete API documentation is available in the source code:
+
+- [`src/time_sync.rs`](../src/time_sync.rs) - Main synchronization manager
+- [`src/time_sync/sync_algorithm.rs`](../src/time_sync/sync_algorithm.rs) - Local Voting Protocol implementation
+- [`src/time_sync/esp_now_protocol.rs`](../src/time_sync/esp_now_protocol.rs) - ESP-NOW communication layer
+
+## Getting Help
+
+If you have questions or need assistance:
+
+1. Check the [troubleshooting section](./time-synchronization.md#troubleshooting) in the main documentation
+2. Review the [example applications](../examples/rust-examples/) for usage patterns
+3. Examine the [API documentation](../src/time_sync.rs) for detailed function descriptions
+4. Look at the [diagrams](./time-sync-diagrams.md) for visual understanding of the system
+
+## Contributing
+
+When contributing to the time synchronization system:
+
+1. Follow the existing code style and documentation patterns
+2. Add comprehensive documentation for new features
+3. Include examples and usage patterns
+4. Update diagrams when architectural changes are made
+5. Test on both ESP32 and ESP32-C6 platforms
+
+---
+
+*This documentation is part of the Martos RTOS project. For more information, visit the [main project repository](../README.md).*

docs/README.md

@@ -0,0 +1,14 @@
+[build]
+rustflags = [
+  "-C", "link-arg=-Tlinkall.x",
+  "-C", "force-frame-pointers",
+  "-C", "link-arg=-Trom_functions.x",
+]
+
+target = "riscv32imac-unknown-none-elf"
+
+[unstable]
+build-std = ["core", "alloc"]
+
+[target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))']
+runner = "espflash flash --monitor"

docs/time-sync-diagrams.md

@@ -0,0 +1,18 @@
+[package]
+name = "time-sync"
+version = "0.1.0"
+edition = "2021"
+
+[profile.release]
+debug = true
+
+[dependencies]
+martos = { path = "../../../../", features = ["network"] }
+esp-hal = "0.21.1"
+esp-backtrace = { version = "0.14.1", features = ["esp32c6", "panic-handler", "exception-handler", "println"] }
+esp-println = { version = "0.11.0", features = ["esp32c6"] }
+esp-wifi = { version = "0.10.1", features = ["wifi", "esp-now"] }
+static_cell = "2.0.0"
+
+[features]
+default = ["esp-hal/esp32c6", "esp-backtrace/esp32c6", "esp-println/esp32c6", "esp-wifi/esp32c6"]

docs/time-synchronization.md

@@ -0,0 +1,171 @@
+# ESP32-C6 Time Synchronization Example
+
+This example demonstrates the time synchronization system implemented in Martos RTOS using ESP-NOW communication protocol. The system implements a **Local Voting Protocol** that allows time to accelerate but prevents it from going backwards, ensuring monotonic time progression.
+
+## Features
+
+- **Time Synchronization**: Synchronizes time across multiple ESP32-C6 nodes using broadcast messages
+- **ESP-NOW Communication**: Uses ESP-NOW for low-latency peer-to-peer communication
+- **Local Voting Protocol**: Implements dynamic time acceleration algorithm with monotonic time guarantee
+- **Broadcast-based Sync**: Uses broadcast messages for efficient multi-node synchronization
+- **Quality Monitoring**: Tracks synchronization quality and peer performance
+- **Cross-platform**: Compatible with ESP32 (Xtensa) and ESP32-C6 (RISC-V) platforms
+
+## Architecture
+
+The example consists of several key components:
+
+1. **TimeSyncManager**: Main synchronization controller
+2. **ESP-NOW Protocol**: Communication layer for time data exchange
+3. **Sync Algorithm**: Core synchronization algorithm with dynamic correction
+4. **Timer Integration**: Integration with Martos timer system
+
+## Configuration
+
+The synchronization system is configured with the following parameters:
+
+- **Sync Interval**: 500ms (default broadcast frequency)
+- **Max Correction**: 1000μs (default maximum time correction per cycle)
+- **Acceleration Factor**: 0.1 (default acceleration rate)
+- **Deceleration Factor**: 0.05 (default deceleration rate)
+- **Max Peers**: 10 (maximum number of participants considered in consensus)
+
+## Usage
+
+### Building and Flashing
+
+```bash
+# Build the example
+cargo build --release --example time-sync
+
+# Flash to ESP32 (adjust port as needed)
+espflash flash --release --example time-sync /dev/ttyUSB0
+```
+
+### Running Multiple Nodes
+
+To test synchronization between multiple nodes:
+
+1. Flash the example to multiple ESP32-C6 devices (ESP32 and ESP32-C6)
+2. Ensure devices are within ESP-NOW communication range
+3. Monitor serial output to see synchronization progress
+4. Watch the `diff` value decrease as synchronization improves
+
+### Expected Output
+
+```
+ESP32-C6: Setup time synchronization!
+ESP32-C6: Time synchronization setup complete!
+ESP32-C6: Received timestamp: 30288013μs, corrected time: 936751μs, diff: 29351262μs
+ESP32-C6: Current offset: 100000μs
+ESP32-C6: Received timestamp: 32278010μs, corrected time: 3036532μs, diff: 29241478μs
+ESP32-C6: Current offset: 200000μs
+ESP32-C6: Received timestamp: 34268014μs, corrected time: 5136548μs, diff: 29131466μs
+ESP32-C6: Current offset: 200000μs
+ESP32-C6: Received timestamp: 36258013μs, corrected time: 7136562μs, diff: 29121451μs
+ESP32-C6: Current offset: 300000μs
+ESP32-C6: Received timestamp: 38248009μs, corrected time: 9236609μs, diff: 29011400μs
+ESP32-C6: Current offset: 400000μs
+ESP32-C6: Received timestamp: 40238008μs, corrected time: 11336665μs, diff: 28901343μs
+ESP32-C6: Current offset: 400000μs
+ESP32-C6: Received timestamp: 42228012μs, corrected time: 13336653μs, diff: 28891359μs
+ESP32-C6: Current offset: 500000μs
+ESP32-C6: Received timestamp: 44218013μs, corrected time: 15436722μs, diff: 28781291μs
+ESP32-C6: Current offset: 600000μs
+ESP32-C6: Received timestamp: 46208013μs, corrected time: 17538108μs, diff: 28669905μs
+```
+
+**Key observations:**
+- `Received timestamp`: Time from the remote node
+- `corrected time`: Local time adjusted by the synchronization offset
+- `diff`: Time difference between remote and local (should decrease over time)
+- `Current offset`: Virtual time offset applied to local time
+
+## Synchronization Algorithm
+
+The example implements a **Local Voting Protocol** algorithm with the following characteristics:
+
+1. **Broadcast Communication**: Nodes send time broadcasts every 2 seconds
+2. **Time Difference Calculation**: Compares received timestamps with local corrected time
+3. **Monotonic Time**: Time can only accelerate, never go backwards
+4. **Dynamic Correction**: Applies corrections based on weighted peer consensus
+5. **Convergence Detection**: Algorithm detects when nodes are synchronized
+
+### Algorithm Details
+
+- **Acceleration Factor**: 0.1 (default; tune for convergence)
+- **Deceleration Factor**: 0.05 (default; tune for stability)
+- **Max Correction**: 1000μs (default; increase carefully for faster initial sync)
+- **Convergence Threshold**: 50% of max correction threshold
+
+## Customization
+
+// Broadcast-only: peers are not managed explicitly
+
+### Adjusting Synchronization Parameters
+
+```rust
+let sync_config = SyncConfig {
+    sync_interval_ms: 1000,        // More frequent broadcasts
+    max_correction_threshold_us: 50000, // Smaller corrections
+    acceleration_factor: 0.9,      // More aggressive acceleration
+    deceleration_factor: 0.7,      // More aggressive deceleration
+    // ... other parameters
+};
+```
+
+### Monitoring Synchronization Quality
+
+```rust
+println!("Quality: {:.2}, Offset: {}μs", 
+    sync_manager.get_sync_quality(), 
+    sync_manager.get_time_offset_us());
+```
+
+## Troubleshooting
+
+### No Synchronization
+
+- Check ESP-NOW communication range
+- Ensure synchronization is enabled
+
+### Poor Synchronization Quality
+
+- Increase sync frequency
+- Adjust acceleration/deceleration factors
+- Check network conditions
+
+### Large Time Corrections
+
+- Reduce max correction threshold
+- Increase sync interval
+- Check for network delays
+
+## Performance Considerations
+
+- **CPU Usage**: Synchronization processing is lightweight
+- **Network Traffic**: Minimal ESP-NOW traffic (few bytes per sync cycle)
+- **Power Consumption**: ESP-NOW is power-efficient for IoT applications
+
+## Cross-Platform Compatibility
+
+This example is designed to work seamlessly between ESP32 (Xtensa) and ESP32-C6 (RISC-V) platforms:
+
+- **ESP-NOW Compatibility**: ESP-NOW works between different ESP chipset architectures
+- **Shared Protocol**: Both platforms use the same synchronization message format
+- **Automatic Detection**: The system automatically detects and adapts to the target platform
+- **Unified API**: Same Martos API works on both platforms
+
+### Testing Cross-Platform Synchronization
+
+1. Flash ESP32 example to an ESP32 device
+2. Flash ESP32-C6 example to an ESP32-C6 device
+3. Both devices will automatically discover and synchronize with each other
+4. Monitor both serial outputs to see synchronization progress
+
+## Future Enhancements
+
+- **Encryption**: Add ESP-NOW encryption for secure time synchronization
+- **Mesh Support**: Extend to multi-hop mesh networks
+- **GPS Integration**: Use GPS for absolute time reference
+- **Adaptive Algorithms**: Implement machine learning-based synchronization

examples/rust-examples/risc-v-esp32-c6/time-sync/.cargo/config.toml

@@ -0,0 +1,2 @@
+[toolchain]
+channel = "esp"