components

2026-02-01 23:37:00 +01:00
parent 304371c6b8
commit 80236fa840
11 changed files with 5501 additions and 0 deletions
--- a/design/components/time_utils/COMPONENT.md
+++ b/design/components/time_utils/COMPONENT.md
@@ -0,0 +1,513 @@
+# Time Utils Component Specification
+
+**Component ID:** C-TIME-001  
+**Component Name:** Time Utils  
+**Version:** 1.0  
+**Date:** 2025-02-01  
+**Location:** `application_layer/utils/time_utils/`
+
+## 1. Component Overview
+
+### 1.1 Purpose
+The Time Utils component provides centralized time management, timestamp generation, and time synchronization services for the ASF Sensor Hub. It ensures consistent time representation across all system components and provides accurate timestamps for sensor data, events, and system operations.
+
+### 1.2 Scope
+- System time management and synchronization
+- High-precision timestamp generation
+- Time zone handling and conversion
+- Uptime and duration tracking
+- Time-based scheduling utilities
+- Time format conversion and validation
+
+### 1.3 Responsibilities
+- Maintain accurate system time
+- Generate timestamps for sensor data and events
+- Provide time synchronization with external sources
+- Handle time zone conversions
+- Track system uptime and component operation durations
+- Provide time-based utility functions
+
+## 2. Component Architecture
+
+### 2.1 Static View
+
+```mermaid
+graph TB
+    subgraph "Time Utils"
+        TC[Time Controller]
+        TS[Time Synchronizer]
+        TG[Timestamp Generator]
+        TZ[Timezone Handler]
+        UT[Uptime Tracker]
+        TF[Time Formatter]
+    end
+    
+    subgraph "Time Sources"
+        RTC[RTC Hardware]
+        NTP[NTP Server]
+        GPS[GPS Module]
+        MH[Main Hub]
+    end
+    
+    subgraph "External Components"
+        SM[Sensor Manager]
+        ES[Event System]
+        DIAG[Diagnostics Manager]
+        LOGGER[Logger]
+    end
+    
+    TC --> TS
+    TC --> TG
+    TC --> TZ
+    TC --> UT
+    TC --> TF
+    
+    TS --> RTC
+    TS --> NTP
+    TS --> GPS
+    TS --> MH
+    
+    SM --> TG
+    ES --> TG
+    DIAG --> TG
+    LOGGER --> TG
+```
+
+### 2.2 Internal Components
+
+#### 2.2.1 Time Controller
+- Central coordination of time management operations
+- Time source selection and prioritization
+- Time accuracy monitoring and validation
+
+#### 2.2.2 Time Synchronizer
+- External time source synchronization
+- Time drift detection and correction
+- Synchronization scheduling and management
+
+#### 2.2.3 Timestamp Generator
+- High-precision timestamp generation
+- Monotonic time tracking
+- Timestamp format standardization
+
+#### 2.2.4 Timezone Handler
+- Time zone conversion and management
+- Daylight saving time handling
+- Local time calculation
+
+#### 2.2.5 Uptime Tracker
+- System uptime monitoring
+- Component operation duration tracking
+- Performance timing utilities
+
+#### 2.2.6 Time Formatter
+- Time format conversion utilities
+- String representation generation
+- Time parsing and validation
+
+## 3. Interfaces
+
+### 3.1 Provided Interfaces
+
+#### 3.1.1 ITimeUtils
+```cpp
+class ITimeUtils {
+public:
+    virtual ~ITimeUtils() = default;
+    
+    // Time Management
+    virtual Result<void> initialize() = 0;
+    virtual Result<void> shutdown() = 0;
+    virtual Result<void> synchronizeTime() = 0;
+    virtual TimeStatus getTimeStatus() const = 0;
+    
+    // Timestamp Generation
+    virtual uint64_t getCurrentTimestampMs() const = 0;
+    virtual uint64_t getCurrentTimestampUs() const = 0;
+    virtual std::chrono::system_clock::time_point getCurrentTimePoint() const = 0;
+    virtual uint64_t getMonotonicTimestampMs() const = 0;
+    
+    // Time Conversion
+    virtual std::string formatTimestamp(uint64_t timestamp_ms, 
+                                       TimeFormat format = TimeFormat::ISO8601) const = 0;
+    virtual Result<uint64_t> parseTimestamp(const std::string& time_str, 
+                                           TimeFormat format = TimeFormat::ISO8601) const = 0;
+    virtual Result<uint64_t> convertToUtc(uint64_t local_timestamp_ms) const = 0;
+    virtual Result<uint64_t> convertToLocal(uint64_t utc_timestamp_ms) const = 0;
+    
+    // Uptime and Duration
+    virtual uint64_t getSystemUptimeMs() const = 0;
+    virtual uint64_t getComponentUptimeMs(ComponentId component) const = 0;
+    virtual Result<void> startDurationTracking(const std::string& operation_id) = 0;
+    virtual Result<uint64_t> stopDurationTracking(const std::string& operation_id) = 0;
+    
+    // Time Zone Management
+    virtual Result<void> setTimeZone(const std::string& timezone) = 0;
+    virtual std::string getCurrentTimeZone() const = 0;
+    virtual bool isDaylightSavingTime() const = 0;
+    
+    // Time Validation
+    virtual bool isTimestampValid(uint64_t timestamp_ms) const = 0;
+    virtual bool isTimeAccurate() const = 0;
+    virtual std::chrono::milliseconds getTimeAccuracy() const = 0;
+};
+```
+
+#### 3.1.2 ITimestampProvider
+```cpp
+class ITimestampProvider {
+public:
+    virtual ~ITimestampProvider() = default;
+    virtual uint64_t getTimestamp() const = 0;
+    virtual uint64_t getMonotonicTimestamp() const = 0;
+    virtual bool isTimestampAccurate() const = 0;
+};
+```
+
+#### 3.1.3 ITimeFormatter
+```cpp
+class ITimeFormatter {
+public:
+    virtual ~ITimeFormatter() = default;
+    virtual std::string formatTime(uint64_t timestamp_ms, TimeFormat format) const = 0;
+    virtual std::string formatDuration(uint64_t duration_ms) const = 0;
+    virtual Result<uint64_t> parseTime(const std::string& time_str, TimeFormat format) const = 0;
+};
+```
+
+### 3.2 Required Interfaces
+
+#### 3.2.1 IRTCDriver
+- Real-time clock hardware access
+- RTC time reading and setting
+- RTC alarm and interrupt management
+
+#### 3.2.2 INetworkTime
+- NTP client functionality
+- Network time synchronization
+- Time server communication
+
+#### 3.2.3 IConfigurationManager
+- Time zone configuration
+- Synchronization settings
+- Time source preferences
+
+#### 3.2.4 ILogger
+- Time synchronization event logging
+- Time accuracy monitoring logs
+- Error condition reporting
+
+## 4. Dynamic View
+
+### 4.1 Time Synchronization Sequence
+
+```mermaid
+sequenceDiagram
+    participant TC as Time Controller
+    participant TS as Time Synchronizer
+    participant NTP as NTP Client
+    participant RTC as RTC Driver
+    participant LOGGER as Logger
+    
+    TC->>TS: synchronizeTime()
+    TS->>NTP: requestTimeSync()
+    NTP->>NTP: queryNTPServer()
+    NTP-->>TS: ntp_time_response
+    
+    alt NTP Sync Successful
+        TS->>TS: validateTimeResponse(ntp_time)
+        TS->>RTC: setSystemTime(ntp_time)
+        RTC-->>TS: time_set_success
+        TS->>TS: updateTimeAccuracy(HIGH)
+        TS->>LOGGER: logTimeSyncSuccess(ntp_time)
+        TS-->>TC: sync_successful
+    else NTP Sync Failed
+        TS->>RTC: getCurrentTime()
+        RTC-->>TS: rtc_time
+        TS->>TS: updateTimeAccuracy(LOW)
+        TS->>LOGGER: logTimeSyncFailure(reason)
+        TS-->>TC: sync_failed
+    end
+```
+
+### 4.2 Timestamp Generation Sequence
+
+```mermaid
+sequenceDiagram
+    participant SM as Sensor Manager
+    participant TG as Timestamp Generator
+    participant RTC as RTC Driver
+    participant TC as Time Controller
+    
+    SM->>TG: getCurrentTimestampMs()
+    TG->>RTC: getSystemTime()
+    RTC-->>TG: current_time
+    TG->>TC: getTimeAccuracy()
+    TC-->>TG: accuracy_status
+    TG->>TG: generateTimestamp(current_time, accuracy)
+    TG-->>SM: timestamp_ms
+    
+    Note over SM,TG: Timestamp includes accuracy metadata
+```
+
+### 4.3 Duration Tracking Sequence
+
+```mermaid
+sequenceDiagram
+    participant COMP as Component
+    participant UT as Uptime Tracker
+    participant TG as Timestamp Generator
+    
+    COMP->>UT: startDurationTracking("sensor_acquisition")
+    UT->>TG: getMonotonicTimestamp()
+    TG-->>UT: start_timestamp
+    UT->>UT: storeStartTime("sensor_acquisition", start_timestamp)
+    UT-->>COMP: tracking_started
+    
+    Note over COMP,UT: Operation executes
+    
+    COMP->>UT: stopDurationTracking("sensor_acquisition")
+    UT->>TG: getMonotonicTimestamp()
+    TG-->>UT: end_timestamp
+    UT->>UT: calculateDuration(start_timestamp, end_timestamp)
+    UT-->>COMP: operation_duration_ms
+```
+
+## 5. Time Management
+
+### 5.1 Time Sources Priority
+```cpp
+enum class TimeSource {
+    NTP_SERVER = 0,         // Highest priority - Network Time Protocol
+    GPS_MODULE = 1,         // High priority - GPS time
+    MAIN_HUB = 2,           // Medium priority - Main Hub time
+    RTC_HARDWARE = 3,       // Low priority - Hardware RTC
+    SYSTEM_CLOCK = 4        // Lowest priority - System clock
+};
+```
+
+### 5.2 Time Accuracy Levels
+```cpp
+enum class TimeAccuracy {
+    HIGH,                   // ±1 second accuracy (NTP/GPS synchronized)
+    MEDIUM,                 // ±10 seconds accuracy (Recent sync)
+    LOW,                    // ±60 seconds accuracy (RTC only)
+    UNKNOWN                 // Accuracy unknown (no sync)
+};
+```
+
+### 5.3 Time Synchronization Strategy
+- **Primary Sync**: NTP server synchronization every 24 hours
+- **Backup Sync**: Main Hub time synchronization every 6 hours
+- **Drift Monitoring**: Continuous monitoring of time drift
+- **Accuracy Tracking**: Real-time accuracy assessment
+- **Fallback**: RTC hardware as last resort time source
+
+## 6. Timestamp Generation
+
+### 6.1 Timestamp Formats
+```cpp
+enum class TimeFormat {
+    UNIX_TIMESTAMP_MS,      // Milliseconds since Unix epoch
+    UNIX_TIMESTAMP_US,      // Microseconds since Unix epoch
+    ISO8601,                // ISO 8601 format (YYYY-MM-DDTHH:MM:SS.sssZ)
+    RFC3339,                // RFC 3339 format
+    HUMAN_READABLE,         // Human-readable format
+    COMPACT                 // Compact format for storage
+};
+```
+
+### 6.2 Timestamp Structure
+```cpp
+struct Timestamp {
+    uint64_t timestamp_ms;          // Milliseconds since epoch
+    TimeAccuracy accuracy;          // Timestamp accuracy level
+    TimeSource source;              // Time source used
+    bool is_synchronized;           // Whether time is synchronized
+    std::chrono::milliseconds drift; // Estimated drift from accurate time
+};
+```
+
+### 6.3 Monotonic Time Tracking
+- **Boot Time Reference**: Monotonic time since system boot
+- **Overflow Handling**: 64-bit counters to prevent overflow
+- **High Resolution**: Microsecond resolution for precise timing
+- **Drift Compensation**: Compensation for clock drift
+
+## 7. Time Zone Management
+
+### 7.1 Time Zone Support
+```cpp
+class TimeZoneManager {
+public:
+    Result<void> setTimeZone(const std::string& timezone);
+    std::string getCurrentTimeZone() const;
+    bool isDaylightSavingTime(uint64_t timestamp_ms) const;
+    uint64_t convertToUtc(uint64_t local_timestamp_ms) const;
+    uint64_t convertToLocal(uint64_t utc_timestamp_ms) const;
+    
+private:
+    std::string current_timezone_;
+    int32_t utc_offset_minutes_;
+    bool dst_active_;
+};
+```
+
+### 7.2 Supported Time Zones
+- **UTC**: Coordinated Universal Time (default)
+- **Local**: Configurable local time zone
+- **DST Support**: Automatic daylight saving time handling
+- **Offset Calculation**: UTC offset calculation and conversion
+
+## 8. Performance Monitoring
+
+### 8.1 Uptime Tracking
+```cpp
+struct UptimeInfo {
+    uint64_t system_uptime_ms;      // Total system uptime
+    uint64_t component_uptime_ms;   // Component-specific uptime
+    uint32_t boot_count;            // Number of system boots
+    uint64_t last_boot_time_ms;     // Timestamp of last boot
+    std::map<std::string, uint64_t> operation_durations; // Operation timing
+};
+```
+
+### 8.2 Duration Tracking
+- **Operation Timing**: Track duration of specific operations
+- **Performance Metrics**: Calculate average, min, max durations
+- **Bottleneck Identification**: Identify slow operations
+- **Trend Analysis**: Monitor performance trends over time
+
+## 9. Configuration
+
+### 9.1 Time Utils Configuration
+```cpp
+struct TimeUtilsConfig {
+    // Synchronization Configuration
+    std::string ntp_server_url;
+    std::chrono::hours sync_interval;
+    std::chrono::seconds sync_timeout;
+    bool automatic_sync_enabled;
+    
+    // Time Zone Configuration
+    std::string default_timezone;
+    bool dst_enabled;
+    int32_t utc_offset_minutes;
+    
+    // Accuracy Configuration
+    std::chrono::milliseconds max_acceptable_drift;
+    TimeAccuracy minimum_required_accuracy;
+    bool strict_accuracy_enforcement;
+    
+    // Logging Configuration
+    bool log_sync_events;
+    bool log_accuracy_changes;
+    bool log_time_jumps;
+    
+    // Performance Configuration
+    bool uptime_tracking_enabled;
+    bool duration_tracking_enabled;
+    uint32_t max_tracked_operations;
+};
+```
+
+## 10. Error Handling
+
+### 10.1 Time-Related Errors
+```cpp
+enum class TimeError {
+    SYNC_FAILED,            // Time synchronization failed
+    INVALID_TIMESTAMP,      // Invalid timestamp value
+    TIMEZONE_INVALID,       // Invalid time zone specification
+    ACCURACY_INSUFFICIENT,  // Time accuracy below requirements
+    DRIFT_EXCESSIVE,        // Time drift exceeds limits
+    SOURCE_UNAVAILABLE,     // Time source not available
+    FORMAT_INVALID          // Invalid time format
+};
+```
+
+### 10.2 Error Recovery Strategies
+- **Sync Retry**: Retry synchronization with exponential backoff
+- **Source Fallback**: Fall back to alternative time sources
+- **Accuracy Degradation**: Continue with reduced accuracy
+- **Error Reporting**: Report time-related issues to diagnostics
+
+## 11. Performance Characteristics
+
+### 11.1 Timing Requirements
+- **Timestamp Generation**: < 1ms for timestamp generation
+- **Time Synchronization**: < 10 seconds for NTP synchronization
+- **Format Conversion**: < 5ms for time format conversion
+- **Duration Calculation**: < 1ms for duration tracking operations
+
+### 11.2 Resource Usage
+- **Memory**: < 4KB for time management data structures
+- **Storage**: Minimal persistent storage for time zone data
+- **CPU**: < 0.5% average utilization for time operations
+- **Network**: Periodic NTP synchronization traffic
+
+## 12. Security Considerations
+
+### 12.1 Time Security
+- **NTP Security**: Secure NTP communication to prevent time attacks
+- **Time Validation**: Validate time sources and detect time jumps
+- **Accuracy Verification**: Verify time accuracy from multiple sources
+
+### 12.2 Timestamp Security
+- **Monotonic Guarantees**: Ensure monotonic timestamp progression
+- **Tamper Detection**: Detect attempts to manipulate system time
+- **Audit Trail**: Maintain audit trail of time changes
+
+## 13. Testing Strategy
+
+### 13.1 Unit Tests
+- Timestamp generation accuracy
+- Time format conversion correctness
+- Duration tracking precision
+- Time zone conversion validation
+
+### 13.2 Integration Tests
+- NTP synchronization functionality
+- RTC integration and fallback
+- Component timestamp consistency
+- Time accuracy maintenance
+
+### 13.3 System Tests
+- Long-term time accuracy validation
+- Time synchronization under network failures
+- Performance impact of time operations
+- Time zone and DST handling
+
+## 14. Dependencies
+
+### 14.1 Internal Dependencies
+- Configuration Manager for time settings
+- Logger for time event logging
+- Network stack for NTP synchronization
+- Hardware drivers for RTC access
+
+### 14.2 External Dependencies
+- ESP-IDF time and RTC APIs
+- NTP client library
+- Time zone database
+- Hardware RTC support
+
+## 15. Constraints and Assumptions
+
+### 15.1 Constraints
+- Time accuracy limited by available time sources
+- Network dependency for high-accuracy time synchronization
+- RTC hardware accuracy limitations
+- Memory constraints for time zone data
+
+### 15.2 Assumptions
+- Network connectivity available for NTP synchronization
+- RTC hardware properly configured and functional
+- System clock reasonably stable between synchronizations
+- Time zone configuration provided during system setup
+
+---
+
+**Document Status:** Final for Implementation  
+**Dependencies:** RTC Driver, Network Stack, Configuration Manager, Logger  
+**Next Review:** After component implementation and accuracy validation