System Architecture¶

This document describes the software architecture of the RTK Base firmware (version 4.0.x).

Main System Diagram¶

The RTK Base consists of multiple interconnected modules managing different aspects of the system.

Software Modules¶

Core Modules¶

Finite State Machines¶

ZED State Machine¶

The ZED GNSS module operates through several distinct states:

flowchart TD
    Init_UART[UART Baudrate Check]
    ZedConfigState[Update ZED Configuration]
    GetStartupPosState[Get Startup Position]
    WaitForUserState[Wait for User Input]
    FixedModeState[Fix Mode]
    SurveyInState[Survey-in]

    Init_UART --> ZedConfigState
    ZedConfigState --> GetStartupPosState
    GetStartupPosState -->|ref_position_available + valid_position| FixedModeState
    GetStartupPosState -->|!ref_position_available + valid_position| WaitForUserState
    WaitForUserState -->|svin_started| SurveyInState
    FixedModeState -->|svin_started| SurveyInState
    SurveyInState -->|svin_position_available| FixedModeState
    WaitForUserState -->|manual_ref_position_available| FixedModeState

    style FixedModeState fill:#008000,color:white
    style WaitForUserState fill:#ff8000,color:white

States:

1. UART Baudrate Check: Probes for ZED module at different baudrates
2. ZED Configuration: Loads configuration for F9P or F20 module
3. Get Startup Position: Acquires initial coarse position
4. Wait for User Input: No valid reference position exists; requires manual intervention
5. Fix Mode: Operational mode with valid reference position
6. Survey-in: Refining position accuracy (90 seconds with Fast SVIN)

RTK Base Main State¶

System state is derived from component states:

flowchart TD
    ZE{{ZED Error?}}
    NE{{Ethernet Ready?}}
    STA{{WiFi STA Ready?}}
    MQ{{MQTT Ready?}}
    F[Fault State]
    B[Base State]

    ZE -->|yes| F
    NE -->|no + MQTT not ready| F
    STA -->|no + STA configured + MQTT not ready| F
    MQ -->|no + 4G| F
    ZE -->|no faults| B
    NE -->|ok| B
    STA -->|ok| B
    MQ -->|ok| B

    style F fill:#ff0000,color:white
    style B fill:#00aa00,color:white

LED State Indicators¶

The RGB and discrete LEDs provide visual feedback of system state:

Error Indication¶

When in Fault state, press the configuration button to display error type:

Connectivity Modes¶

WiFi Access Point (AP)¶

Use Cases: - UDP client socket to transmit RTCM to robots - Reverse proxy: Internet via MQTT

Features: - SSID: Configurable (default: RTKWifi) - Security: WPA2 - Max clients: 5

WiFi Station (STA)¶

Use Cases: - Internet access via existing WiFi - MQTT cloud connection

Ethernet¶

Primary Use: - Internet access for MQTT cloud connection - Router configuration and management

Default Gateway Selection¶

Priority order for MQTT cloud connection:

1. WiFi STA (highest priority)
2. Connected and gateway assigned
3. Ethernet
4. Connected and gateway assigned
5. AP Reverse Gateway
6. MAC configured and client connected
7. None - MQTT stopped

ZED Module Configuration¶

ZED-F9P (Standard)¶

Constellations:

• GPS (L1/L2)
• GLONASS (L1/L2)
• Galileo (E1/E5b)
• BeiDou (B1/B2)
• QZSS (L1/L2)

Features: - Dual-band reception - RTK positioning - Raw measurement output

ZED-F20 (Advanced)¶

Constellations:

• GPS (L1/L2/L5)
• GLONASS (L1/L2)
• Galileo (E1/E5a/E5b/E6)
• BeiDou (B1/B2/B3)
• QZSS (L1/L2/L5)
• NAVIC (L5)

Features: - Triple-band reception (dual/tri-band UI display) - Improved multipath rejection - Faster convergence - Better performance under canopy

Reference Position Management¶

v4.0 Migration¶

The v4.0 firmware introduces automatic migration from v3.x:

1. Detection: System detects missing antenna position on first boot
2. Auto-Calibration: Performs automatic survey-in (~90 seconds)
3. Storage: Saves position and delta correction
4. Validation: 0.5m delta check with corrections, 7m without

Position Sources¶

1. Survey-in: Automatic precision determination
2. Manual Entry: User-specified ECEF or LLA coordinates
3. Fast SVIN: Accelerated survey with RTCM corrections (90 seconds)

Communication Interfaces¶

REST API¶

• HTTP server on port 80
• JSON request/response
• Full system control and monitoring

MQTT¶

• TLS-encrypted connection
• RTCM data publication
• Remote command execution
• Status reporting

TCP API¶

• Port 8000
• Raw UBX/RTCM/NMEA stream
• Bidirectional communication

UDP¶

• Port 5003 (configurable)
• RTCM broadcast in AP mode
• Multiple client support

Data Flow¶

GNSS Antenna
    ↓
ZED Module (F9P/F20)
    ↓
RTCM Parser
    ↓
Distribution:
    ├── MQTT → Cloud broker
    ├── UDP → Local clients
    └── TCP → Connected clients

Error Handling¶

Error Levels¶

1. Warning: Non-critical, logged only
2. Error: Affects functionality, LED indication
3. Fatal: System unusable, requires service

Recovery¶

• Automatic reconnection for network errors
• ZED reset on communication failure
• Fallback to safe defaults on configuration errors

References¶

• REST API
• MQTT API
• Console Commands
• Fast SVIN