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 are related, but still separate in many ways.

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

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. Times are always calculated on passing a horizon and not user-set elevation values.

RX/TX Tracking Logic

The tracking loop for the selected satellite/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 SDR and optional TX radio
7. receives updates from the SDR or radio(s) in use to update the system if changes were made outside of it

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 get wiped out by the next tracking update. What good would that be?

Sync RX/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
• 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 the 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.

TX Safety Logic

TX safety checks can inhibit uplink behavior based on:

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

These are intended to prevent transmitting under obviously invalid tracking conditions.