Skip to content
Zipline Zipline Service Documentation

    DISTRO HOVER CONFIGURATION CHECKER

    published Last Updated: Oct 9, 2026 HW: all

    Background

    Section titled “Background”

    The distro hover configuration checker is a startup diagnostic run by distro_a to verify that the four hover motors are installed, provisioned, and wired to the expected hover load switch positions.

    This diagnostic is intended to catch configuration errors that could allow the aircraft to power the wrong hover motor, power multiple hovers unexpectedly, or command a hover with the wrong spin direction.

    At a high level, the checker:

    1. Powers the hover load switches on in sequence.
    2. Waits for each hover node to boot and publish an identity advertisement.
    3. Associates each hover identity advertisement to the load switch that powered it on using boot timing.
    4. Checks whether all four expected hover nodes were seen, whether each hover maps one-to-one to a single expected corner, whether the reported spin direction matches the expected corner, and whether the hardware appears physically swapped versus only provisioned incorrectly.

    If the check is still running, the aircraft is not ready for flight. If the check fails, the resulting distro_a.power_status alarms are launch-blocking / preflight-fail conditions.

    What the checker can alarm on

    Section titled “What the checker can alarm on”

    Aggregate alarms

    Section titled “Aggregate alarms”

    Corner-specific alarms

    Section titled “Corner-specific alarms”

    How to interpret the aggregate alarms

    Section titled “How to interpret the aggregate alarms”

    CONFIGURATION_CHECK_FAILED

    Section titled “CONFIGURATION_CHECK_FAILED”

    This means the diagnostic did not complete in a normal way. Examples include abnormal power-up timing, more than one hover appearing to turn on at once, or the checker running too long without reaching a diagnosable end state.

    This is primarily a sequencing / timing failure, not a clean corner-identification failure.

    Follow the CONFIGURATION_CHECK_FAILED troubleshooting page if this alarm is active.

    HARDWARE_CONFIGURATION_INCORRECT

    Section titled “HARDWARE_CONFIGURATION_INCORRECT”

    This means the checker found one or more corners where the hover spin direction does not match the expected corner. This is commonly accompanied by one or more *_SPIN_INCORRECT alarms and suggests an actual hardware mismatch or incorrect motor installed at that position.

    Follow the HARDWARE_CONFIGURATION_INCORRECT troubleshooting page if this alarm is active.

    REPROVISION_REQUIRED

    Section titled “REPROVISION_REQUIRED”

    This means the hardware appears physically correct, but the software identity / provisioning does not match the expected assignment. This suggests a reprovisioning / deployment / node identity issue rather than a physical installation issue.

    Follow the REPROVISION_REQUIRED troubleshooting page if this alarm is active.

    REQUIRED_NODES_MISSING

    Section titled “REQUIRED_NODES_MISSING”

    This means one or more expected hover nodes were not seen or could not be matched to the expected sequence. This is commonly accompanied by one or more *_MISSING alarms.

    Follow the REQUIRED_NODES_MISSING troubleshooting page if this alarm is active.

    REQUIRED_NODES_DUPLICATED

    Section titled “REQUIRED_NODES_DUPLICATED”

    This means more than one hover identity appeared associated with a single hover load switch position. This is commonly accompanied by one or more *_DUPLICATED alarms.

    Follow the REQUIRED_NODES_DUPLICATED troubleshooting page if this alarm is active.

    NODES_APPEAR_SWAPPED

    Section titled “NODES_APPEAR_SWAPPED”

    This means the checker found a one-to-one mapping and spin direction looked correct, but the hover nodes appear to be installed in the wrong physical corners. This suggests a physical swap.

    Follow the NODES_APPEAR_SWAPPED troubleshooting page if this alarm is active.

    Where to look in telemetry

    Section titled “Where to look in telemetry”

    Use distro_board_telemetry.hover_configuration_checker from distro_a board telemetry.

    The most useful fields are:

    • state
    • fingerprint_count
    • per-corner tracker state
    • per-corner id_message_count
    • per-corner loadswitch_match_count
    • per-corner associated_loadswitch_node_id
    • per-corner spin_direction
    • per-corner spin_direction_match
    Section titled “Related pages”
    1 reference
    CONFIGURATION_CHECK_FAILED

    Did this guide help you get unblocked?

    Open suggestions

    There are no open suggestions.

    Open pull requests

    There are no open pull requests.

    Edit this page on GitHub
    Topic history
    1. 2026-10-07 Susan Minne Bulk/mechanical change
      Replace individual guide ownership with system technical contacts
      Commit dca5a1a
    2. 2026-09-24 Susan Minne Bulk/mechanical change
      chore: backfill aircraft owner identities batch 2
      Commit 6ca6807
    3. 2026-09-23 Susan Minne Bulk/mechanical change
      docs: remove obsolete Confluence metadata
      Commit 2d5374e
    4. 2026-09-13 Susan Minne Bulk/mechanical change
      feat: add MX approval metadata to topics
      Commit 406a785
    5. 2026-05-31 cjmoore-zipline Bulk/mechanical change
      Refresh stale troubleshooting guide owners
      Commit 9386bd4
    6. 2026-05-28 Susan Minne Bulk/mechanical change
      Remove redundant topic applicability banners
      Commit e561ad0
    7. 2026-05-14 Susan Minne Bulk/mechanical change
      Review of migrated topics and set to published
      Commit d5f3ec5
    8. 2026-05-11 Gavin Edwards
      Fix broken corner-specific alarm links in DISTRO HOVER CONFIGURATION CHECKER (#436)
      Commit 23ae40d PR #436
    9. 2026-05-09 Susan Minne Bulk/mechanical change
      Fix high-confidence internal documentation links
      Commit a6593fc
    10. 2026-05-06 Gavin Edwards Bulk/mechanical change
      Remove redundant Engineer Owner table from topic body (#298)
      Commit 1619f07 PR #298
    Baseline import
    Initial import into service_docs
    Imported by Gavin Edwards on 2026-05-06
    Migrate Susan's missing topics from #292
    Commit f2f29d2
    Suggest a change