Data Connectors#
Connectors retrieve external facts and preserve provenance. They do not contain performance analytics logic.
See Free spacecraft and PV research APIs for the free NTRS, DISCOS, Zenodo, Dataverse, Horizons, PDS, PSA and DONKI APIs, including access requirements, original-file downloads and reproducible query snapshots.
Current sources#
OrbitalPV contains initial adapters for:
CelesTrak — public orbital elements;
Space-Track — authenticated catalog access;
NASA SSCWeb — spacecraft ephemeris services;
NASA NAIF — SPICE kernels;
NASA CDAWeb/HAPI — heliophysics time series;
NOAA SWPC — space-weather context;
SatNOGS DB — satellite metadata and mission-dependent telemetry;
BIRDS EPS — open panel and battery telemetry;
Flying Laptop / DaRUS — calibrated on-orbit solar-array voltage and current;
OPS-SAT-AD — original annotated photodiode and magnetometer measurements;
LASP LISIRD — measured total and spectral solar irradiance;
Earth Search Sentinel-2 — ground imagery, spectral bands and scene classification;
OpenStreetMap / Overpass — raw solar and wind installation features.
See Ground satellite imagery and renewable-energy features for image retrieval and the relationship to Dunnett et al. (2020), including which inputs the paper actually uses.
The NOAA SWPC connector also normalizes measured GOES integral proton and electron flux. SatNOGS metadata is public, but its telemetry endpoint currently requires authentication; it is not an anonymous real-data example.
Real BIRDS EPS telemetry#
OrbitalPV can retrieve the public BIRDS Electrical Power System dataset directly from the upstream BIRDSOpenSource repository. Install the workbook reader and plotting dependencies to run the gallery example:
pip install -U "orbital-pv[excel,examples]>=0.4.2"
Use the public API to download a workbook once and reuse it locally:
from pathlib import Path
import orbitalpv as opv
workbook = Path("data/birds/TSURU.xlsx")
if workbook.exists():
telemetry = opv.load_birds_eps_workbook(workbook, campaign_year=2021)
else:
telemetry = opv.fetch_birds_eps(
"TSURU", workbook, campaign_year=2021
)
fetch_birds_eps preserves the original workbook locally and returns
normalized panel-level telemetry with timestamp, panel identifier, voltage,
current and temperature when available. load_birds_eps_workbook reads an
existing workbook without another network request. Both preserve the source
sheet so each measurement remains associated with its campaign.
Available measurements#
The expanded example uses all four spacecraft. The following counts describe
the upstream workbooks at commit
67ad4435c5329abde65afc16e30d725cd5f2653c after filtering nonnumeric time
and missing voltage/current values:
Satellite |
Flight campaigns |
Measurement times |
Panel observations |
|---|---|---|---|
RAAVANA |
2 |
2,159 |
10,795 |
UGUISU |
3 |
3,260 |
16,300 |
NEPALISAT |
3 |
3,040 |
15,200 |
TSURU |
40 |
23,266 |
116,330 |
Total |
48 |
31,725 |
158,625 |
A measurement time is counted within its spacecraft and campaign; each has
five panel observations. The total therefore does not describe 158,625 unique
timestamps. TSURU’s Test1 w batt and Test2 wo batt sheets are excluded
from flight analysis. The workbooks contain separate measurement sessions,
not continuous coverage between the first and last campaign dates.
Campaign dates and elapsed time#
RAAVANA contains two campaigns, on 13 February and 11 March 2021, with 1,079 and 1,080 measurements respectively at five-second intervals. Plotting each campaign against elapsed minutes exposes these measurements instead of compressing them into two clusters on a month-scale date axis.
Most TSURU sheets name a month and day without a year; the last two dated
sheets explicitly name January 2022. campaign_year=2021 supplies the
missing year for the earlier sheets while preserving years already present.
This is an explicit inference from the workbook sequence and TSURU’s
14 March 2021 deployment, not a year provided in those sheet names. With
this choice, its 40 flight campaigns span 28 March 2021 to 24 January 2022.
Campaign dates must be sorted because workbook sheet order is not always
chronological.
Important
Numeric Time Stamp values are elapsed seconds within a campaign.
The normalized timestamp combines the campaign date at midnight with
those elapsed seconds. Midnight is a date anchor; the workbook does not
provide the actual UTC start time. The timezone-aware result must not
be used as a precise UTC measurement time for orbit, Sun-position or
eclipse alignment without an independently established start time.
The connector preserves the recorded elapsed intervals. For example, TSURU contains intervals of 10, 10.6 and 11.3 seconds, so replacing them all with a nominal ten-second grid would alter the source measurements.
Analysis walkthrough and attribution#
The dataset is real on-orbit telemetry from four 1U CubeSats and is published by Jara and Lepcha (2022), DOI 10.17632/8kp25ycf63.1, under CC BY 4.0. Retain the dataset attribution when sharing derived data. The associated article, Jara et al. (2022), documents the measurement fields and collection procedure. It reports panel failures in RAAVANA and UGUISU, but these exploratory plots do not reproduce expert fault labels or establish a degradation rate.
See the executable Real BIRDS CubeSat solar-panel telemetry walkthrough for the four-spacecraft overview, full-resolution RAAVANA campaign plots, five-minute power envelopes within each campaign, and TSURU’s 40-campaign history. Five-minute envelopes summarize real samples within each session; they do not create new measurement campaigns or fill gaps.
Primary sources:
Additional measured-data workflows#
Install the current public API and plotting support:
python -m pip install -U "orbital-pv[excel,examples]>=0.5.0"
These are separate observations with different physical meanings. An array’s electrical measurements, an irradiance instrument’s input measurements, and particle-environment measurements are not interchangeable.
Source |
Public connector |
Measured example |
|---|---|---|
Flying Laptop |
|
|
OPS-SAT-AD v2 |
|
|
TSIS-1 and SORCE TIM |
|
|
TSIS-1 SIM |
|
|
NOAA GOES |
|
Flying Laptop: actual array voltage and current#
The University of Stuttgart publishes monthly archives under CC BY 4.0, DOI 10.18419/darus-451, with a separate packet and units description. The connector reads electrical packet 4900 directly from the compressed archive, without extracting archive paths. It validates downloads against the provider’s catalog checksum and records a SHA-256 provenance sidecar.
import orbitalpv as opv
power = opv.fetch_flying_laptop_power(
"2018-02", "data/FLP_TM_HK_2018-02.tar.bz2",
time_min="2018-02-01", time_max="2018-02-02",
)
# Offline reuse of the complete downloaded month:
month = opv.load_flying_laptop_power("data/FLP_TM_HK_2018-02.tar.bz2")
February 2018 contains 75,097 packet timestamps and 300,388 array observations.
The right, left, center and onboard experimental test array stay distinct.
Voltage is in V and current in A; power_w is calculated as V times I.
The Unix-millisecond timestamps represent UTC packet generation, with up to
400 ms difference from sensor acquisition documented by the provider. Time
filters use an inclusive start and exclusive end. The gallery shows monthly
coverage, native voltage/current/power, and daily upper envelopes.
OPS-SAT: original sensor signals and annotations#
The OPSSAT-AD v2 release supplies
303,493 original measurements in 2,123 segments from nine channels. The
connector downloads segments.csv rather than the extracted-feature table,
pins the version and SHA-256, and preserves channel, segment, expert annotation
and the provider’s train/test split. The dataset is CC BY 4.0.
import orbitalpv as opv
signals = opv.fetch_opssat_segments(
"data/opssat_segments_v2.csv", channels=["CADC0892"], split="test"
)
Photodiode and magnetometer values retain their source scale. The published
CSV supplies no engineering units, so they must not be interpreted as panel
current or generated power. The numeric anomaly field contains the expert
annotation; the inconsistent text label field is preserved but not used
for classification. The gallery plots native signals and separately selected
nominal/anomalous segments without filling the missing mission intervals.
LISIRD: measured total and spectral irradiance#
LASP’s public science products supply
TSIS-1 TIM and SORCE TIM total irradiance, plus TSIS-1 SIM spectral irradiance.
The connector validates units and decodes the time conventions declared by
the LaTiS jsond metadata. Nominal bin centers and weighted average
measurement times remain separate where both are provided.
import orbitalpv as opv
with opv.LisirdConnector() as connector:
tsi = connector.total_solar_irradiance(
"tsis_tsi_24hr", time_min="2023-01-01", time_max="2024-01-01",
cache_path="data/tsis_2023.json",
)
spectrum = connector.spectral_irradiance(
time_min="2023-06-01", time_max="2023-06-04",
cache_path="data/tsis_spectrum_20230601_03.json",
)
TSI fields at 1 AU and actual Earth distance are distinct and use W/m²; spectral fields use W/m²/nm with wavelengths in nm. Provider fill values, uncertainties, provisional flags and spectral quality bits remain explicit. The 2023 daily series has 365 nominal bins but only 292 valid measured bins in the checked snapshot. The example leaves the missing bins as gaps.
The spectral example uses three daily spectra with 2,104 wavelength bins each. It shows quality-marked wavelengths separately and does not integrate across rejected intervals. The illustrative PV response in the TSI example is a simulation driven by measured irradiance, not measured spacecraft power.
GOES: measured particle environment#
import orbitalpv as opv
with opv.NoaaSwpcConnector() as connector:
protons = connector.goes_integral_particle_flux(
"protons", period="7-day", cache_path="data/goes_protons.json"
)
This retrieves a rolling observation window and caches the original response;
refresh=True requests a new snapshot. Flux is in particles/(cm² s sr),
and actual satellite IDs and energy thresholds are retained. Primary proton
and electron observations can come from different GOES spacecraft. Integral
energy channels overlap and must not be summed; energetic protons can
contaminate electron measurements. These geostationary observations are
environmental context, not a spacecraft-specific radiation damage dose.
See NOAA’s proton and electron product descriptions for units and limitations.
Provenance contract#
Every serious ingestion workflow should retain:
source and endpoint;
request parameters;
retrieval timestamp;
source/product version;
original time scale;
coordinate frame;
units and quality flags;
raw checksum;
parser version;
licensing or usage constraints.
This information is required to reproduce later modelling results.
Solar radiation, activity and storms#
Use the existing LisirdConnector.total_solar_irradiance and
spectral_irradiance for measured sunlight (TSIS/SORCE, W/m² and W/m²/nm).
These distinguish irradiance at 1 AU from irradiance at Earth’s actual distance.
They are not surface irradiance or spacecraft electrical telemetry.
NoaaSwpcConnector additionally provides:
solar_activity("xrays"): rolling six-hour primary GOES X-ray channels;flux_w_m2retains separate energy bands and satellite identifiers.solar_activity("kp"): estimated planetary Kp, dimensionless, 0–9.solar_activity("alerts"): complete official bulletin text and issue time; bulletins can be watches, warnings, cancellations or summaries, not just events.solar_wind_magnetic_field(): native real-time L1 magnetic-field records.Existing
real_time_solar_wind(),f107_flux()andgoes_integral_particle_flux(): plasma, radio activity and proton/electron measurements. ExistingDonkiConnector.eventssupplies NASA event catalogues.
The normalized activity interface accepts cache_path and refresh=True.
Caches preserve original JSON plus URL, retrieval time and SHA-256 in a sidecar.
A cache is deliberately a frozen snapshot, not a freshness guarantee. Inspect
measurement/issue timestamps independently of retrieval time. Missing records
are not quiet conditions; invalid numeric measurements are masked and flagged.
For X-rays, quality_good additionally requires an explicitly false NOAA
electron-contamination flag; missing quality is not treated as good.
HTTP and schema errors propagate instead of generating substitute observations.
Example:
from orbitalpv import NoaaSwpcConnector
with NoaaSwpcConnector() as source:
xrays = source.solar_activity("xrays", cache_path="xrays.json", refresh=True)
kp = source.solar_activity("kp")
alerts = source.solar_activity("alerts")
Run examples/real_data/plot_solar_activity.py for an offline synthetic demo;
set ORBITALPV_LIVE_SOLAR=1 for rolling observations. The demo does not infer
causation from concurrent curves. X-ray flux is not broadband PV irradiance;
Kp and L1 observations are not orbit-specific dose or PV loss estimates.
Operational feeds may be provisional and primary GOES identity can change.
Sources: NOAA SWPC data services, GOES X-ray flux, LASP TSIS data.