Update and test light_ll connection_management.rs

Author: retsimx

rust/src/common.rs

@@ -78,6 +78,7 @@ pub fn save_pair_info(adr: u32, p: &[u8]) {
     interval_min + 20 ms <= interval_max <= 2second
     timeout <= 6second
 */
+#[cfg_attr(test, mry::mry)]
 pub fn update_ble_parameter_cb() {
     if !CONN_UPDATE_SUCCESSED.get() {
         setup_ble_parameter_start(

rust/src/sdk/ble_app/ble_ll_pair.rs

@@ -388,6 +388,7 @@ pub fn pair_save_key()
 /// This function resets the pairing state and prepares initialization vectors
 /// for a new BLE connection. It uses the device's MAC address as part of the
 /// initialization vectors for encryption.
+#[cfg_attr(test, mry::mry)]
 pub fn pair_init()
 {
     // Reset pairing state to initial value

rust/src/sdk/ble_app/light_ll/connection_management.rs

@@ -1,17 +1,75 @@
+//! # Light Link Layer (light_ll) Module
+//!
+//! This module implements the core link layer functionality for a BLE mesh lighting system 
+//! on the TLSR8266 chip. The light_ll module serves as the bridge between the low-level 
+//! BLE radio hardware and the higher-level mesh networking protocol stack.
+//!
+//! ## Architecture Overview
+//!
+//! The module is organized into six main subsystems that work together to provide a complete
+//! mesh networking solution:
+//!
+//! 1. **Connection Management**: Handles BLE peripheral connections, timing synchronization,
+//!    and parameter updates
+//! 2. **Mesh Management**: Manages mesh network topology, node discovery, and status propagation
+//! 3. **Packet Processing**: Parses and routes incoming packets, handles retransmission and acknowledgments
+//! 4. **Status Management**: Coordinates device status reporting and bridging between BLE and mesh
+//! 5. **OTA Management**: Provides over-the-air firmware update capabilities
+//! 6. **Pairing Management**: Handles device authentication and security key management
+//!
+//! ## Key Design Principles
+//!
+//! ### Multi-Protocol Support
+//! The system operates simultaneously as:
+//! - A BLE peripheral (for smartphone/gateway connections)
+//! - A mesh node (for device-to-device communication)
+//! - A bridge between these two networks
+//!
+//! ### Timing-Critical Operation
+//! All mesh communication is precisely timed to ensure:
+//! - Collision avoidance in the shared radio medium
+//! - Reliable message delivery with minimal latency
+//! - Power-efficient operation through synchronized sleep cycles
+//!
+//! ### Scalable Mesh Architecture
+//! The mesh protocol supports:
+//! - Up to 254 nodes per network (addresses 1-254, with 0 reserved for broadcast)
+//! - Automatic relay and routing of messages
+//! - Self-healing network topology
+//! - Group addressing for synchronized control
+
 /// Mesh network management functionality
+///
+/// Handles mesh node discovery, status tracking, and network topology maintenance.
+/// Implements algorithms for reliable status propagation and automatic node timeout detection.
 pub mod mesh_management;
 
-/// BLE connection management functionality
+/// BLE connection management functionality  
+///
+/// Manages BLE peripheral connections, including connection parameter negotiation,
+/// timing synchronization, and adaptive parameter updates for optimal performance.
 pub mod connection_management;
 
 /// Packet processing and parsing functionality
+///
+/// Implements the core packet routing logic, including mesh relay algorithms,
+/// duplicate detection, acknowledgment handling, and protocol parsing.
 pub mod packet_processing;
 
 /// Over-The-Air (OTA) update management
+///
+/// Provides secure firmware update capabilities over the mesh network,
+/// with flash memory management and verification algorithms.
 pub mod ota_management;
 
 /// Device status and reporting management
+///
+/// Coordinates status reporting between BLE and mesh networks, implementing
+/// bridge algorithms and response buffering for reliable data transfer.
 pub mod status_management;
 
 /// Pairing and security management
+///
+/// Handles device authentication, key management, and secure pairing protocols
+/// for mesh network access control.
 pub mod pairing_management;

rust/src/sdk/ble_app/light_ll/mesh_management.rs

@@ -1,21 +1,141 @@
+//! # Over-The-Air (OTA) Update Management
+//!
+//! This module implements secure firmware update capabilities for the TLSR8266 mesh lighting
+//! system. It provides the core functionality for receiving, validating, and storing firmware
+//! updates transmitted over the mesh network.
+//!
+//! ## OTA Update Architecture
+//!
+//! The OTA system is designed with the following principles:
+//!
+//! ### Security and Reliability
+//! - **Write-Verify Cycle**: Every flash write operation is immediately verified by reading back
+//!   the data to ensure integrity
+//! - **Atomic Operations**: Flash writes are performed in discrete pages to prevent partial updates
+//! - **Error Recovery**: Failed writes are detected immediately and can trigger retransmission
+//!
+//! ### Flash Memory Management
+//! - **Dedicated Flash Region**: Firmware updates are written to a separate flash area to avoid
+//!   corrupting the running firmware
+//! - **Sequential Writing**: Firmware data is written sequentially to prevent fragmentation
+//! - **Address Tracking**: Current write position is maintained to resume interrupted updates
+//!
+//! ### Integration with Mesh Network
+//! - **Packet-Based Transfer**: Firmware is transmitted in small packets suitable for mesh networking
+//! - **Progress Tracking**: Update progress is tracked and can be reported across the network
+//! - **Error Propagation**: Write failures are communicated back to the update initiator
+//!
+//! ## Flash Memory Layout
+//!
+//! ```
+//! Flash Memory:
+//! ┌─────────────────┬─────────────────┬─────────────────┐
+//! │ Running FW      │ New FW Area     │ Config/Data     │
+//! │ (Active)        │ (OTA Target)    │ (Persistent)    │
+//! └─────────────────┴─────────────────┴─────────────────┘
+//!                   ↑
+//!           FLASH_ADR_LIGHT_NEW_FW
+//! ```
+//!
+//! ## Update State Machine
+//!
+//! The OTA process follows this state progression:
+//! 1. **Idle**: No update in progress
+//! 2. **Receiving**: Accepting firmware data packets
+//! 3. **Continue**: Previous packet written successfully, ready for next
+//! 4. **Error**: Write/verify failure detected, update aborted
+//! 5. **Complete**: All firmware data received and verified
+
 use crate::config::FLASH_ADR_LIGHT_NEW_FW;
 use crate::sdk::drivers::flash::{flash_read_page, flash_write_page};
 use crate::sdk::light::OtaState;
 use crate::state::{OTA_UPDATE_CURRENT_FLASH_ADDRESS, SimplifyLS};
 
-/// Saves OTA data to flash memory
+/// Saves OTA firmware data to flash memory with verification.
+///
+/// This function implements the core OTA flash write algorithm with built-in verification
+/// to ensure data integrity. It performs atomic write operations followed by immediate
+/// read-back verification to detect any flash memory errors.
+///
+/// # Flash Write Algorithm
+///
+/// The function follows a strict write-verify-advance sequence:
+///
+/// 1. **Address Calculation**: Computes the target flash address by adding the current
+///    write offset to the base OTA flash region address
+///
+/// 2. **Flash Write Operation**: Writes the incoming data to flash memory using the
+///    hardware flash driver
+///
+/// 3. **Verification Read**: Immediately reads back the written data from flash to
+///    verify the write operation succeeded
+///
+/// 4. **Data Comparison**: Performs byte-by-byte comparison between the original data
+///    and the read-back data to detect any corruption
+///
+/// 5. **State Update**: On successful verification, advances the write pointer for
+///    the next packet; on failure, returns error state
+///
+/// # Error Detection
+///
+/// The verification process detects several types of flash errors:
+/// - **Write Failures**: Flash cells that fail to program correctly
+/// - **Read Disturbance**: Previously written data corrupted by nearby writes
+/// - **Wear-Out**: Flash cells that have exceeded their write/erase cycles
+/// - **Power Glitches**: Incomplete writes due to power supply instability
+///
+/// # Flash Memory Safety
+///
+/// The function ensures safe flash operations by:
+/// - Using only the designated OTA flash region (prevents overwriting active firmware)
+/// - Performing sequential writes (prevents address conflicts)
+/// - Validating write operations before advancing (prevents partial corruption)
+/// - Maintaining atomic write semantics (each call either fully succeeds or fails)
+///
+/// # Performance Considerations
+///
+/// - **Flash Write Time**: Each write operation may take several milliseconds
+/// - **Verification Overhead**: Read-back verification doubles the flash access time
+/// - **Sequential Access**: Sequential writes are optimized by flash hardware
+/// - **Page Alignment**: Performance is optimal when data aligns with flash page boundaries
+///
+/// # Parameters
+/// * `data` - Firmware data packet to write to flash (1-16 bytes typical)
+///
+/// # Returns
+/// * `OtaState::Continue` - Data written and verified successfully, ready for next packet
+/// * `OtaState::Error` - Write or verification failed, update should be aborted
+///
+/// # Side Effects
+/// * Modifies flash memory content in the OTA region
+/// * Updates `OTA_UPDATE_CURRENT_FLASH_ADDRESS` on successful writes
+/// * May trigger flash wear leveling operations (hardware-dependent)
+///
+/// # Flash Endurance
+/// Flash memory has limited write/erase cycles (typically 10,000-100,000 cycles).
+/// This function contributes to flash wear and should only be used for legitimate
+/// firmware updates to preserve flash lifetime.
 pub fn rf_ota_save_data(data: &[u8]) -> OtaState
 {
+    // Calculate target flash address: base OTA region + current write offset
     let addr = OTA_UPDATE_CURRENT_FLASH_ADDRESS.get() + FLASH_ADR_LIGHT_NEW_FW;
+    
+    // Write the firmware data packet to flash memory
     flash_write_page(addr, data.len() as u32, data.as_ptr());
 
+    // Allocate temporary buffer for verification read (16 bytes max packet size)
     let mut tmp = [0u8; 0x10];
+    
+    // Read back the written data for verification
     flash_read_page(addr, data.len() as u32, tmp.as_mut_ptr());
 
+    // Verify data integrity by comparing original data with read-back data
     if data == &tmp[..data.len()] {
+        // Write verification successful - advance write pointer for next packet
         OTA_UPDATE_CURRENT_FLASH_ADDRESS.set(OTA_UPDATE_CURRENT_FLASH_ADDRESS.get() + data.len() as u32);
         return OtaState::Continue;
     } else {
+        // Write verification failed - return error to abort update
         return OtaState::Error;
     }
 }