pico-platform/DEVELOPMENT_INSTRUCTIONS.md

# RP2040-ETH Precision Timing Tool Development Instructions

## Project Overview
A precision timing tool using Waveshare RP2040-ETH with FreeRTOS for complex timing and scheduling operations.

### Input Protocols
- NTP (Network Time Protocol)
- PTP (Precision Time Protocol)
- IRIG (Inter-Range Instrumentation Group time codes)
- GPS (Global Positioning System time)
- PPS (Pulse Per Second)

### Output Protocols
- PTP (Precision Time Protocol)
- NTP (Network Time Protocol)
- IRIG-A (Audio frequency time code)

## Development Environment Setup

### Prerequisites
1. **ARM GCC Toolchain**: arm-none-eabi-gcc
2. **CMake**: Version 3.13 or higher
3. **Pico SDK**: Will be included as submodule
4. **FreeRTOS**: Will be included from RP2040-FreeRTOS repository
5. **Python 3**: For build tools and utilities

### Initial Setup Steps
```bash
# 1. Clone the FreeRTOS-RP2040 repository as reference
git clone --recursive https://github.com/smittytone/RP2040-FreeRTOS.git reference/

# 2. Set up Pico SDK environment variable
export PICO_SDK_PATH=/path/to/pico-sdk

# 3. Install required tools
# macOS:
brew install cmake python3 gcc-arm-embedded

# Linux:
sudo apt update
sudo apt install cmake gcc-arm-none-eabi libnewlib-arm-none-eabi build-essential
```

## Project Architecture

### Core Components

1. **FreeRTOS Kernel Integration**
   - Task scheduling for time-critical operations
   - Inter-task communication via queues
   - Software timers for periodic updates
   - Interrupt handling for PPS and timing signals

2. **Network Stack (CH9120)**
   - Ethernet controller management
   - TCP/UDP protocol implementation
   - NTP client/server functionality
   - PTP protocol stack

3. **Timing Core**
   - High-precision time keeping
   - Clock synchronization algorithms
   - Time source arbitration
   - Drift compensation

4. **Protocol Handlers**
   - NTP: RFC 5905 implementation
   - PTP: IEEE 1588 implementation
   - IRIG: Time code generation/decoding
   - GPS: NMEA/UBX parsing
   - PPS: Edge detection and timestamping

### Task Structure

```
Main Tasks:
├── Network Task (Priority: High)
│   ├── Ethernet management
│   ├── Protocol handling
│   └── Packet processing
├── Timing Task (Priority: Critical)
│   ├── Clock maintenance
│   ├── Synchronization
│   └── Drift correction
├── Input Task (Priority: High)
│   ├── GPS parsing
│   ├── PPS handling
│   └── IRIG decoding
├── Output Task (Priority: Normal)
│   ├── NTP server
│   ├── PTP master
│   └── IRIG-A generation
└── Management Task (Priority: Low)
    ├── Configuration
    ├── Monitoring
    └── Statistics
```

## Build Configuration

### CMake Structure
```cmake
# Main CMakeLists.txt
cmake_minimum_required(VERSION 3.13)
include(pico_sdk_import.cmake)
project(precision_timing_tool)
pico_sdk_init()

# Add FreeRTOS
add_subdirectory(FreeRTOS-Kernel)

# Project sources
add_executable(timing_tool
    src/main.c
    src/network/ch9120.c
    src/network/ntp.c
    src/network/ptp.c
    src/timing/clock.c
    src/timing/sync.c
    src/io/gps.c
    src/io/pps.c
    src/io/irig.c
)

# Link libraries
target_link_libraries(timing_tool
    pico_stdlib
    hardware_spi
    hardware_i2c
    hardware_dma
    hardware_pio
    hardware_timer
    FreeRTOS
)
```

## Hardware Connections

### Pin Assignments
```
CH9120 Ethernet Controller:
- UART1 TX: GPIO 20
- UART1 RX: GPIO 21
- CFG: GPIO 18
- RES: GPIO 19

GPS Module:
- UART0 TX: GPIO 0
- UART0 RX: GPIO 1
- PPS: GPIO 2 (interrupt)

IRIG Interface:
- Input: GPIO 3 (capture)
- Output: GPIO 4 (PWM)

Status LEDs:
- System: GPIO 25
- GPS Lock: GPIO 26
- Network: GPIO 27
- PTP Sync: GPIO 28
```

## Development Workflow

1. **Initial Development**
   - Set up basic FreeRTOS tasks
   - Implement CH9120 driver
   - Create timing core structure

2. **Protocol Implementation**
   - Start with NTP client
   - Add GPS time source
   - Implement PPS interrupt handler
   - Add NTP server functionality

3. **Advanced Features**
   - PTP implementation
   - IRIG encoding/decoding
   - Clock discipline algorithms
   - Web configuration interface

4. **Testing & Validation**
   - Unit tests for protocol handlers
   - Integration tests with reference clocks
   - Long-term stability testing
   - Network stress testing

## Configuration

### FreeRTOSConfig.h Key Settings
```c
#define configUSE_PREEMPTION                    1
#define configUSE_PORT_OPTIMISED_TASK_SELECTION 0
#define configUSE_TICKLESS_IDLE                 0
#define configCPU_CLOCK_HZ                      133000000
#define configTICK_RATE_HZ                      1000
#define configMAX_PRIORITIES                    32
#define configMINIMAL_STACK_SIZE                256
#define configTOTAL_HEAP_SIZE                   (128 * 1024)
#define configUSE_MUTEXES                       1
#define configUSE_RECURSIVE_MUTEXES             1
#define configUSE_COUNTING_SEMAPHORES           1
#define configQUEUE_REGISTRY_SIZE               8
#define configUSE_QUEUE_SETS                    1
#define configUSE_TIME_SLICING                  1
```

## Debugging

### Debug Output
- UART0: GPS data (when not connected)
- USB Serial: Debug console
- SWD: Hardware debugging

### Performance Monitoring
- FreeRTOS task statistics
- Network packet counters
- Time synchronization metrics
- Clock drift measurements

## Next Steps

1. Create project structure based on FreeRTOS template
2. Implement basic CH9120 communication
3. Add GPS NMEA parser
4. Implement NTP client
5. Add PPS interrupt handler
6. Create basic web interface
7. Implement additional protocols

## Innovative Ideas

1. **Multi-source Time Fusion**
   - Kalman filter for optimal time estimation
   - Automatic source quality assessment
   - Seamless failover between sources

2. **Adaptive Network Timing**
   - Machine learning for network delay prediction
   - Dynamic packet rate adjustment
   - Congestion-aware protocol selection

3. **Hardware Timestamping**
   - PIO state machines for precise capture
   - DMA-based packet timestamping
   - Sub-microsecond accuracy

4. **Configuration Options**
   - Web-based management interface
   - SNMP monitoring
   - REST API for integration
   - Mobile app for configuration