fix(observers): rename telemetry airtime fields to seconds

db/migrations/033_telemetry_airtime_secs.sql

@@ -0,0 +1,4 @@
+-- These always held seconds of radio time from the observer's tx_air_secs/rx_air_secs
+-- status fields, never a percentage; name them for what they are.
+ALTER TABLE observer_telemetry RENAME COLUMN airtime_tx_pct TO airtime_tx_secs;
+ALTER TABLE observer_telemetry RENAME COLUMN airtime_rx_pct TO airtime_rx_secs;

db/observers.go

@@ -158,8 +158,8 @@ func (s *Store) InsertObserverTelemetry(ctx context.Context, observerID uuid.UUI
 		ObserverID:       observerID,
 		ReportedAt:       pgtype.Timestamptz{Time: reportedAt, Valid: true},
 		BatteryVoltageMv: batteryMV,
-		AirtimeTxPct:     txAirSecs,
-		AirtimeRxPct:     rxAirSecs,
+		AirtimeTxSecs:    txAirSecs,
+		AirtimeRxSecs:    rxAirSecs,
 		NoiseFloorDb:     &noiseFloor,
 		UptimeSeconds:    &uptimeSeconds,
 		QueueLength:      queueLen,
@@ -183,8 +183,8 @@ func (s *Store) GetObserverTelemetry(ctx context.Context, observerID uuid.UUID,
 		points = append(points, api.ObserverTelemetryPoint{
 			T:             v.ReportedAt.Time.UnixMilli(),
 			BatteryMV:     v.BatteryVoltageMv,
-			AirtimeTxPct:  v.AirtimeTxPct,
-			AirtimeRxPct:  v.AirtimeRxPct,
+			AirtimeTxSecs: v.AirtimeTxSecs,
+			AirtimeRxSecs: v.AirtimeRxSecs,
 			NoiseFloorDB:  v.NoiseFloorDb,
 			UptimeSeconds: v.UptimeSeconds,
 			QueueLength:   v.QueueLength,
@@ -216,8 +216,8 @@ func (s *Store) GetObserverTelemetryBucketed(ctx context.Context, observerID uui
 		points = append(points, api.ObserverTelemetryPoint{
 			T:             r.Bucket.Time.UnixMilli(),
 			BatteryMV:     &r.BatteryVoltageMv,
-			AirtimeTxPct:  &r.AirtimeTxPct,
-			AirtimeRxPct:  &r.AirtimeRxPct,
+			AirtimeTxSecs: &r.AirtimeTxSecs,
+			AirtimeRxSecs: &r.AirtimeRxSecs,
 			NoiseFloorDB:  &r.NoiseFloorDb,
 			UptimeSeconds: &r.UptimeSeconds,
 			QueueLength:   &r.QueueLength,

db/queries/queries.sql

@@ -226,14 +226,14 @@ WHERE id = $1;
 -- Inserts a telemetry snapshot for an observer. The reported_at timestamp should
 -- be truncated to the configured resolution before calling to ensure deduplication.
 INSERT INTO observer_telemetry (
-    observer_id, reported_at, battery_voltage_mv, airtime_tx_pct,
-    airtime_rx_pct, noise_floor_db, uptime_seconds, queue_length,
+    observer_id, reported_at, battery_voltage_mv, airtime_tx_secs,
+    airtime_rx_secs, noise_floor_db, uptime_seconds, queue_length,
     debug_flags, receive_errors
 ) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
 ON CONFLICT (observer_id, reported_at) DO NOTHING;
 
 -- name: GetObserverTelemetry :many
-SELECT id, reported_at, battery_voltage_mv, airtime_tx_pct, airtime_rx_pct,
+SELECT id, reported_at, battery_voltage_mv, airtime_tx_secs, airtime_rx_secs,
        noise_floor_db, uptime_seconds, queue_length, debug_flags, receive_errors
 FROM observer_telemetry
 WHERE observer_id = $1
@@ -247,8 +247,8 @@ SELECT
   (date_trunc('day', reported_at) +
     (EXTRACT(HOUR FROM reported_at)::int / $4::int) * ($4::int * interval '1 hour'))::timestamptz AS bucket,
   AVG(battery_voltage_mv)::int   AS battery_voltage_mv,
-  GREATEST(MAX(airtime_tx_pct) - MIN(airtime_tx_pct), 0)::real AS airtime_tx_pct,
-  GREATEST(MAX(airtime_rx_pct) - MIN(airtime_rx_pct), 0)::real AS airtime_rx_pct,
+  GREATEST(MAX(airtime_tx_secs) - MIN(airtime_tx_secs), 0)::real AS airtime_tx_secs,
+  GREATEST(MAX(airtime_rx_secs) - MIN(airtime_rx_secs), 0)::real AS airtime_rx_secs,
   AVG(noise_floor_db)::real      AS noise_floor_db,
   MAX(uptime_seconds)::bigint    AS uptime_seconds,
   AVG(queue_length)::int         AS queue_length,

docs/docs.go

@@ -3204,10 +3204,10 @@ const docTemplate = `{
         "github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint": {
             "type": "object",
             "properties": {
-                "airtimeRxPct": {
+                "airtimeRxSecs": {
                     "type": "number"
                 },
-                "airtimeTxPct": {
+                "airtimeTxSecs": {
                     "type": "number"
                 },
                 "batteryMv": {

docs/swagger.json

@@ -3202,10 +3202,10 @@
         "github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint": {
             "type": "object",
             "properties": {
-                "airtimeRxPct": {
+                "airtimeRxSecs": {
                     "type": "number"
                 },
-                "airtimeTxPct": {
+                "airtimeTxSecs": {
                     "type": "number"
                 },
                 "batteryMv": {

docs/swagger.yaml

@@ -576,9 +576,9 @@ definitions:
     type: object
   github_com_MeshCore-Beacon_beacon-server_internal_api.ObserverTelemetryPoint:
     properties:
-      airtimeRxPct:
+      airtimeRxSecs:
         type: number
-      airtimeTxPct:
+      airtimeTxSecs:
         type: number
       batteryMv:
         type: integer

internal/api/observers.go

@@ -49,11 +49,12 @@ type Observer struct {
 }
 
 // ObserverTelemetryPoint is a single telemetry snapshot for an observer.
+// Airtime is radio seconds: cumulative since boot on 1h points, per-bucket delta on 6h/24h.
 type ObserverTelemetryPoint struct {
 	T             int64    `json:"t"` // epoch ms
 	BatteryMV     *int32   `json:"batteryMv,omitempty"`
-	AirtimeTxPct  *float32 `json:"airtimeTxPct,omitempty"`
-	AirtimeRxPct  *float32 `json:"airtimeRxPct,omitempty"`
+	AirtimeTxSecs *float32 `json:"airtimeTxSecs,omitempty"`
+	AirtimeRxSecs *float32 `json:"airtimeRxSecs,omitempty"`
 	NoiseFloorDB  *float32 `json:"noiseFloorDb,omitempty"`
 	UptimeSeconds *int64   `json:"uptimeSeconds,omitempty"`
 	QueueLength   *int32   `json:"queueLength,omitempty"`