noisedestroyers/pico-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cead28fdd63563952aca59d16f1d23bf46bfa30a
pico-platform/PROJECT_STRUCTURE.md

7.8 KiB
Raw Blame History

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)

// 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

# 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)

// 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