Tracking and Control Logic

Tracking and Control Logic

Overview

Pi-Sat continuously separates three control areas:

• pass prediction
• live RF tracking
• live rotator control

Those systems are related, but they are still kept logically separate.

Autotrack Behavior

When autotrack is enabled:

• the app follows the first active pass in the pass list
• overlapping passes stay on the pass that started first
• when that pass ends, the app advances to the next pass in the list

When a user manually selects a pass or satellite:

• autotrack is disabled
• the UI stays on the user-selected target until changed again or autotrack is re-enabled

Pass Timing vs Pass Filtering

Pi-Sat keeps two separate ideas:

• pass-list filtering can use a minimum pass elevation threshold
• live pass state and UI pass timing are based on the actual horizon crossing at 0.0 degrees

This is intentional. It allows the operator to ignore low-value passes in the list while still seeing real AOS and LOS timing for the selected pass.

RX and TX Tracking Logic

The tracking loop for the selected satellite and profile does the following:

1. reads orbital position
2. computes Doppler from range rate
3. builds the target RX frequency
4. builds the target TX frequency if the profile is not RX-only
5. preserves manual user offset on top of changing Doppler
6. writes updated targets to the RX and optional TX control paths
7. receives readback updates from connected devices when available

Why User Offset Is Preserved

Manual tuning is treated as operator intent. If the user adjusts the downlink or uplink, that offset should stay in place while Doppler continues to move around it.

Without that behavior, manual corrections would constantly be wiped out by the next tracking update.

Sync RX and TX Offset Logic

When sync is enabled:

• changing the RX offset also maps the corresponding TX offset
• changing the TX offset also maps back to RX

When sync is disabled:

• RX and TX offsets can be adjusted independently

RX-only profiles do not use TX offset logic.

Rotator Command Logic

Pi-Sat only sends rotator tracking commands when all of the following are true:

• rotator control is enabled
• config-level rotator writes are enabled
• the selected pass is active
• the target elevation is at or above the configured rotator minimum elevation

If a tracked satellite is below that threshold, Pi-Sat keeps state updated but does not send movement commands.

Manual Rotator Control

Manual rotator controls are intended for periods with no active pass ownership.

During an active pass:

• pass tracking owns the rotator
• manual mode is disabled

When no active pass exists:

• manual moves are allowed

Return Home After Pass

If enabled, Pi-Sat sends the rotator to its configured home target immediately after a tracked pass ends.

This is useful when the operator wants the rotator to reset between passes instead of holding the last commanded position.

AOS and LOS Automation Logic

If AOS and LOS scripts are configured, Pi-Sat can trigger those scripts on real pass events.

Typical uses include:

• starting a recording process at AOS
• stopping a recording process at LOS
• running an operator-defined workflow around the pass window

These scripts are optional and are configured through the settings page.

TX Safety Logic

TX safety checks can inhibit uplink behavior based on:

• below-horizon state
• CAT or control loss
• lack of a valid pass state

These checks exist to prevent transmitting under obviously invalid tracking conditions.