ZED Manager Finite State Machine¶

This document describes the finite state machine (FSM) that manages the ZED GNSS module operation in the RTK Base firmware.

Overview¶

The ZED Manager (zed_f9p_manager) implements a state machine that controls the ZED-F9P or ZED-F20 GNSS module from initialization through to operational RTK fixed mode.

State Diagram¶

stateDiagram-v2
    [*] --> ZED_INITIALIZATION
    ZED_INITIALIZATION --> ZED_CONFIGURE : Power on / Reset complete

    ZED_CONFIGURE --> ZED_TESTING : Production test not done
    ZED_CONFIGURE --> ZED_GET_STARTUP_POSITION : Production test done

    ZED_TESTING --> ZED_GET_STARTUP_POSITION : Production test complete

    ZED_GET_STARTUP_POSITION --> ZED_WAIT_INPUT : Position valid, No stored ref position
    ZED_GET_STARTUP_POSITION --> ZED_FIX_MODE : Position valid, Delta < threshold
    ZED_GET_STARTUP_POSITION --> ZED_GET_STARTUP_POSITION : Timeout (15 min) → Error

    ZED_WAIT_INPUT --> ZED_SURVEY : Survey button pressed
    ZED_WAIT_INPUT --> ZED_WAIT_INPUT : Wait for user action

    ZED_SURVEY --> ZED_GET_STARTUP_POSITION : Survey complete, Accuracy OK
    ZED_SURVEY --> ZED_SURVEY : Survey timeout → Error, Can retry

    ZED_FIX_MODE --> ZED_FIX_MODE : RTCM consistent
    ZED_FIX_MODE --> ZED_FIX_MODE : RTCM inconsistent (30s) → Error
    ZED_FIX_MODE --> ZED_SURVEY : User triggers new survey
    ZED_FIX_MODE --> ZED_INITIALIZATION : ZED reset detected

    note right of ZED_GET_STARTUP_POSITION
        Waits 20s for RTCM corrections
        Minimum 30s observation time
        Max 15 min timeout
    end note

    note right of ZED_SURVEY
        Default: 90 sec (Fast SVIN)
        Max: 24 hours
        Auto-restart when corrections arrive
    end note

State Definitions¶

ZED_INITIALIZATION (0)¶

Description: Initial power-on or reset state.

Entry Actions: - Reset ZED module communication - Wait 2 seconds for ZED to fully boot

Exit Conditions: - Automatic transition to ZED_CONFIGURE on first iteration

Duration: < 2 seconds

ZED_CONFIGURE (1)¶

Description: Configuration and initialization of the ZED module.

Entry Actions: - Verify UART baudrate with ZED - Load configuration valueset (ZED-F9P or ZED-F20 specific) - Configure measurement rate (1000ms default) - Fetch antenna status - Fetch unique ID

Exit Conditions: - If production test NOT done → transition to ZED_TESTING - If production test DONE → transition to ZED_GET_STARTUP_POSITION

Key Configurations: - CFG_MSGOUT_UBX_NAV_SVIN_UART1: Survey-in message output - CFG_RATE_MEAS: Measurement rate (default 1000ms)

ZED_TESTING (2)¶

Description: Production testing state for factory validation.

Entry Actions: - Run production tests (firmware version, satellite count, antenna)

Exit Conditions: - Production test complete → transition to ZED_GET_STARTUP_POSITION

Note: This state is skipped during normal operation.

ZED_GET_STARTUP_POSITION (3)¶

Description: Determining the initial position to validate against stored reference.

Entry Actions: - Clear ZED_ERROR_GET_STARTUP_POSITION error bit - Start requesting RTCM corrections if reference position requires them

Exit Conditions:

1. No stored reference position → ZED_WAIT_INPUT
2. Position is valid (sufficient satellites, accuracy OK)

3. No reference position in NVS

4. Position matches reference → ZED_FIX_MODE

5. Delta < 7m (without corrections)

6. Delta < 0.5m (with corrections + precise reference)

7. Timeout (15 minutes) → Set error bit

8. Log warning
9. Stay in state, set ZED_ERROR_GET_STARTUP_POSITION

Timing Requirements: - Minimum 20 seconds wait for RTCM corrections - Minimum 30 seconds satellite observation time - Maximum 15 minutes total (900 seconds)

Accuracy Requirements: - With corrections: accuracy < zed_survey_accuracy_corr (default 0.5m) - Without corrections: accuracy < initial_accuracy (default 30m)

ZED_WAIT_INPUT (4)¶

Description: Waiting for user action to start survey-in.

Entry Actions: None

Exit Conditions: - Survey button pressed → ZED_SURVEY

User Options: - Start survey-in via web UI, MQTT, or console - Set manual reference position

ZED_SURVEY (5)¶

Description: Survey-in mode for precise position determination.

Entry Actions: - Enable SVIN message output (CFG_MSGOUT_UBX_NAV_SVIN_UART1 = 1) - Start survey-in procedure

