Source & architecture

A deep technical reference for the OrbitDeck for iOS codebase — subsystem by subsystem — so you can read it, extend it, or verify the math. It documents the actual types, algorithms and data flow, not just the shape of the app.

View the repository on GitHub User documentation

Overview

OrbitDeck is a native SwiftUI application for iPhone and iPad (iOS/iPadOS 17+) that computes satellite passes, Doppler, look angles, footprints, link budgets, and a large set of orbital-analysis and operating tools entirely on-device from live orbital elements. It is a companion to the OrbitDeck desktop app and CardSat by Paul Stoetzer, N8HM.

The architecture is deliberately layered and framework-light: one observable store holds all state, pure engine types do the math, thin service types fetch data and talk to the system, and SwiftUI views render it. There is no external app framework and no database. Roughly 73,000 lines of Swift in the app target — Views ~19k, Engine ~18k, digital modes (FT4, packet/APRS, CW and DeepCW, SSTV) ~12k, rig control ~8k, Services ~4.4k, logging ~3.3k, rotator ~2.6k, Models ~2.5k, audio and recording ~2k — plus a WidgetKit extension for the Live Activity (~0.8k) and a Swift Testing suite (~3.5k). Third-party code is limited to the SGP4/SDP4 propagator SatelliteKit (a Swift package dependency), the MIT-licensed ft8_lib (FT4/FT8, vendored C), and the MIT-licensed DeepCW model (bundled as Core ML).

Tech stack

ConcernChoice
UISwiftUI (declarative); MapKit for maps; Canvas for polar/sky plots; Core Graphics / UIGraphicsPDFRenderer for PDF export
Live ActivityActivityKit + WidgetKit in the OrbitDeckWidgets extension (Lock Screen, Dynamic Island, Apple Watch Smart Stack); local updates only (no push), BGAppRefreshTask for background replans, and an opt-in scheduled activity for a later pass on iOS 26+
Audio & DSPAVAudioEngine capture/playback, Accelerate (vDSP) for spectra and filters, Core ML for the DeepCW CW decoder, the vendored ft8_lib C library for FT4
NetworkingURLSession for HTTPS services; Network.framework for the Icom RS-BA1 UDP protocol, rigctld/rotctld clients and servers, KISS over TCP, APRS-IS, DX cluster and telnet
ConcurrencySwift async/await and Task/Task.detached. Combine is used only through ObservableObject/@Published and a single subscription in AudioHub; new code uses async APIs.
PropagationSatelliteKit (SGP4/SDP4), resolved by Swift Package Manager at build time (not vendored)
PersistenceUserDefaults (preferences as JSON), the Keychain (secrets), and on-disk JSON under Application Support (GP catalog, SatNOGS DB, space weather, the QSO log and media indexes)
Minimum OSiOS/iPadOS 17 for the app; iOS 18 for the Live Activity extension (on iOS 17 the app runs without it); iOS 26 for the scheduled next-pass activity
DependenciesOne package: SatelliteKit. No analytics, ads, or tracking SDKs.

Repository layout

The top level of the repository:

