257 lines
7.8 KiB
Markdown
257 lines
7.8 KiB
Markdown
# Precision Timing Tool - Project Structure
|
|
|
|
## Directory Layout
|
|
```
|
|
precision-timing-tool/
|
|
├── CMakeLists.txt # Main build configuration
|
|
├── pico_sdk_import.cmake # Pico SDK integration
|
|
├── FreeRTOSConfig.h # FreeRTOS configuration
|
|
├── README.md # Project documentation
|
|
├── DEVELOPMENT_INSTRUCTIONS.md # Development guide
|
|
├── PROJECT_STRUCTURE.md # This file
|
|
│
|
|
├── src/ # Source code
|
|
│ ├── main.c # Application entry point
|
|
│ ├── config.h # System configuration
|
|
│ │
|
|
│ ├── freertos/ # FreeRTOS specific
|
|
│ │ ├── tasks.c # Task definitions
|
|
│ │ ├── tasks.h
|
|
│ │ └── hooks.c # FreeRTOS hooks
|
|
│ │
|
|
│ ├── drivers/ # Hardware drivers
|
|
│ │ ├── ch9120/ # Ethernet controller
|
|
│ │ │ ├── ch9120.c
|
|
│ │ │ ├── ch9120.h
|
|
│ │ │ └── ch9120_config.h
|
|
│ │ ├── gps/ # GPS receiver
|
|
│ │ │ ├── gps.c
|
|
│ │ │ ├── gps.h
|
|
│ │ │ └── nmea_parser.c
|
|
│ │ └── hardware/ # RP2040 hardware
|
|
│ │ ├── pps.c # PPS interrupt handler
|
|
│ │ ├── pps.h
|
|
│ │ ├── rtc.c # Real-time clock
|
|
│ │ └── rtc.h
|
|
│ │
|
|
│ ├── network/ # Network protocols
|
|
│ │ ├── ntp/ # NTP implementation
|
|
│ │ │ ├── ntp_client.c
|
|
│ │ │ ├── ntp_server.c
|
|
│ │ │ ├── ntp_common.h
|
|
│ │ │ └── ntp_packet.h
|
|
│ │ ├── ptp/ # PTP implementation
|
|
│ │ │ ├── ptp_clock.c
|
|
│ │ │ ├── ptp_messages.c
|
|
│ │ │ ├── ptp_common.h
|
|
│ │ │ └── ptp_types.h
|
|
│ │ └── network_stack.c # Common network functions
|
|
│ │
|
|
│ ├── timing/ # Timing core
|
|
│ │ ├── clock_discipline.c # Clock sync algorithms
|
|
│ │ ├── clock_discipline.h
|
|
│ │ ├── time_sources.c # Time source management
|
|
│ │ ├── time_sources.h
|
|
│ │ ├── timebase.c # System timebase
|
|
│ │ └── timebase.h
|
|
│ │
|
|
│ ├── protocols/ # Time code protocols
|
|
│ │ ├── irig/ # IRIG time codes
|
|
│ │ │ ├── irig_decoder.c
|
|
│ │ │ ├── irig_encoder.c
|
|
│ │ │ └── irig_common.h
|
|
│ │ └── timecode.h # Common time code interface
|
|
│ │
|
|
│ ├── utils/ # Utility functions
|
|
│ │ ├── circular_buffer.c
|
|
│ │ ├── circular_buffer.h
|
|
│ │ ├── statistics.c # Timing statistics
|
|
│ │ ├── statistics.h
|
|
│ │ └── debug.h # Debug macros
|
|
│ │
|
|
│ └── web/ # Web interface
|
|
│ ├── web_server.c
|
|
│ ├── web_server.h
|
|
│ ├── api_handlers.c # REST API
|
|
│ └── html_content.h # Embedded HTML
|
|
│
|
|
├── lib/ # External libraries
|
|
│ ├── FreeRTOS-Kernel/ # FreeRTOS submodule
|
|
│ └── pico-sdk/ # Pico SDK submodule
|
|
│
|
|
├── test/ # Unit tests
|
|
│ ├── test_ntp.c
|
|
│ ├── test_ptp.c
|
|
│ ├── test_clock.c
|
|
│ └── CMakeLists.txt
|
|
│
|
|
├── tools/ # Development tools
|
|
│ ├── deploy.sh # Deployment script
|
|
│ ├── monitor.py # Serial monitor
|
|
│ └── time_client.py # Test client
|
|
│
|
|
├── docs/ # Documentation (already created)
|
|
│ ├── hardware/
|
|
│ ├── software/
|
|
│ ├── examples/
|
|
│ ├── freertos/
|
|
│ └── timing/
|
|
│
|
|
└── build/ # Build output (generated)
|
|
└── timing_tool.uf2 # Firmware binary
|
|
```
|
|
|
|
## Module Descriptions
|
|
|
|
### Core Modules
|
|
|
|
#### Main Application (`src/main.c`)
|
|
- System initialization
|
|
- FreeRTOS scheduler start
|
|
- Hardware configuration
|
|
- Task creation
|
|
|
|
#### FreeRTOS Tasks (`src/freertos/tasks.c`)
|
|
```c
|
|
// Task priorities (higher number = higher priority)
|
|
#define TASK_PRIORITY_TIMING (configMAX_PRIORITIES - 1) // Critical
|
|
#define TASK_PRIORITY_PPS (configMAX_PRIORITIES - 2) // High
|
|
#define TASK_PRIORITY_NETWORK (configMAX_PRIORITIES - 3) // High
|
|
#define TASK_PRIORITY_GPS (configMAX_PRIORITIES - 4) // Normal
|
|
#define TASK_PRIORITY_OUTPUT (configMAX_PRIORITIES - 5) // Normal
|
|
#define TASK_PRIORITY_WEB (configMAX_PRIORITIES - 6) // Low
|
|
#define TASK_PRIORITY_STATS (configMAX_PRIORITIES - 7) // Low
|
|
```
|
|
|
|
### Hardware Drivers
|
|
|
|
#### CH9120 Ethernet (`src/drivers/ch9120/`)
|
|
- UART communication with CH9120
|
|
- Network configuration
|
|
- Packet transmission/reception
|
|
- TCP/UDP socket management
|
|
|
|
#### GPS Driver (`src/drivers/gps/`)
|
|
- NMEA sentence parsing
|
|
- Time extraction
|
|
- Position data (for fixed installations)
|
|
- PPS synchronization
|
|
|
|
### Network Protocols
|
|
|
|
#### NTP Implementation (`src/network/ntp/`)
|
|
- Client: Time synchronization
|
|
- Server: Time distribution
|
|
- Stratum management
|
|
- Authentication support
|
|
|
|
#### PTP Implementation (`src/network/ptp/`)
|
|
- Best Master Clock Algorithm
|
|
- Sync message generation
|
|
- Delay measurement
|
|
- Hardware timestamping hooks
|
|
|
|
### Timing Core
|
|
|
|
#### Clock Discipline (`src/timing/clock_discipline.c`)
|
|
- Phase-locked loop (PLL)
|
|
- Frequency-locked loop (FLL)
|
|
- Hybrid PLL/FLL algorithm
|
|
- Drift compensation
|
|
|
|
#### Time Sources (`src/timing/time_sources.c`)
|
|
- Source priority management
|
|
- Quality assessment
|
|
- Automatic failover
|
|
- Source statistics
|
|
|
|
## Build System
|
|
|
|
### CMake Configuration
|
|
```cmake
|
|
# Feature flags
|
|
option(ENABLE_NTP "Enable NTP protocol" ON)
|
|
option(ENABLE_PTP "Enable PTP protocol" ON)
|
|
option(ENABLE_GPS "Enable GPS support" ON)
|
|
option(ENABLE_IRIG "Enable IRIG support" ON)
|
|
option(ENABLE_WEB "Enable web interface" ON)
|
|
option(DEBUG_OUTPUT "Enable debug output" OFF)
|
|
```
|
|
|
|
### Memory Layout
|
|
```
|
|
RAM Usage (264KB total):
|
|
- FreeRTOS heap: 128KB
|
|
- Network buffers: 32KB
|
|
- Time data structures: 16KB
|
|
- Stack space: 32KB
|
|
- BSS/Data: ~56KB
|
|
|
|
Flash Usage (4MB total):
|
|
- Application code: ~256KB
|
|
- Web content: ~64KB
|
|
- Configuration: 4KB
|
|
- Reserved: ~3.7MB
|
|
```
|
|
|
|
## Configuration Files
|
|
|
|
### System Configuration (`src/config.h`)
|
|
```c
|
|
// Network settings
|
|
#define DEFAULT_IP_ADDRESS "192.168.1.100"
|
|
#define DEFAULT_SUBNET_MASK "255.255.255.0"
|
|
#define DEFAULT_GATEWAY "192.168.1.1"
|
|
|
|
// Time source priorities (0 = highest)
|
|
#define PRIORITY_GPS 0
|
|
#define PRIORITY_PTP 1
|
|
#define PRIORITY_NTP 2
|
|
#define PRIORITY_IRIG 3
|
|
|
|
// Timing parameters
|
|
#define PLL_UPDATE_INTERVAL_MS 1000
|
|
#define DRIFT_COMP_WINDOW_S 3600
|
|
#define MAX_OFFSET_JUMP_MS 1000
|
|
```
|
|
|
|
## Inter-Task Communication
|
|
|
|
### Message Queues
|
|
- Time update queue
|
|
- Network packet queue
|
|
- Configuration queue
|
|
- Statistics queue
|
|
|
|
### Semaphores/Mutexes
|
|
- Clock access mutex
|
|
- Network resource mutex
|
|
- Configuration mutex
|
|
- Statistics buffer mutex
|
|
|
|
### Event Groups
|
|
- Time source events
|
|
- Network events
|
|
- System status events
|
|
|
|
## Development Guidelines
|
|
|
|
1. **Coding Standards**
|
|
- MISRA-C 2012 compliance where practical
|
|
- Consistent naming convention
|
|
- Comprehensive error handling
|
|
|
|
2. **Real-Time Considerations**
|
|
- Minimize ISR execution time
|
|
- Avoid dynamic memory allocation
|
|
- Use fixed-priority preemptive scheduling
|
|
|
|
3. **Testing Strategy**
|
|
- Unit tests for algorithms
|
|
- Integration tests for protocols
|
|
- System tests with reference clocks
|
|
|
|
4. **Documentation**
|
|
- Doxygen comments for APIs
|
|
- Design documents for complex modules
|
|
- User manual for configuration |