Exit Conditions:

1. Survey complete with required accuracy → ZED_GET_STARTUP_POSITION
2. Standard: accuracy < 1m for zed_survey_min_time (default 90s)
3. With corrections: accuracy < zed_survey_accuracy_corr_dyn after CORRECTED_SURVEY_IN_MIN_TIME

4. System then re-evaluates position against reference in GET_STARTUP_POSITION state

5. Timeout → Set ZED_ERROR_SURVEY error bit

6. Default timeout: 90 minutes

7. Maximum timeout: 24 hours

8. Survey restart → Stay in ZED_SURVEY

9. Triggered when corrections arrive after 30 seconds
10. Limited to 1 automatic restart

Dynamic Accuracy:

zed_survey_accuracy_corr_dyn = (1.0/3600) * (elapsed_time)
if zed_survey_accuracy_corr_dyn > zed_survey_accuracy_corr:
    zed_survey_accuracy_corr_dyn = zed_survey_accuracy_corr

Fast SVIN Mode: - Default survey time: 90 seconds - Achieved by feeding RTCM corrections during survey

ZED_FIX_MODE (6)¶

Description: Operational RTK fixed position mode.

Entry Actions: - Configure ZED to fixed position mode using stored reference - Reset RTCM consistency timestamp - Clear ZED_ERROR_FIX error bit

Stay Conditions: - RTCM stream is consistent → remain in ZED_FIX_MODE - Reset timestamp when RTCM consistency confirmed

Error Conditions: - RTCM inconsistent for 30 seconds → Set ZED_ERROR_FIX error bit - ZED uptime resets (module restart detected) → ZED_INITIALIZATION

RTCM Consistency Check: - Period: 30 seconds - Must have received RTCM within period - Track timestamp_last_rtcm_consistent_tick

Error Bits¶

The FSM maintains an error bitmask for fault detection:

graph TD
    A[Error Bitmask] --> B[ZED_ERROR_SURVEY]
    A --> C[ZED_ERROR_FIX]
    A --> D[ZED_ERROR_ANTENNA]
    A --> E[ZED_ERROR_GET_STARTUP_POSITION]
    A --> F[ZED_ERROR_NO_RTCM]
    A --> G[ZED_ERROR_PROBE]
    A --> H[ZED_WARN_CORRECTING_REFPOS]

    B -->|Bit 0| Survey timeout/failure
    C -->|Bit 1| RTK fix lost
    D -->|Bit 2| Antenna short/open
    E -->|Bit 3| Startup position timeout
    F -->|Bit 4| No RTCM corrections
    G -->|Bit 5| ZED not responding
    H -->|Bit 6| Determining real ref position

Error States¶

State Transition Table¶

Timing Constants¶

Reference Position Flags¶

The refpos structure contains flags indicating position characteristics:

Survey-in Flow¶

sequenceDiagram
    participant User
    participant ZED_Manager
    participant ZED_Module
    participant NVS

    User->>ZED_Manager: Press Survey Button
    ZED_Manager->>ZED_Manager: Check state >= GET_STARTUP_POSITION
    ZED_Manager->>ZED_Module: UBX NAV-SVIN enable
    ZED_Manager->>ZED_Module: Start Survey-in

    loop Every Second
        ZED_Module->>ZED_Manager: NAV-SVIN status
        alt Survey < 90 sec
            Note over ZED_Manager: Wait for min time
        else Survey > 90 sec and accuracy OK
            ZED_Manager->>ZED_Manager: Survey OK
            ZED_Manager->>NVS: Save ref position
            ZED_Manager->>ZED_Manager: Move to GET_STARTUP_POSITION
            ZED_Manager->>ZED_Manager: Re-evaluate position delta
            alt Delta < threshold
                ZED_Manager->>ZED_Module: Set Fix Mode
            else Delta > threshold
                ZED_Manager->>ZED_Manager: Set ERROR or WAIT_INPUT
            end
        else Survey timeout
            ZED_Manager->>ZED_Manager: Set ERROR_SURVEY
        else Corrections arrive after 30s
            ZED_Manager->>ZED_Module: Restart Survey
        end
    end

    ZED_Manager->>User: Survey Complete

Key Functions¶

Protection Rules¶

1. Impatient User Protection
2. Cannot jump directly to ZED_SURVEY or ZED_FIX_MODE before reaching ZED_GET_STARTUP_POSITION

3. Returns ESP_FAIL if attempted

4. RTCM Resource Management

5. When leaving a state that wanted RTCM, release RTCM requirement

6. Clears ZED_ERROR_NO_RTCM error bit

7. ZED Reset Detection

8. Monitors ZED uptime
9. If uptime resets and state > ZED_CONFIGURE, restart from ZED_INITIALIZATION

References¶

• Architecture - System architecture overview
• Console Commands - CLI commands for ZED
• REST API - API for state monitoring
• Source: components/zed_f9p_manager/zed_f9p_manager.c