Editing SimTX API/Satellites

{{SimTX API navigation}}
SimTX satellites are '''user-launched''' [[SimTX API/Stations|stations]] of kind <code>SATELLITE</code>. An account designs one (orbit, attitude, antennas and rigs), launches it through the [[SimTX API/Station endpoints|account service]], and from then on any number of sessions can transmit from it (a downlink) or receive on it (the uplink) while it moves. There are no real or system satellites; every satellite belongs to an account.

== Life cycle ==
{| class="wikitable"
! State !! Meaning
|-
| <code>ACTIVE</code> || Launched and in orbit. Usable for sessions; listed if PUBLIC.
|-
| <code>DEORBITING</code> || The deorbit burn has fired. The satellite is fully usable on its falling orbit until it reenters.
|-
| <code>DEORBITED</code> || Reentered. Sessions are refused with <code>STATION_INACTIVE</code>. The record remains until the owner deletes it.
|}

* '''Launch.''' <code>POST /api/v1/satellites</code> with the name, callsign, visibility, limits, orbit (without epoch), attitude, 1 to 4 antennas and up to 8 rigs. The account service sets the orbit epoch to the launch instant. See [[SimTX API/Station endpoints#Launching a satellite|Station endpoints]].
* '''Sealed.''' After launch only the name, callsign, visibility and limits can change. The orbit, attitude, antennas and rigs cannot; to change them, deorbit the satellite and launch another.
* '''Deorbit.''' A retrograde burn, not a deletion, and it cannot be undone. See [[#Deorbit|Deorbit]].
* '''Antennas''' on satellites are modelled in free space. The circularly polarised types <code>TURNSTILE</code> and <code>HELIX</code> and the <code>MONOPOLE</code> are intended for them; a NEC deck must not contain a <code>GN</code> card.

== Satellites on the wire ==
* The [[SimTX API/Packets/StationList|station list]] contains every ACTIVE or DEORBITING PUBLIC satellite, with or without sessions. <code>core.location</code> is the sub-satellite point at <code>captured_at_ms</code>, and <code>core.orbit</code> and <code>core.attitude</code> describe its motion. <code>LiveSession.location</code> of a session on the satellite moves with it.
* A session bound to a satellite gets the elements in <code>SessionStatus.station.core.orbit</code>, and <code>UPDATED</code> statuses when they change or when the deorbit burn fires. See [[SimTX API/Session status#Satellites|Session status]].
* [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] returns positions over a time window, and [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] returns passes over an observer. Both are control requests and need the server features <code>ephemeris</code> and <code>passes</code>.
* The account service lists PUBLIC satellites without authentication at <code>GET /api/v1/satellites</code>. See [[SimTX API/Public endpoints#Public satellites|Public endpoints]].

Clients may propagate the elements locally to draw satellites, using the model below, or ask the server. '''The server is authoritative.''' Use the server's simulation clock (<code>ServerHello.simulation_time_ms</code>, or a recent <code>StationList.captured_at_ms</code>) as "now", not the local clock.

== Orbit model ==
Every satellite uses the model <code>simtx-j2-v1</code>: mean Keplerian elements with the secular rates caused by the Earth's oblateness (J2), and nothing else. There are no short-period terms, no drag and no decay; a satellite stays in its orbit until its owner deorbits it.

=== Elements and constants ===
The [[SimTX API/Data types#OrbitalElements|OrbitalElements]] are the mean semi-major axis ''a'', eccentricity ''e'', inclination ''i'', right ascension of the ascending node Ω, argument of perigee ω and mean anomaly ''M''<sub>0</sub>, all at the epoch.

<syntaxhighlight lang="text">
μ    = 398600.4418 km³/s²       gravitational parameter
J2   = 1.08262668e-3
R_J2 = 6378.137 km               reference radius for J2
R    = 6371.0 km                 sphere for heights, latitude, longitude and look angles
</syntaxhighlight>

=== Secular rates ===
<syntaxhighlight lang="text">
n0 = √(μ / a³)          p = a (1 − e²)          η = √(1 − e²)          k = 1.5 J2 (R_J2 / p)²

dΩ/dt = −k n0 cos i
dω/dt =  ½ k n0 (5 cos² i − 1)
dM/dt =  n0 (1 + ½ k η (3 cos² i − 1))          period = 2π / (dM/dt)
</syntaxhighlight>

The three angles grow linearly with Δt = t − epoch.

=== Position and velocity ===
# Solve Kepler's equation ''M'' = ''E'' − ''e'' sin ''E'' by Newton's method, starting from ''E''<sub>0</sub> = ''M'' + ''e'' sin ''M'' (or π when ''e'' > 0.8), to |Δ''E''| < 10<sup>−14</sup> in at most 16 iterations.
# The perifocal position is ''r'' = (''a'' (cos ''E'' − ''e''), ''a'' η sin ''E'', 0).
# Rotate it by R3(Ω) R1(''i'') R3(ω) into the model's inertial frame. The model has no precession or nutation.
# The velocity is the derivative of the perifocal position with d''E''/dt = (d''M''/dt) / (1 − ''e'' cos ''E''), rotated the same way, plus (dΩ/dt) ẑ × ''r'' plus (dω/dt) ĥ × ''r'', where ĥ is the orbit normal.

=== Earth-fixed coordinates ===
The inertial frame is turned into Earth-fixed (ECEF) coordinates by the Earth Rotation Angle, using UTC as UT1:

<syntaxhighlight lang="text">
θ    = 2π (frac(Du) + 0.7790572732640 + 0.00273781191135448 Du),    Du = JD(UTC) − 2451545.0
r_ecef = R3(θ) r
v_ecef = R3(θ) v − ω_E × r_ecef,                                      ω_E = 2π × 1.00273781191135448 / 86400 rad/s
</syntaxhighlight>

Latitude, longitude and height are taken on the 6,371 km sphere, which is also the frame of [[SimTX API/Packets/EphemerisResponse|EphemerisSample]] <code>x</code>, <code>y</code> and <code>z</code>.

=== Look angles and Doppler ===
Look angles are computed in the observer's topocentric east-north-up frame on the sphere: azimuth from north through east, and '''geometric''' elevation (refraction is left to the propagation model). The range rate is positive when the satellite recedes, and the Doppler shift is −''f'' × (range rate) / ''c''.

=== Attitude ===
The [[SimTX API/Data types#Attitude|Attitude]] decides where a satellite's antennas point. It is defined against the orbiting (LVLH) frame built from the inertial position ''r'' and velocity ''v'':
* z<sub>L</sub> = −r̂ (nadir), y<sub>L</sub> = −ĥ (ĥ = ''r'' × ''v'' normalised), x<sub>L</sub> = y<sub>L</sub> × z<sub>L</sub> (along-track; the velocity direction on circular orbits).

{| class="wikitable"
! Mode !! Body axes
|-
| <code>nadir</code> (yaw) || The LVLH frame rotated by the yaw angle about z<sub>b</sub>. No mode set means nadir with yaw 0.
|-
| <code>inertial</code> (α, δ, roll) || z<sub>b</sub> = (cos δ cos α, cos δ sin α, sin δ) in the inertial frame. At roll 0, x<sub>b</sub> = (−sin α, cos α, 0), towards increasing right ascension, and y<sub>b</sub> = z<sub>b</sub> × x<sub>b</sub>, towards the celestial north pole. Roll rotates about z<sub>b</sub>.
|-
| <code>spin</code> (axis, rpm, φ<sub>0</sub>) || z<sub>b</sub> along the named axis: <code>ORBIT_NORMAL</code> z = +ĥ, x = along-track, y = nadir; <code>NADIR</code> z = −r̂, x = along-track, y = −ĥ; <code>VELOCITY</code> z = along-track, x = nadir, y = +ĥ. The body then turns about z<sub>b</sub> by φ = φ<sub>0</sub> + 2π (rpm / 60) Δt, relative to the orbiting frame.
|}

A rotation by ψ about z<sub>b</sub> maps x to cos ψ x + sin ψ y and y to −sin ψ x + cos ψ y. Every axis is finally rotated into Earth-fixed coordinates by R3(θ). Antenna boresight is the body +z axis for <code>HELIX</code>, <code>TURNSTILE</code>, <code>MONOPOLE</code> and NEC decks; Yagi booms (+y in the template) are mapped to +z.

=== Validation ===
The account service accepts an orbit only when:
* the model is <code>simtx-j2-v1</code>;
* the perigee ''a'' (1 − ''e'') − ''R'' is at least 200 km and the apogee ''a'' (1 + ''e'') − ''R'' at most 40,000 km above the 6,371 km sphere, which limits ''e'' to about 0.752;
* 0 ≤ ''e'' < 1, 0 ≤ ''i'' ≤ 180°, all angles finite;
* a spin rate, if any, is 0 to 60 rpm.

=== Accuracy ===
An implementation that agrees with the server to 1 cm in position, 10<sup>−5</sup> m/s in velocity and 0.01 Hz in Doppler at 437.8 MHz, over intervals of up to ten years, draws satellites where the server simulates them.

== Ephemerides ==
An [[SimTX API/Packets/EphemerisRequest|EphemerisRequest]] asks for a satellite's position from <code>from_ms</code> to <code>to_ms</code> every <code>step_seconds</code>, at most 3,600 samples. The [[SimTX API/Packets/EphemerisResponse|EphemerisResponse]] gives, for each sample, the sub-satellite latitude and longitude, the height above the sphere and the Earth-fixed position. The satellite must be PUBLIC or the account's own; otherwise the answer is [[SimTX API/Packets/Error|Error]] <code>NOT_FOUND</code>. For a deorbiting satellite the samples stop at its reentry.

== Passes ==
A [[SimTX API/Packets/PassPredictionRequest|PassPredictionRequest]] asks when a satellite is above <code>min_elevation_deg</code> for an observer, within a window of at most 7 days. The observer is a ground station with a live session on that server (PUBLIC or the account's own) or an arbitrary [[SimTX API/Data types#GeoPoint|position]]. Each [[SimTX API/Packets/PassPredictionResponse|Pass]] gives the times of acquisition (AOS), closest approach (TCA) and loss of signal (LOS), the maximum elevation, the azimuths at AOS and LOS and, when a frequency was given, the largest Doppler shift.

AOS, TCA and LOS are given to 1 ms and are accurate to about 0.2 s; short grazing passes are included. Passes that overlap the window are clipped to it: an always-visible geostationary satellite gives one window-long pass, a never-visible one none.

== Deorbit ==
Deorbiting is a retrograde burn, not a deletion, and it cannot be undone.
* '''Preview.''' <code>POST /api/v1/stations/{id}/deorbit/preview</code> returns the [[SimTX API/Data types#Deorbit|deorbit]] that a burn fired now would produce (burn time, reentry time and place, delta-v, and the post-burn orbit) without changing anything. Use it to confirm with the user.
* '''Burn.''' <code>POST /api/v1/stations/{id}/deorbit</code> fires it. The burn takes the satellite's state at the burn time and lowers its speed along the velocity vector until the new orbit's perigee is 100 km below the surface. Position is continuous; the velocity change is the burn. The stored orbit is replaced by the post-burn elements (epoch = burn time) and the satellite becomes <code>DEORBITING</code>.
* '''Falling.''' While deorbiting, the satellite works normally on its falling orbit: tickets, sessions, the station list, ephemerides and passes. Sessions bound to it receive [[SimTX API/Packets/SessionStatus|SessionStatus]] <code>UPDATED</code> with <code>UPDATE_REASON_DEORBIT_SCHEDULED</code> and the new elements.
* '''Reentry.''' The satellite reenters at <code>reentry_at_ms</code>, the first time after the burn that its height drops below 80 km, above <code>reentry_point</code>. The servers then end its sessions with <code>ENDED</code> and the reason ''Satellite burned up on reentry'', and the account service marks it <code>DEORBITED</code>.
* '''Clients''' stop drawing the satellite at <code>reentry_at_ms</code> and cut ground tracks there. They draw the fall from the post-burn elements and never re-plan the burn themselves.

Typical results:

{| class="wikitable"
! Orbit !! Delta-v !! Time to reentry
|-
| LEO 550 km || 189 m/s || 29 min
|-
| Geostationary || 1,506 m/s || 5.15 h
|-
| Molniya, burn at apogee || 62 m/s || 5.8 h
|-
| Molniya, burn at perigee || 2,614 m/s || 29 min
|}

Deorbiting satellites count towards the owner's satellite quota until they reenter. A deorbited satellite can then be deleted.

{{SimTX API navbox}}
[[Category:SimTX API]]