SimTX API/Satellites

SimTX satellites are user-launched stations of kind SATELLITE. An account designs one (orbit, attitude, antennas and rigs), launches it through the 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

State	Meaning
ACTIVE	Launched and in orbit. Usable for sessions; listed if PUBLIC.
DEORBITING	The deorbit burn has fired. The satellite is fully usable on its falling orbit until it reenters.
DEORBITED	Reentered. Sessions are refused with STATION_INACTIVE. The record remains until the owner deletes it.

• Launch. POST /api/v1/satellites 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 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.
• Antennas on satellites are modelled in free space. The circularly polarised types TURNSTILE and HELIX and the MONOPOLE are intended for them; a NEC deck must not contain a GN card.

Satellites on the wire

• The station list contains every ACTIVE or DEORBITING PUBLIC satellite, with or without sessions. core.location is the sub-satellite point at captured_at_ms, and core.orbit and core.attitude describe its motion. LiveSession.location of a session on the satellite moves with it.
• A session bound to a satellite gets the elements in SessionStatus.station.core.orbit, and UPDATED statuses when they change or when the deorbit burn fires. See Session status.
• EphemerisRequest returns positions over a time window, and PassPredictionRequest returns passes over an observer. Both are control requests and need the server features ephemeris and passes.
• The account service lists PUBLIC satellites without authentication at GET /api/v1/satellites. See 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 (ServerHello.simulation_time_ms, or a recent StationList.captured_at_ms) as "now", not the local clock.

Orbit model

Every satellite uses the model simtx-j2-v1: 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 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₀, all at the epoch.

μ    = 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

Secular rates

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)

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

Position and velocity

1. Solve Kepler's equation M = E − e sin E by Newton's method, starting from E₀ = M + e sin M (or π when e > 0.8), to |ΔE| < 10⁻¹⁴ in at most 16 iterations.
2. The perifocal position is r = (a (cos E − e), a η sin E, 0).
3. Rotate it by R3(Ω) R1(i) R3(ω) into the model's inertial frame. The model has no precession or nutation.
4. The velocity is the derivative of the perifocal position with dE/dt = (dM/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:

θ    = 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

Latitude, longitude and height are taken on the 6,371 km sphere, which is also the frame of EphemerisSample x, y and z.

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 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_L = −r̂ (nadir), y_L = −ĥ (ĥ = r × v normalised), x_L = y_L × z_L (along-track; the velocity direction on circular orbits).

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

A rotation by ψ about z_b 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 HELIX, TURNSTILE, MONOPOLE 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 simtx-j2-v1;
• 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⁻⁵ 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 EphemerisRequest asks for a satellite's position from from_ms to to_ms every step_seconds, at most 3,600 samples. The 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 Error NOT_FOUND. For a deorbiting satellite the samples stop at its reentry.

Passes

A PassPredictionRequest asks when a satellite is above min_elevation_deg 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 position. Each 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. POST /api/v1/stations/{id}/deorbit/preview returns the 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. POST /api/v1/stations/{id}/deorbit 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 DEORBITING.
• Falling. While deorbiting, the satellite works normally on its falling orbit: tickets, sessions, the station list, ephemerides and passes. Sessions bound to it receive SessionStatus UPDATED with UPDATE_REASON_DEORBIT_SCHEDULED and the new elements.
• Reentry. The satellite reenters at reentry_at_ms, the first time after the burn that its height drops below 80 km, above reentry_point. The servers then end its sessions with ENDED and the reason Satellite burned up on reentry, and the account service marks it DEORBITED.
• Clients stop drawing the satellite at reentry_at_ms and cut ground tracks there. They draw the fall from the post-burn elements and never re-plan the burn themselves.

Typical results:

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.