PathContents
OrbitDeckIOS/The app target (SwiftUI), split by role (below). Not a synchronized folder: new source files must be added to the target in Xcode.
OrbitDeckIOS.xcodeprojThe Xcode project: the OrbitDeckIOS app, the OrbitDeckWidgets extension and the OrbitDeckIOSTests test target.
OrbitDeckWidgets/The widget extension: the next-pass Live Activity for the Lock Screen, Dynamic Island and Apple Watch Smart Stack (OrbitDeckWidgets.swift, OrbitDeckWidgetsBundle.swift). A synchronized folder. Its OrbitDeckPassAttributes is duplicated in Models/OrbitStore.swift, because the app target can't see extension files; the two copies must stay identical.
OrbitDeckIOSTests/The unit tests (Swift Testing), 19 test files. A synchronized folder, so new test files are compiled automatically.
examples/CardSat-BASIC/Sample Tiny BASIC programs (.BAS) that run in the app.
tools/deepcw/The DeepCW model pipeline: convert_deepcw.py (ONNX → PyTorch → Core ML, checked against ONNX Runtime at each step), cw_ref.py (a Python reference of the app's streaming decoder, runnable on the ONNX or Core ML model) and make_cw.py (noisy CW test audio), with a README.
PrivacyInfo.xcprivacyThe app's privacy manifest (required-reason APIs and declared data types).
docs/This website (GitHub Pages, served at orbitdeckios.n8hm.radio).
fastlane/, scripts/App Store screenshot automation (scripts/screenshots.sh and a fastlane Snapfile), a simulator build script, and standalone parity smoke scripts and a Tiny BASIC regression script.
THIRD_PARTY_NOTICES.md, LICENSEThird-party credits and the MIT license.

Inside OrbitDeckIOS/:

PathContents
OrbitDeckIOSApp.swift, AppTheme.swift, OrbitDeck-Bridging-Header.hThe @main entry point, the design tokens, and the bridging header that exposes ft8_lib's C API to Swift.
Models/OrbitStore.swiftThe single source of truth (@MainActor observable store) plus OrbitSecretStore (Keychain), automatic satellite switching and the LiveActivityController.
Models/SatelliteModels.swiftThe value types: ObserverSite, SatelliteRecord, TransponderRecord, PredictedPass, LiveLook, SkyPoint, RadioCalibration, StorePreferences, ManualSatelliteDefinition, enums.
Engine/OrbitPredictor.swiftLook angles, pass prediction, ground track, Doppler, footprint, beta angle.
Engine/FeatureEngine.swiftSun/Moon/planet positions, Maidenhead/VUCC, footprint sets, space-weather fetch, EME, transits, zones, orbital history, MUF, hams.at and AMSAT status clients.
Engine/FeatureCompletionEngine.swiftLink budgets, radio playbook, EME band analysis, satellite eclipse timelines, conjunction detail.
Engine/ParityPlanningEngine.swiftWorkable grids/states/DXCC, mutual and rove windows, satellite↔satellite LOS, visible passes, horizon masks, and the Open-Meteo weather client.
Engine/AstronomyParityEngine.swiftAurora outlook, occultations, appulses, solar/lunar eclipses and shadow tracks.
Engine/DeepParityEngine.swiftThe Tiny BASIC interpreter, the bench-tool math, and OrbitDecayModel.
Engine/UtilityEngine.swiftThe safe math evaluator, the graphing engine, shared calculator plumbing, and the in-app Help text.
Engine/DXCCData.swiftThe DXCC entity roster and GeoEntityLookup (reverse geocode → DXCC + ADIF/LoTW subdivisions).
Engine/DXCCNumericData.swiftARRL numeric entity codes and representative coordinates (used by Tiny BASIC).
Engine/WorldMapData.swiftPublic-domain Natural Earth coastline polygons for the flat/globe maps.
Services/GPService, TransponderService, AO7Service, LocationProvider, ExportService (PDFs, text exports, station reports, backup & restore), XLSXExportService, PassAlarmService.
CAT/Rig control: radio catalog and config, the PTTAuthority, codecs, BLE/Icom-network/rigctld transports, the rigctld server and client approval, the controller and its views.
Rotator/Rotator control: protocols, codecs, network transport, the rotctld server, the controller and its views.
Audio/, Recording/Audio sources (USB, Icom network audio, built-in mic), the AudioHub, DSP helpers and remote voice; pass recordings and voice memos.
Log/The QSO log, ADIF, LoTW signing, Cloudlog/Wavelog, gzip, awards, and the Log screens.
DigitalModes/FT4Engine.swift (FT4, PSKReporter, packet/APRS modems, KISS, the APRS-IS satgate, the classic CW decoder and the DeepCW pipeline) and FT4Views.swift; SSTV/; ft8_lib/ (vendored C, MIT); DeepCW/ (DeepCW.mlpackage and its MIT LICENSE).
Diagnostics/DebugLog.swiftThe on-device diagnostic log (ODLog) with rotation.
Views/All other SwiftUI screens: RootView, HomeView, GroundTrackView, PassesView, RadioView, SettingsView (including Acknowledgments), the multi-screen files (FeatureViews, AdvancedFeatureViews, DeepParityViews, UtilityFeatureViews), and shared UI (Components).

App entry & lifecycle

OrbitDeckIOSApp is the @main entry point. Its init registers the Live Activity background refresh. It owns the app's long-lived @StateObjects — the OrbitStore, the NotificationRouter, the rig and rotator controllers, the AudioHub, the QSOStore, the recorder, the SSTV, FT4, packet and CW engines, remote voice, auto switching and the LiveActivityController — injects them all as environment objects into RootView, and forces the dark color scheme. A single launch .task wires them together, then bootstraps the store:

WindowGroup {
    RootView()
        .environmentObject(store)
        .environmentObject(notifications)
        // … the other controllers and engines …
        .preferredColorScheme(.dark)
        .task {
            notifications.activate()
            rig.attach(store)
            // … rotator, rigctld/rotctld servers, audio, log, digital modes …
            await store.bootstrap()
            autoSwitch.attach(store)
            liveActivity.attach(store: store, autoSwitch: autoSwitch)
        }
}

bootstrap() loads the cached catalog, any imported element sets, the transponder database and the space-weather snapshot from disk (so the app is usable offline immediately), then performs the cadence checks that trigger a background refresh only when data is stale. A scene-phase handler lets the Live Activity start or refresh on foreground and flushes the FT4 activity log on background.

State & persistence

OrbitStore is an @MainActor final class OrbitStore: ObservableObject, created once and shared via @EnvironmentObject. It is the single source of truth for the whole app.

Published state

  • satellites: [SatelliteRecord] — the working catalog.
  • preferences: StorePreferences — every user setting (see below); its didSet persists and syncs the time-zone flag.
  • spaceWeather: SpaceWeatherSnapshot?, currentLocationEntity: GeoLocationEntity?.
  • isRefreshingGP, isRefreshingTransponders, statusMessage, lastError, lastGPRefresh.

Key methods

MethodRole
bootstrap()Load caches, refresh what's stale.
refreshGP()Fetch elements via GPService, respect the CelesTrak cadence, cache to disk.
refreshAllTransponders() / …IfNeeded()Download the SatNOGS DB and apply it to every satellite; the "if needed" variant only runs when the cache is missing or older than about a week.
refreshSpaceWeatherIfNeeded(maxAge:)Refresh solar/geomagnetic indices when stale (about hourly) or on foreground.
select(_:), setLocationMode(_:), applyCurrentLocation(latitude:longitude:altitudeMeters:)Selection and observer-position management. Switching to fixed restores the preserved savedFixedSite; following writes the live fix into the observer under the "Current location" name.
refreshLocationEntity()Reverse-geocode the observer into currentLocationEntity, throttled to a ~1 km key so a moving fix doesn't spam the geocoder.
calibration(for:), setCalibration(_:for:), downlinkCalibrationHz(for:invert:)Per-satellite radio calibration; the last folds the stored offsets into a single receive-referred correction (uplink sign-flipped on an inverting transponder).
operatorGrid, operatorGrid6, operatorVuccGridsMaidenhead locators and the claimable VUCC grid list for the current observer.

Persistence & secrets

StorePreferences is one Codable struct; its didSet JSON-encodes it into UserDefaults under a versioned key, so every setting is saved the instant it changes and there is no separate save step. New fields are added as Optional so older stored blobs keep decoding without a migration. The GP catalog, SatNOGS database and space-weather snapshot are cached as JSON files under Application Support. Secrets (the QRZ and Space-Track passwords, the hams.at API key, Icom network radio passwords, the LoTW .p12 passphrase, the Cloudlog/Wavelog API key and the APRS-IS passcode) go through OrbitSecretStore to the iOS Keychain as this-device-only generic-password items — never the preferences JSON. The LoTW .p12 itself is a file in Application Support written with complete file protection. CelesTrak requests are gated by a two-hour cooldown per group (or custom URL), so switching groups still fetches the new one; an HTTP 403/429 sets a device-wide back-off, because CelesTrak's limit is per IP address.

Because there is exactly one store and it is @Published, any screen reflects a preference change immediately; SwiftUI re-renders what changed and the app needs no separate reload plumbing.

Domain models

All domain types are value types (mostly Sendable) in SatelliteModels.swift, so heavy work moves off the main actor freely.

  • ObserverSite — name, latitude, longitude, altitude; satelliteKitLocation bridges to SatelliteKit; coarseKey (~100 m) and stableKey (~1 km) are rounded strings used to key recomputes so GPS jitter doesn't thrash them.
  • TransponderRecord — up/downlink low/high, mode, invert, type, baud, service. Computed: isLinear (needs both passbands and a transponder type or ≥5 kHz width), bandwidth, downlinkCenter/uplinkCenter, isTwoWay, and a human kind ("Linear (inverting)", "FM", "CW / Beacon", "Data (BPSK…)").
  • SatelliteRecord — identity, epoch, the six mean elements plus B*, a SatelliteKit Elements, its transponders, and an isManual flag. Computed: periodMinutes, semiMajorAxisKm, apogeeKm/perigeeKm, elementAgeDays.
  • LiveLook — one topocentric observation: az/el, range, range-rate, sub-point lat/lon/alt, sunlit, beta angle, footprint radius.
  • PredictedPass — AOS/TCA/LOS, max elevation, AOS/LOS azimuth, duration. SkyPoint — a timestamped az/el sample.
  • RadioCalibration (downlink/uplink Hz), StorePreferences (observer, favorites, min elevation, GP source, calibrations, location mode, useLocalTime, …), GPSourceKind, LocationMode, ManualSatelliteDefinition, LabOrbitDefinition.

Propagation engine

OrbitPredictor is the single wrapper over SatelliteKit. Each call builds a Satellite(elements:), asks it for TEME position/velocity at a Julian date, and derives the rest. Everything is pure and throwing; callers move heavy scans off-main with Task.detached.

FunctionWhat it computes
look(_:observer:at:)Full topocentric LiveLook — azimuth/elevation/range from topPosition, range-rate (including the observer's Earth-rotation velocity), the geodetic sub-point, sunlit test, beta angle and footprint radius.
predictPasses(…minElevation:maxCount:horizonDays:)A coarse 30 s rise/set scan refined by bisection to sub-second AOS/LOS, with TCA found by golden-section search. Handles a pass already in progress and continuously-visible high orbits.
currentOrNextPass, nextEventThe pass in progress or the next one (ignoring the display minimum so a track always has an arc); the next horizon event with its max elevation.
groundTrack, subpoint, skyPathA lat/lon/alt sample series over a window; the instantaneous sub-point; an az/el track for one pass (~20 s steps).
equatorCrossingsInterpolated latitude-zero crossings (ascending/descending) — the basis of the OSCARLOCATOR reference-orbit tables.
dopplerFrequencies(downlinkHz:uplinkHz:rangeRateKmS:…)One-way Doppler dials: with β = vrange/c, the receive dial uses f·(1−β) and the transmit dial f/(1−β), plus an optional calibration term folded into receive.
passbandFrequencies(_:offsetHz:)Linear-transponder tuning: an offset from center, walking the uplink the opposite way on an inverting transponder.
footprintRadius(altitudeKm:)The 0°-elevation surface radius, Re·acos(Re/(Re+h)). The Ground Track draws the matching geodesic circle as an explicit boundary polygon (see below).
betaAngle, isSunlitThe angle between the orbit-plane normal and the Sun unit vector; a cylindrical-shadow illumination test.
The Sun/Moon geometry uses standard Meeus-style low-precision series (good to arc-minutes) — appropriate for pass visibility, eclipse fraction and EME, and far cheaper than full ephemerides.

Decay & lifetime

OrbitDecayModel (in DeepParityEngine.swift) is a King-Hele style atmospheric-decay integrator. estimate(…) returns a lifetime in days and a DecayAnchor describing what it trusted: a measured decay rate (observed n-dot) where the elements support it, otherwise the fitted B*. It integrates the semi-major axis against an exponential atmosphere (banded reference densities and scale heights from ~100–1000 km), applies a King-Hele eccentricity correction (via modified Bessel functions), scales density by a low/mean/high solar-activity factor, and stops at re-entry altitude or a long-life cap. lifetimeFromArea(…) derives the ballistic coefficient from physical inputs (Cd·A/m) for a spacecraft still on the bench — the basis of the orbit-lifetime and debris-compliance bench tools.

Astronomy & feature math

FeatureEngine is the largest engine and backs most Analysis and Sky screens. Highlights:

  • Grids & VUCC. gridToLatLon/latLonToGrid4/latLonToGrid6 implement Maidenhead both ways; vuccGrids(lat,lon,tolerance) returns the 1–4 grids you may claim on a line or corner, treating a fix within ~6.1 m (the ARRL 20-ft GPS rule) of a boundary as on it.
  • Sun/Moon/planets. sunMoon and skyObjects give az/el, phase and illumination; planet positions come from a compact VSOP-style element set converted to geocentric RA/Dec then to horizon coordinates via local sidereal time.
  • Footprint sets. workableGrids/workableGridsNow/…AcrossNextPass enumerate the grids inside the footprint (an angular-distance test against a grid lattice); bestPassesForTarget finds passes where both your station and a target sit inside the footprint at once.
  • Analysis. equator crossings, Sun/Moon transits (disk-crossing detection with a coarse scan then refinement), orbital zones (South-Atlantic-Anomaly / radiation-belt dwell via a centered-dipole L-shell model), eclipse fraction, LTAN, conjunction screening (coarse then 1 s refinement), and an orbital-history analyzer that fits decay/precession trends from Space-Track GP series.
  • Space weather lives here as a small service that fetches NOAA SWPC (flux, planetary Kp/A) and the ham-community sunspot number (hamqsl, with NOAA fallback) in parallel and reduces them to a SpaceWeatherSnapshot.

FeatureCompletionEngine adds the radio and EME math: linkBudget (EIRP − FSPL − losses), the Doppler radioPlaybook (hold-RX or hold-TX rows across a pass), EME band analysis (Doppler, Faraday rotation, sky temperature, libration spread, path degradation vs. lunar distance) and satellite eclipse timelines. AstronomyParityEngine adds the aurora outlook (a Kp-driven auroral-boundary magnetic-latitude test), lunar occultations, planetary appulses, and solar/lunar eclipse detection with shadow ground tracks.

Planning engine

ParityPlanningEngine backs the Workable, Mutual, Rove and visible-pass screens. It exposes snapshot types (WorkableSetSnapshot of grids/states/DXCC, MutualWindowRecord, RovePassRecord, SatelliteLOSWindow, VisiblePassRecord, HorizonMask) and the functions that build them: workableNow/workableAcrossNextPass/workableHorizon, targetSearch, mutualWindows (times two stations both see a satellite), satelliteLOSWindows (a ray-sphere line-of-sight test between two satellites), visiblePasses (an optical-magnitude estimate applied when the satellite is sunlit, the Sun is well down, and elevation is adequate), and trim (clip a pass to a four-point interpolated horizon mask). US-state membership uses a bundled centroid table; DXCC membership uses the footprint against the DXCC roster.

Math & utilities

UtilityEngine holds the pieces shared by the calculators. SafeMathEvaluator is a hand-written lexer/parser/evaluator for the scientific calculator: infix expressions with correct precedence, SI metric-prefix literals (100k, 2.2n), the usual trig/hyperbolic/log/exp/factorial/nCr/nPr functions, physical constants (c, kb, Re, mu, g0, pi, e), and amateur-radio/orbit helpers (fspl, dop, wavelength↔frequency, dB conversions, SWR/return-loss, noise-figure↔temperature, orbital period/velocity/footprint, slant range, dish gain). GraphCalculatorEngine samples a function across a range for the graphing calculator (trace, roots, integral, CSV). An older lightweight TinyBasicEngine also lives here alongside the graphics-op types shared with the full interpreter.

Tiny BASIC & bench tools

DeepParityEngine.swift contains the full Tiny BASIC interpreter — CardSatTinyBasicEngine (the front-end and static helpers), BasicVM (the execution state machine: variables, string variables, named and anonymous arrays, FOR/GOSUB stacks, DATA pointer), BasicExpressionParser (a recursive-descent numeric/string parser with the documented precedence), and TinyBasicHostContext (the immutable bridge that exposes about 85 read-only variable names such as SATAZ, AOSIN, SFI, LSHELL; some exist only for CardSat compatibility and read 0). It tokenizes by splitting statements on colons and arguments on commas (respecting quotes and parentheses), dispatches statements by keyword, records drawing commands for the 240×135 display (drawn by the view after the run), sandboxes file I/O to a private directory, and bounds execution by statement count and wall-clock time. The dialect is documented end-to-end on the Tiny BASIC page.

The bench tools are data-driven: BenchTools.allTools is a list of ToolDefinitions (id, category, fields), and a compute function switches on the id to produce ToolResults. Categories include Antennas & feedline (yagi, quad, helix, coax, match), RF & measurement (attenuator, cascade, imd, exposure), Electronics & power (pll, thermal, crosssection), Terrestrial VHF/UHF (tropo, terrainLOS), Satellite & orbit (slant, kepler, footprint, orbitLifetime, debrisCompliance, deltaV, stateVector, orbitalThermal, linkMargin), and General (sciCalc, programmer, unitConverter, dxccLookup, gridConvert). Adding a calculator is a definition plus a case.

DXCC & geocoding

DXCCData holds the DXCC entity roster (DXCCEntity: prefix, name, representative lat/lon) and a search helper; DXCCNumericData holds the ARRL numeric entity codes and coordinates that Tiny BASIC addresses by number. The interesting logic is GeoEntityLookup, which turns a coordinate into a GeoLocationEntity (DXCC entity + primary/secondary subdivision):

  • lookup(latitude:longitude:) reverse-geocodes with CLGeocoder, resolves the DXCC entity from an ISO-3166 → DXCC map (US and GB are split on the administrative area for Alaska/Hawaii and the four UK home nations), and normalizes the subdivisions to the names LoTW/TQSL expect.
  • adifPrimary maps a US state name to its two-letter code. usSecondary applies a county-designator-first rule: a subdivision ending in "County/Parish/Borough/Census Area/Municipality" is a county (bare LoTW name); otherwise it is treated as independent-city territory.
  • Connecticut is special-cased: Core Location returns the new census "planning region," so a full town→legacy-county table resolves the county LoTW still expects. independentCityName handles the US independent cities — Virginia's (with "City" appended to the four that collide with a county — Fairfax City, Franklin City, Richmond City, Roanoke City), plus Baltimore, St. Louis and Carson City.

Data services

Services are thin and stateless where possible; the store owns caching and cadence.

  • GPService — fetches General Perturbations elements from the AMSAT daily bulletin, a CelesTrak group, or a custom URL, and parses OMM (JSON/XML/CSV) and classic TLE (with checksum validation) into SatelliteRecords via SatelliteKit Elements. It exposes the CelesTrak group list, a browser-style User-Agent, per-NORAD "extra" fetches for New Launches, and makeManualRecord for hand-entered elements.
  • TransponderService — downloads the SatNOGS transmitter database (per-NORAD or the whole set), keeps rows with a real downlink, and builds TransponderRecords keyed by NORAD id.
  • AO7Service — fits AMSAT status reports of AO-7's A/B mode to a periodic switch model (coarse then fine search, positive/negative report weighting), returning the current mode, the next switch time, and a confidence figure — windowed by the satellite's last eclipse exit so stale phase is ignored.
  • ActivationService & HamsatAlertService — read the hams.at upcoming-activations Atom feed (with a browser User-Agent) and compute mutual-visibility windows for "Can I work it?"; and post an activation via hams.at's authenticated POST /api/alerts. The posting client is split into pure request-building, validation and response-parsing behind a HamsatTransport seam, so it is unit-tested against a local mock of the hams.at server; the API key is stored in the Keychain.
  • QRZService — QRZ XML callsign lookup using the operator's subscription credentials (password from the Keychain).
  • AmsatStatusService — the AMSAT status API (summary, catalog and reports), catalog-name matching to the GP catalog, and attributed status submission, used by the AMSAT Status screen and the Home one-tap report card.
  • Space weather is fetched by the small service inside FeatureEngine described above.

Rig control (CAT)

The CAT/ group implements direct transceiver control (Doppler tuning). It is split into a data model, protocol codecs, transports, an orchestrator and its UI:

  • RigTypes.swift — the radio catalog (RadioCatalog of RadioSpecs ported from CardSat: CI-V addresses, bauds, full-duplex/RX-only/LAN flags, MAIN/SUB select bytes, sat-mode and tone sub-commands), the persisted CATConfig/RigSlot/CATTuning, the RigMode/RigFamily/RigRole/CATTransportKind enums, and the CTCSS tone tables (a 39-tone list plus the Kenwood-specific numberings). The config types use tolerant custom Codable (decode-if-present with defaults) so adding fields in a later release never fails to decode a saved setup.
  • CATCodec.swift — pure, stateless frame builders/parsers for every dialect: Icom CI-V (little-endian BCD frequency, mode, MAIN/SUB select, sat mode, CTCSS, 07 D2 band assignment, read/parse), Yaesu 5-byte binary (FT-847 SAT-RX/TX opcodes, FT-817 family, FT-100 little-endian, VR-5000, FT-736R), and Kenwood ASCII (TS base FA/FB/MD, the TS-2000/790 satellite-mode (SATL) entry/exit handshake with dual-control band select, and the TH-D74/D75 band-B FQ/MD/FO with fine-step handling). Narrow FM on FM birds is a mode/filter path (CI-V 06 05 <filter>) driven from the transponder mode. Being pure, they are unit-testable without hardware.
  • CATTransport.swift — the CATTransport abstraction and BLESerialTransport, a CoreBluetooth UART client (Nordic UART or a generic write+notify pair) that scans-and-matches the chosen peripheral by identifier and exposes async send / read. A BLEScanner backs the Settings device picker.
  • IcomNetwork.swift — IcomNetworkTransport, a byte-exact port of Icom's RS-BA1 UDP protocol (control + serial streams, the login/auth/ConnInfo handshake with the passcode cipher, a 100 ms idle/ping keepalive with a data watchdog, and CI-V tunneling), built on Network.framework. Transient path loss (.waiting) is ridden through rather than treated as a drop, so a brief Wi-Fi blip no longer forces a re-login; the audio stream re-establishes after a reconnect.
  • RigController.swift — a @MainActor ObservableObject that owns the configured radios and the tuning loop. It computes the corrected dials exactly as Home does (OrbitPredictor.dopplerFrequencies + per-satellite calibration + passband + transverter LO), applies FM/linear deadbands and a predictive lead, and routes each leg to the right radio and VFO. It also implements the One True Rule read-back: it reads the followed leg and folds an operator dial move into the passband offset so the other leg stays transponder-correct. The loop is driven by a DispatchSource timer on the main queue with an overlap guard, and all command pacing/reads use GCD timing — not a MainActor Task.sleep loop, which is unreliable on device and would freeze the UI. Config persists to its own UserDefaults key, decoupled from StorePreferences.
  • CATViews.swift — the Rig Control configuration screen (presented as a sheet from Settings so it can't wedge the split-view navigation) and the Home Rig control card (connect/disconnect, live dials, Doppler toggle), which tracks the Home transponder and passband selection.
iOS supports only Bluetooth LE here — generic Bluetooth Classic (SPP) adapters require MFi and cannot be opened. The RS-BA1 network path is implemented to the reverse-engineered spec and verified against real hardware where possible.

Rotator control

The Rotator/ group steers an az/el antenna rotator to follow the selected satellite. It mirrors the CAT design — data model, codecs, transports, an orchestrator and UI — and reuses CAT's BLE transport and network primitives:

  • RotatorTypes.swift — the RotatorProtocolKind enum (GS-232A/B, Easycomm I/II/III, SPID Rot2Prog, SAEBRTrack, rotctld, PstRotator, OZ9AAR URC, with network/TCP/default-port traits), the RotAzRange axis convention (0–360 / −180…+180 / 0–450° overlap), and the persisted RotatorConfig — the full set of CardSat options that apply on iOS (protocol, transport endpoint, pre-position lead, a tracking slew lead, 450° lookahead, alignment offsets, deadband, magnetic correction, park az/el, flip, minimum elevation, update rate). It uses the same tolerant custom Codable as the CAT config, in its own UserDefaults key.
  • RotatorCodec.swift — pure, stateless command builders and position parsers: GS-232 (W aaa eee), Easycomm I integer / II&III decimal (AZ… EL…), the SPID Rot2Prog 13-byte binary frame, SAEBRTrack's compact whole-degree AZnnnELnnn, rotctld (P az el / p / S), PstRotator's <PST><TRACK>az el</TRACK></PST> UDP command, and OZ9AAR URC's JSON ({"GOTO":[az,el]} / {"POLL"}). The GS-232/Easycomm/SPID/PstRotator builders are ported byte-for-byte from CardSat's rotator.cpp; SAEBRTrack and URC follow the OscarWatch reference. Each protocol applies its own final clamp.
  • RotatorNetwork.swift — RotatorNetworkTransport, a Network.framework client conforming to CAT's CATTransport so the controller reuses the same plumbing. It does TCP for rotctld and OZ9AAR URC, and UDP for PstRotator (binding the local source port to dest+1 as CardSat does), and awaits the send completion so a real socket error surfaces on the Home card instead of being silently dropped. Serial rotators (including SAEBRTrack) reuse CAT's BLESerialTransport.
  • RotatorController.swift — a @MainActor ObservableObject running the pointing loop on a DispatchSource timer (same GCD-timing discipline as the rig controller). Each tick computes the live look angle, then branches to track (applying alignment offsets, flip for overhead passes, the 450° overlap pre-commit and axis normalization, and optional magnetic-declination correction), pre-position to the AOS bearing within the lead window, or park. A deadband suppresses needless moves; on the fire-and-forget UDP path a short keep-alive resends to self-heal a dropped datagram, while reliable transports send only on real movement.
  • RotatorViews.swift — the Rotator configuration screen (presented as a sheet from Settings, like the CAT screen) with protocol, connection, pointing, alignment and park sections, and the Home Rotator card (connect/disconnect, commanded az/el, mode and transmit status). The card shares a ControlStatusHeader with the rig card for a consistent look.
The network protocols are validated end-to-end — PstRotator's UDP command against the documented spec, and rotctld against Hamlib's dummy backend (rotctld -m 1); OZ9AAR URC follows the documented TCP/JSON format. The serial protocols (GS-232, Easycomm, SPID, SAEBRTrack) are byte-faithful to their references and await on-hardware confirmation, as with the CAT serial radios. The Green Heron RT-21 Az/El is intentionally not offered — it needs two independent serial links (one per axis), which a single BLE adapter can't drive; reach it via rotctld.

Logging, audio & digital modes

These groups give OrbitDeck operating features beyond tracking. They reuse the CAT/rotator conventions (a controller + its own persistence, GCD timers, Home cards gated on configuration).

  • Log/ — the QSO log. QSOTypes (records with per-QSO upload flags, per-leg modes, DXCC, state and LoTW confirmation, plus tolerant-Codable config), QSOStore (JSON on disk, DXCC fill, the rate-limited QRZ name/state worker, ADIF import merging, uploads, and LogAwards for QSO/satellite/VUCC/WAS/DXCC totals), ADIF (import/export, hardened against hostile lengths and frequencies), Gzip (pure-Swift RFC-1952 via the Compression framework + a CRC-32), LoTW (on-device .tq8: SecPKCS12Import of the user's certificate, per-QSO SIGNDATA and the RSA-PKCS1v15-SHA1 signature via SecKeyCreateSignature, ported byte-for-byte from CardSat's validated implementation, incl. LoTWSatName normalization and the subdivision tables), Cloudlog (JSON API, the https/local-network URL policy and strict reply classification), and LogViews (Log screen, editor, settings, awards, PDF reports, Home quick-log card).
  • Log integrity. Files are written atomically. QSOStore.loadOrPreserve moves an unreadable file to <name>.corrupt-<UTC timestamp>.json before starting empty (and blocks writes for the session if it can't), and save failures surface as a banner. An upload marks only the QSOs whose uploaded fields still match what was sent (markUploaded), so an edit or QRZ fill during an upload is re-sent next time.
  • Audio/ — a CATTransport-style abstraction: AudioSource with USBAudioSource (AVAudioEngine over a class-compliant USB interface, or the built-in mic when a feature is set to Always) and IcomAudioSource (the RS-BA1 network audio stream), an AudioHub that tracks availability, health and the exclusive operating mode, remote voice, and AudioDSP (Goertzel, an arctan FM discriminator, a ring buffer).
  • Recording/ — PassRecorder streams the received audio to a compressed AAC .m4a via AVAudioFile, and records voice memos that log a QSO stub; the Home card + Log listing show them.
  • DigitalModes/ — SSTV/ (a generic segment-based decoder over the demodulated subcarrier, VIS auto-detect, its own gallery + a Photos export), and FT4Engine/FT4Views: full-duplex FT4 built on the vendored MIT ft8_lib (bridged to Swift) with PSKReporter reporting; the packet/APRS stack (AFSK 1200 and G3RUH 9600 modems, AX.25, KISS over BLE or TCP, APRS parsing, the pass log and the receive-only APRS-IS satgate); and the CW decoder, whose default engine is DeepCW: a Swift port of the reference pipeline (anti-aliased resampling to 3.2 kHz, STFT with noise-quantile log1p normalization, a 12 s window every second, blended CTC posteriors, greedy decoding) running the bundled Core ML model in float32 on CPU+GPU, with the classic demodulator kept as an option and still driving the pitch, speed and spectrum readouts. Every transmit path (FT4, Tune, packet, remote voice and the rigctld server) keys through the lease-based PTTAuthority in CAT/RigTypes.swift: one holder at a time, strict key/unkey ordering and a global key-time limit.

The CAT group also has a rigctld client transport (a Hamlib NET rigctl TCP client, so any Hamlib-supported radio can be driven), and the CAT and rotator groups each host a server (RigctldServer on TCP 4532, RotctldServer on TCP 4533) built on a shared HamlibLineServer. New clients wait for operator approval (NetworkServerApprovals: allow once / always / deny, 30 s timeout, denied in the background, loopback allowed), and VPN and cellular interfaces are refused.

FT4/SSTV, packet, the CW decoder, the Icom network-audio stream, rigctld and the BLE serial rotators are implemented to spec, with each flagged in its source header for on-air verification where it hasn't been. The pure-logic paths (ADIF/LoTW signing, gzip, Cloudlog reply parsing, packet framing, the DeepCW front end) are covered by unit tests.

Location

LocationProvider is a @MainActor ObservableObject wrapper over CLLocationManager that serves two independent consumers: the compass (which needs location fixes so Core Location can resolve true heading from magnetic) and the observer follow. startHeading/stopHeading and startFollowing/stopFollowing track those consumers separately so releasing one doesn't cut updates the other still needs; setPrecise switches between a battery-friendly ~100 m accuracy with a 50 m distance filter and full best-accuracy with no filter (used by the Grid Finder). It also offers opt-in reverse geocoding: with geocodeEnabled set, each fix is geocoded (throttled to ~1 km) and published as entity, which the Grid Finder reads. The shared "current location" follow that drives observer-relative screens is coalesced to ~1 Hz in RootView so live screens don't re-render faster than once per second.

Exports

ExportService renders PDFs with Core Graphics and writes text formats. PDFs include the pass schedule, the OSCARLOCATOR reference-orbit tables (equator crossings, skipping geosynchronous birds), the illumination raster, the multi-day progression, the two-site mutual-windows report (paired polar sky plots), and a comprehensive per-satellite analysis sheet. Text exports include pass CSV (full and compact), stepped listings, two-site comparisons, merged favorites, an ICS calendar (with optional lead-time alarms), and JSON. XLSXExportService is a small, dependency-free Office-Open-XML writer that emits a valid .xlsx (a stored ZIP of the required XML parts, a bold frozen header row, and an auto-filter) so spreadsheets export without a third-party library. Everything is shared through the standard iOS share sheet.

Notifications

PassAlarmService schedules a local UNUserNotification at AOS minus the chosen lead time, with a deterministic id per satellite+pass so it can be queried and canceled; it throws if the pass is too imminent and requests authorization lazily the first time you schedule one. The NotificationRouter (in RootView.swift) is the UNUserNotificationCenterDelegate: tapping a pass reminder sets a flag that RootView observes to switch the selection to Home.

RootView is a NavigationSplitView (balanced style): a sidebar of grouped destinations and a detail pane. Every screen is a case of the OrbitDestination enum — each with a title, an SF Symbol, and a usesSelectedSatellite flag — organized into the groups LIVE, PASSES, ANALYSIS, OPERATING TOOLS, SKY & SPACE, and CATALOG & CONFIGURATION. destinationView(_:) maps a case to its view. Notable details: reading-oriented screens are capped to ~720 pt and centered on iPad while full-bleed screens (globe, radar, ground track) use the whole pane; a transient nil selection resolves to the last real screen so the detail never flashes Home; the scene-phase handler refreshes stale space weather and catalogs on foreground and releases GPS on background; and an idle-timer hook keeps the screen awake only while Home is showing and the app is active.

Design system & shared UI

AppTheme defines ODTheme (the dark palette — background, panel, accent, good, warning, muted, grid, map colors), the odPanel() card modifier and ODFieldStyle text-field style, and the two workhorse layout views MetricRow (label + right-aligned monospaced value, scaled to avoid wrapping) and SectionCard (titled panel).

Components holds the cross-cutting pieces:

  • ODFormat — all date/number formatting. A global useLocalTime flag (mirrored from the store) switches every time between UTC and the device zone; local formatters honor the device 12/24-hour setting while UTC stays 24-hour, and primaryClock/secondaryClock render a time in the chosen zone and the other zone for the dual clocks in pass lists.
  • Binding.snapping(to:within:) — a center-detent for sliders whose neutral is the middle (passband, calibration, node longitude, time-freeze).
  • PolarSkyPlot — a Canvas polar sky chart (elevation rings, compass rose, track, AOS/LOS and live direction-of-travel arrows, optional compass-up orientation).
  • CurrentLocationEntityInfo, SelectedSatelliteHeader, PassAlarmButton/PassAlarmUnavailable, the satellite switcher/picker, and GeoLocationEntity.

Live-update patterns

Several patterns recur across the live screens and are worth understanding before editing them:

  • TimelineView as the clock. Live screens refresh with TimelineView(.periodic(from:by:)), anchored to a stable date so frequent re-renders don't re-fire it faster than 1 Hz. Ad-hoc Task.sleep loops proved unreliable on device, so the codebase standardizes on TimelineView.
  • Render-time memoization. Occasional-but-expensive work (e.g. the Home sky-track arc) is computed inside the TimelineView and cached in a reference held in @State, recomputed only when its key changes — so it always draws without depending on a cancelable .task that a split-view transition might kill.
  • Stable location keys. Reload keys round the observer to coarseKey (~100 m) or stableKey (~1 km) so a jittering GPS fix doesn't restart multi-second recomputes (pass lists, the Daily Schedule).
  • Generation tokens over cancellation. The streaming Daily Schedule supersedes an in-flight load with a monotonically increasing token rather than Task.isCancelled, so a spurious task cancellation during a navigation transition can't leave it stuck on "Computing…".
  • Last-writer-wins. Background fetches publish their result even if the parent task was canceled, so a coarse location update can't strand a list on its loading state.

Feature-screen map

Where to find each screen:

FileScreens
HomeView.swiftHome (live track with the memoized arc, transponder/Doppler cards with passband + calibration sliders, the CAT rig-control and rotator cards, one-tap AMSAT status reporting, fleet dashboard) and the Grid Finder (VUCC compass dials + proximity map).
GroundTrackView.swiftGround Track — a MapKit map with the sub-point path, a live heading marker, and the geodesic footprint drawn as an explicit 0°-elevation boundary polygon (walked by bearing from the sub-point) instead of a projected MapCircle.
PassesView.swiftNext Passes (quality-scored list, pass-detail sheet) and the Daily Schedule (per-satellite streaming, day grouping, pin-to-now).
TrackView, SkyRadarView, OrbitalAnalysisView, IlluminationView, PassDetailView, TenDayView, RadioView, SatellitesView, SettingsViewThe standalone screens (real-time polar plot; all-sky radar; orbital analysis; illumination; pass detail; pass progression; the Radio/Doppler screen; the catalog; and Settings/About/Calibrations).
FeatureViews.swiftWorkable, Mutual windows, Sun/Moon, Sky Map, Celestial, EME, Transits, Orbital Zones, Astronomy, Orbital History, Space Wx, MUF, Propagation, New Launches, Sites, Activations/QRZ, AMSAT Status, Sky at a Glance, Planning, Conjunctions, and the DX Doppler sheet.
AdvancedFeatureViews.swiftOSCARLOCATOR Sim (live/QTH projections, A/B reference-orbit comparison), Reference Orbits, and Exports.
DeepParityViews.swift, UtilityFeatureViews.swiftTools, the scientific and graphing calculators, Tiny BASIC, Learn, References, and the 3D globe.
CAT/CATViews.swiftRig Control (CAT) configuration sheet and the Home rig-control card. Engine, transports and codecs live alongside it in the CAT/ group (see Rig control).
Rotator/RotatorViews.swiftRotator control configuration sheet and the Home rotator card. Codec, transport and controller live alongside it in the Rotator/ group (see Rotator control).
Log/LogViews.swiftThe Log screen (QSOs + pass recordings), QSO editor, Log settings and the Home quick-log card (see Logging).
DigitalModes/SSTV/SSTVViews.swift, DigitalModes/FT4Views.swift, Recording/RecordingViews.swiftThe SSTV Images gallery + viewer, the Home SSTV / FT4 / pass-recording cards (all gated on audio availability).

Building & contributing

  • Clone the repo and open OrbitDeckIOS.xcodeproj in a current Xcode (the app target uses Swift 6 language mode).
  • SatelliteKit is a Swift Package dependency (github.com/gavineadie/SatelliteKit); Xcode resolves it on first open. Build and run the OrbitDeckIOS scheme on a device or simulator; it also builds the OrbitDeckWidgets Live Activity extension.
  • Bridging header and ft8_lib. OrbitDeckIOS/OrbitDeck-Bridging-Header.h imports ft8_lib's <ft8/…> and <common/…> headers, so the target's Header Search Paths must include $(SRCROOT)/OrbitDeckIOS/DigitalModes/ft8_lib. The app target and the OrbitDeckIOSTests target both carry that setting (the test target builds against the app's bridging header, so it needs the same path).
  • DeepCW model. DigitalModes/DeepCW/DeepCW.mlpackage is in the app target's Compile Sources phase, so Xcode compiles it into a .mlmodelc in the app bundle. If it's missing, the CW decoder falls back to the classic engine. To rebuild it from the upstream ONNX model, see tools/deepcw/README.md.
  • The Info.plist is mostly generated from build settings (INFOPLIST_KEY_*, including the permission purpose strings); OrbitDeckIOS/Info.plist adds the background modes, the orbitdeck:// URL scheme, the background-task identifier and Files-app sharing. The launch screen uses a LaunchBackground color in the asset catalog.
  • Location, compass, Bluetooth, audio interfaces and reverse-geocoding features need a real device (the Simulator has no magnetometer, no USB audio and limited geocoding).
  • The app target uses explicit file references (not a synchronized group), so a brand-new source file must be added to the target in Xcode; small additions often fit naturally into an existing file. OrbitDeckWidgets/ and OrbitDeckIOSTests/ are synchronized folders. Don't edit project.pbxproj by hand.
  • The OrbitDeckIOSTests target (Swift Testing, 19 files; its deployment target is iOS 26.5, so run it on a current simulator) covers the hams.at posting client against a local mock server, CAT features and the PTT authority, server client approval and rotator retry, FT4 message parsing, sequencing and Tune gating, the packet modems and APRS parsing, the classic CW decoder and DeepCW (front end vs. the Python prototype, resampler, stitcher, end-to-end copy of keyed CW), QSO logging and log integrity (ADIF hardening, the Cloudlog reply and URL policy, upload marking, corrupt-file preservation), catalog robustness, the Live Activity timeline, and display and unit formatting.
  • Use American English in code comments, UI text, commit messages and documentation (Apple API names keep their own spelling).

License & credits

OrbitDeck for iOS is released under the MIT License (see LICENSE): you may use, copy, modify and distribute it, including in other projects, provided the copyright and license notice are kept; it comes with no warranty. OrbitDeck is distributed on the App Store, so contributions must be compatible with MIT. GPL/AGPL projects are used as behavioral references only, never as a source of code. OrbitDeck is written and maintained by Paul Stoetzer, N8HM.

Third-party code and data, credited in THIRD_PARTY_NOTICES.md and in the app under Settings → About → Acknowledgments:

ComponentUsed forLicense
ft8_lib (Kārlis Goba)FT4 encoding and decoding (vendored in DigitalModes/ft8_lib/)MIT
DeepCW (e04)Neural-network CW decoding; the model is converted to Core ML and the reference pipeline ported to Swift (license in DigitalModes/DeepCW/LICENSE)MIT
SatelliteKit (Gavin Eadie)SGP4/SDP4 orbit propagation (Swift package)MIT
d3-celestial (Olaf Frohn)Constellation lines on the sky chartsBSD 3-Clause
Yale Bright Star Catalog (BSC5)Star positions and magnitudes on the sky chartsPublic domain
Natural EarthCoastlines and boundary outlines on the mapsPublic domain
Open-MeteoWeather forecasts (weather data by Open-Meteo.com)CC BY 4.0

If you find OrbitDeck useful, please consider supporting AMSAT, which builds and launches the satellites it tracks.

Contributors

Thank you to everyone whose pull requests have been merged into OrbitDeck:

  • Filip Melik (@filipmelik)
    • #5 — Next Passes screen interaction fixes
    • #8 — Home screen fixes: stale data refreshed on return from the background, and in-progress passes moved to Overhead Now with their LOS time
    • #9 — Native Bluetooth CAT for the IC-705 and IC-905 (sign-in protocol behavior per K7MDL2's IC-705 BLE example)

Contributions are welcome — open an issue or a pull request on GitHub.