# 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