software and system v1
This commit is contained in:
280
1 software design/components/time_sync_service/COMPONENT.md
Normal file
280
1 software design/components/time_sync_service/COMPONENT.md
Normal file
@@ -0,0 +1,280 @@
|
||||
# Time Synchronization Service Component
|
||||
## ASF Sensor Hub (Sub-Hub) Embedded System
|
||||
|
||||
**Component ID:** C-TIME-SYNC-001
|
||||
**Version:** 1.0
|
||||
**Date:** 2025-02-01
|
||||
**Location:** `application_layer/services/time_sync_service/`
|
||||
**Platform:** ESP32-S3, ESP-IDF v5.4
|
||||
|
||||
---
|
||||
|
||||
## 1. Component Overview
|
||||
|
||||
The Time Synchronization Service provides centralized time management, synchronization with external time sources (Main Hub, NTP), and timestamp generation for all system components. This component addresses GAP-SYS-REQ-001 (Missing Time Synchronization Requirements).
|
||||
|
||||
**Primary Purpose:** Ensure accurate system time and synchronized timestamps across all components.
|
||||
|
||||
---
|
||||
|
||||
## 2. Responsibilities
|
||||
|
||||
### 2.1 In-Scope
|
||||
|
||||
- System time management
|
||||
- Time synchronization with Main Hub
|
||||
- Time synchronization with NTP server (optional)
|
||||
- Time zone handling
|
||||
- Timestamp generation
|
||||
- Time drift detection and correction
|
||||
- Time accuracy monitoring
|
||||
|
||||
### 2.2 Out-of-Scope
|
||||
|
||||
- RTC hardware management (handled by ESP-IDF)
|
||||
- Time zone database (uses configured time zone)
|
||||
- Daylight saving time (uses fixed offset)
|
||||
|
||||
---
|
||||
|
||||
## 3. Provided Interfaces
|
||||
|
||||
### 3.1 Time Query Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Get current system time (Unix timestamp)
|
||||
* @param timestamp Output timestamp (seconds since epoch)
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_get_time(uint64_t* timestamp);
|
||||
|
||||
/**
|
||||
* @brief Get current system time with microseconds
|
||||
* @param timestamp_us Output timestamp (microseconds since epoch)
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_get_time_us(uint64_t* timestamp_us);
|
||||
|
||||
/**
|
||||
* @brief Get time string (formatted)
|
||||
* @param buffer Output buffer
|
||||
* @param buffer_size Buffer size
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_get_time_string(char* buffer, size_t buffer_size);
|
||||
```
|
||||
|
||||
### 3.2 Time Synchronization Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Synchronize time with Main Hub
|
||||
* @param timestamp Timestamp from Main Hub
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_sync_with_main_hub(uint64_t timestamp);
|
||||
|
||||
/**
|
||||
* @brief Synchronize time with NTP server
|
||||
* @param ntp_server NTP server address
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_sync_with_ntp(const char* ntp_server);
|
||||
|
||||
/**
|
||||
* @brief Get time synchronization status
|
||||
* @param status Output status structure
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_get_status(time_sync_status_t* status);
|
||||
```
|
||||
|
||||
### 3.3 Configuration Interface
|
||||
|
||||
```c
|
||||
/**
|
||||
* @brief Configure time zone
|
||||
* @param timezone_offset Time zone offset in seconds
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_set_timezone(int32_t timezone_offset);
|
||||
|
||||
/**
|
||||
* @brief Set time synchronization source priority
|
||||
* @param priority_list Priority list (Main Hub, NTP, RTC, Internal)
|
||||
* @return true on success
|
||||
*/
|
||||
bool time_sync_set_source_priority(const time_source_priority_t* priority_list);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Time Source Priority
|
||||
|
||||
### 4.1 Priority Order
|
||||
|
||||
1. **Main Hub** (highest priority) - Real-time synchronization
|
||||
2. **NTP Server** (secondary) - Network time protocol
|
||||
3. **RTC** (tertiary) - Real-time clock (if available)
|
||||
4. **Internal Clock** (lowest) - System uptime-based
|
||||
|
||||
### 4.2 Synchronization Strategy
|
||||
|
||||
- Attempt Main Hub sync every 60 seconds
|
||||
- Fallback to NTP if Main Hub unavailable
|
||||
- Use RTC if network unavailable
|
||||
- Use internal clock as last resort
|
||||
|
||||
---
|
||||
|
||||
## 5. Time Accuracy Requirements
|
||||
|
||||
### 5.1 Accuracy Targets
|
||||
|
||||
- **Main Hub Sync:** ±1 second
|
||||
- **NTP Sync:** ±1 second
|
||||
- **RTC Drift:** ±5 seconds per day
|
||||
- **Internal Clock:** ±10 seconds per hour
|
||||
|
||||
### 5.2 Drift Detection
|
||||
|
||||
- Monitor time drift continuously
|
||||
- Detect drift > 2 seconds
|
||||
- Trigger re-synchronization on drift detection
|
||||
- Report drift events to Diagnostics Manager
|
||||
|
||||
---
|
||||
|
||||
## 6. Internal State Machine
|
||||
|
||||
```
|
||||
[UNINITIALIZED]
|
||||
↓ time_sync_init()
|
||||
[INITIALIZED]
|
||||
↓ First sync attempt
|
||||
[SYNCING]
|
||||
↓ Sync success
|
||||
[SYNCHRONIZED]
|
||||
↓ Drift detected or timeout
|
||||
[DRIFT_DETECTED]
|
||||
↓ Re-sync
|
||||
[SYNCING]
|
||||
↓ Sync failure
|
||||
[SYNC_FAILED]
|
||||
↓ Retry
|
||||
[SYNCING]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. ESP-IDF Integration
|
||||
|
||||
### 7.1 ESP-IDF Services Used
|
||||
|
||||
- `esp_sntp.h` - SNTP client for NTP synchronization
|
||||
- `time.h` - Standard time functions
|
||||
- `sys/time.h` - Time structures
|
||||
|
||||
### 7.2 RTC Support
|
||||
|
||||
- Uses ESP32-S3 RTC if available
|
||||
- RTC battery backup (optional hardware)
|
||||
- RTC calibration support
|
||||
|
||||
---
|
||||
|
||||
## 8. Error Handling
|
||||
|
||||
### 8.1 Error Detection
|
||||
|
||||
- Synchronization failures
|
||||
- Time drift exceeding limits
|
||||
- Invalid timestamps
|
||||
- Network timeouts
|
||||
|
||||
### 8.2 Error Recovery
|
||||
|
||||
- Automatic retry with exponential backoff
|
||||
- Fallback to lower-priority time source
|
||||
- Error reporting to Diagnostics Manager
|
||||
- State transition handling
|
||||
|
||||
### 8.3 Diagnostic Events
|
||||
|
||||
- `DIAG-TIME-SYNC-0001`: Time synchronization failure
|
||||
- `DIAG-TIME-SYNC-0002`: Time drift detected
|
||||
- `DIAG-TIME-SYNC-0003`: Invalid timestamp received
|
||||
- `DIAG-TIME-SYNC-0004`: Time source unavailable
|
||||
|
||||
---
|
||||
|
||||
## 9. Configuration
|
||||
|
||||
### 9.1 Machine Constants
|
||||
|
||||
- Time zone offset
|
||||
- NTP server address
|
||||
- Synchronization interval
|
||||
- Drift threshold
|
||||
|
||||
### 9.2 Runtime Configuration
|
||||
|
||||
- Time source priority
|
||||
- Synchronization frequency
|
||||
- Drift detection sensitivity
|
||||
|
||||
---
|
||||
|
||||
## 10. Dependencies
|
||||
|
||||
### 10.1 OSAL Dependencies
|
||||
|
||||
- **OSAL-TASK:** Background synchronization task
|
||||
|
||||
### 10.2 Application Dependencies
|
||||
|
||||
- **Communication Manager:** Main Hub time sync
|
||||
- **Network Stack:** NTP synchronization
|
||||
- **Logger:** Time event logging
|
||||
- **Diagnostics Manager:** Error reporting
|
||||
|
||||
---
|
||||
|
||||
## 11. Traceability
|
||||
|
||||
### 11.1 System Requirements (Gap Resolution)
|
||||
|
||||
- **SR-TIME-001:** System shall synchronize time with Main Hub or NTP server (GAP-SYS-REQ-001)
|
||||
- **SR-TIME-002:** System shall maintain time accuracy within ±1 second (GAP-SYS-REQ-001)
|
||||
- **SR-TIME-003:** System shall handle time zone configuration (GAP-SYS-REQ-001)
|
||||
- **SR-TIME-004:** System shall detect and report time synchronization failures (GAP-SYS-REQ-001)
|
||||
|
||||
### 11.2 Software Requirements
|
||||
|
||||
- **SWR-DAQ-008:** Timestamp generation for sensor data
|
||||
- **SWR-DIAG-004:** Timestamp diagnostic events
|
||||
|
||||
---
|
||||
|
||||
## 12. Implementation Notes
|
||||
|
||||
### 12.1 ESP-IDF v5.4 Specifics
|
||||
|
||||
- Uses SNTP client for NTP synchronization
|
||||
- Supports multiple NTP servers
|
||||
- Automatic daylight saving time (if configured)
|
||||
- RTC support via ESP32-S3 RTC peripheral
|
||||
|
||||
### 12.2 Performance Considerations
|
||||
|
||||
- Synchronization operations are non-blocking
|
||||
- Background task for periodic sync
|
||||
- Minimal CPU overhead
|
||||
- Memory-efficient timestamp storage
|
||||
|
||||
---
|
||||
|
||||
**Document Status:** Complete
|
||||
**Next Review:** Before implementation
|
||||
**Approval Required:** Software Architect
|
||||
Reference in New Issue
Block a user