"""Versioned ground-receiver protocol. Replay has a separate persistent namespace.""" import hashlib import json from datetime import datetime, timedelta, timezone from typing import Literal from fastapi import APIRouter, Header from pydantic import BaseModel, ConfigDict, Field, model_validator from . import store from .intelligence_api import device_auth class Strict(BaseModel): model_config = ConfigDict(extra='forbid', allow_inf_nan=False, strict=True) class Sensors(Strict): # Required keys, nullable values: missing instrumentation is explicit. battery_voltage_v: float | None = Field(ge=0, le=100) battery_current_a: float | None = Field(ge=-20, le=20) solar_voltage_v: float | None = Field(ge=0, le=100) solar_current_a: float | None = Field(ge=0, le=20) temperature_c: float | None = Field(ge=-80, le=100) ldr_fraction: float | None = Field(ge=0, le=1) accel_g: list[float] | None = Field(min_length=3, max_length=3) gyro_dps: list[float] | None = Field(min_length=3, max_length=3) humidity_pct: float | None = Field(default=None,ge=0,le=100) pressure_hpa: float | None = Field(default=None,ge=300,le=1200) illuminance_lux: float | None = Field(default=None,ge=0,le=200000) battery_level_pct: float | None = Field(default=None,ge=0,le=100,exclude_if=lambda value:value is None) battery_level_method: Literal['voltage_estimate','fuel_gauge','coulomb_counting'] | None = Field(default=None,exclude_if=lambda value:value is None) battery_current_polarity_verified: bool = Field(default=False,exclude_if=lambda value:value is False) temperature_source: Literal['dht11','bme280','bmp280','mpu6050','unknown'] = Field(default='unknown',exclude_if=lambda value:value=='unknown') @model_validator(mode='after') def vectors(self): if self.accel_g is not None and any(abs(v)>16 for v in self.accel_g): raise ValueError('accel_g exceeds configured MPU6050 range') if self.gyro_dps is not None and any(abs(v)>2000 for v in self.gyro_dps): raise ValueError('gyro_dps exceeds MPU6050 range') return self class OnboardAI(Strict): model_version: str = Field(min_length=1, max_length=100) feature_version: Literal['sensor-features-1'] status: Literal['ok', 'insufficient_inputs', 'self_test_failed'] score: float | None = Field(ge=0, le=1e12) category: Literal['nominal', 'anomaly', 'unavailable'] training_domain: Literal['synthetic_bootstrap', 'device_recordings'] inference_us: int | None = Field(ge=0, le=60_000_000) @model_validator(mode='after') def result(self): if self.status=='ok' and (self.score is None or self.category=='unavailable') or self.status!='ok' and (self.score is not None or self.category!='unavailable'): raise ValueError('AI status, score and category disagree') return self class Link(Strict): transport: Literal['usb', 'wifi', 'lora'] tx_ok: int = Field(ge=0) tx_failed: int = Field(ge=0) rssi_dbm: float | None = Field(ge=-200, le=20) snr_db: float | None = Field(ge=-50, le=50) radio_status: Literal['disabled','ready','unavailable','airtime_deferred'] | None = Field(default=None,exclude_if=lambda value:value is None) measurement_source: Literal['ground_station'] | None = Field(default=None,exclude_if=lambda value:value is None) tx_sequence: int | None = Field(default=None,ge=0,le=4294967295,exclude_if=lambda value:value is None) class PayloadAI(Strict): model_version: str = Field(min_length=1,max_length=100) task: Literal['water_segmentation','cloud_segmentation','landcover_classification','scene_triage'] status: Literal['ok','unavailable','quality_rejected','inference_failed'] view_geometry: Literal['downward','upward','unknown'] water_cover_pct: float | None = Field(default=None,ge=0,le=100) cloud_cover_pct: float | None = Field(default=None,ge=0,le=100) inference_us: int | None = Field(default=None,ge=0,le=60_000_000) capture_uptime_ms: int = Field(ge=0) image_sequence: int = Field(ge=0) interest: Literal['water_context_candidate','unflagged_view'] | None = Field(default=None,exclude_if=lambda value:value is None) water_context_score: float | None = Field(default=None,ge=0,le=1,exclude_if=lambda value:value is None) @model_validator(mode='after') def results(self): if self.status!='ok' and (self.water_cover_pct is not None or self.cloud_cover_pct is not None): raise ValueError('Unavailable payload cannot report coverage') if self.water_cover_pct is not None and self.task!='water_segmentation': raise ValueError('Water coverage needs a pixel segmentation model') if self.cloud_cover_pct is not None and self.task!='cloud_segmentation': raise ValueError('Cloud coverage needs a cloud segmentation model') return self class ScenePrediction(Strict): label: str = Field(min_length=1, max_length=160) score: float = Field(ge=0, le=1) class CameraQuality(Strict): luminance_mean: float = Field(ge=0,le=1) dark_fraction: float = Field(ge=0,le=1) bright_fraction: float = Field(ge=0,le=1) edge_mean: float = Field(ge=0,le=1) class CameraAI(Strict): model_version: Literal['espressif-mobilenetv2-s8-v1'] training_domain: Literal['imagenet-1k'] status: Literal['ok', 'camera_unavailable', 'inference_failed','capture_deferred','quality_rejected'] predictions: list[ScenePrediction] = Field(max_length=5) inference_us: int | None = Field(ge=0, le=60_000_000) capture_reason: str | None = Field(default=None,max_length=200,exclude_if=lambda value:value is None) capture_uptime_ms: int | None = Field(default=None,ge=0,exclude_if=lambda value:value is None) quality: CameraQuality | None = Field(default=None,exclude_if=lambda value:value is None) @model_validator(mode='after') def result(self): if (self.status=='ok') != bool(self.predictions): raise ValueError('Camera status and predictions disagree') if self.status!='ok' and self.inference_us is not None: raise ValueError('Failed camera inference cannot report latency') return self class Packet(Strict): protocol_version: Literal[2] device_id: str = Field(pattern=r'^[A-Za-z0-9_.-]{1,64}$') session_id: str = Field(pattern=r'^[A-Za-z0-9_.-]{1,64}$') sequence: int = Field(ge=0, le=4294967295) measured_at: str | None uptime_ms: int = Field(ge=0) firmware_version: str = Field(min_length=1, max_length=80) provenance: Literal['MEASURED', 'SIMULATED'] sensors: Sensors onboard_ai: OnboardAI | None = None operating_mode: Literal['NOMINAL','SAFE','CRITICAL'] | None = Field(default=None,exclude_if=lambda value:value is None) images_taken: int | None = Field(default=None,ge=0,exclude_if=lambda value:value is None) payload_ai: PayloadAI | None = Field(default=None,exclude_if=lambda value:value is None) camera_ai: CameraAI | None = Field(default=None, exclude_if=lambda value: value is None) link: Link safety_flags: list[str] = Field(max_length=16) @model_validator(mode='after') def clock(self): if self.onboard_ai is None and self.camera_ai is None and self.payload_ai is None: raise ValueError('A sensor or camera inference status is required') if self.camera_ai and self.camera_ai.capture_uptime_ms is not None and self.camera_ai.capture_uptime_ms>self.uptime_ms: raise ValueError('Camera capture uptime exceeds packet uptime') if self.payload_ai and self.payload_ai.capture_uptime_ms>self.uptime_ms: raise ValueError('Payload capture uptime exceeds packet uptime') if self.measured_at: d=datetime.fromisoformat(self.measured_at.replace('Z','+00:00')) if d.tzinfo is None:raise ValueError('measured_at requires a timezone') if d>datetime.now(timezone.utc)+timedelta(minutes=5):raise ValueError('Future measurement') self.measured_at=d.astimezone(timezone.utc).isoformat() if any(len(flag)>100 for flag in self.safety_flags):raise ValueError('Safety flag too long') return self def ingest(packet: Packet, mode='real', receiver='ground-receiver'): if mode=='real' and packet.provenance!='MEASURED':raise ValueError('Simulated packets require replay ingestion') body=packet.model_dump(mode='json') checksum=hashlib.sha256(json.dumps(body,sort_keys=True,separators=(',',':')).encode()).hexdigest() identity=hashlib.sha256(json.dumps([mode,packet.device_id,packet.session_id,packet.sequence]).encode()).hexdigest() stamp=store.now() record={**body,'id':identity,'mode':mode,'received_at':stamp,'receiver':receiver, 'source':'LIVE GROUND TELEMETRY' if mode=='real' else 'REPLAY / SIMULATED TELEMETRY', 'checksum':checksum,'time_quality':'device_utc' if packet.measured_at else 'unsynchronized; reception time only'} # Identity check and insert share an SQLite write transaction, including concurrent requests. with store.connection() as con: con.execute('BEGIN IMMEDIATE') row=con.execute('SELECT body FROM records WHERE kind=? AND id=?',('telemetry_v2',identity)).fetchone() if row: old=json.loads(row[0]) if old['checksum']!=checksum:raise ValueError('Conflicting device/session/sequence') return {**old,'duplicate':True} con.execute('INSERT INTO records VALUES (?,?,?)',('telemetry_v2',identity,json.dumps(record,allow_nan=False))) return {**record,'duplicate':False} def status(mode='real', at=None): at=at or datetime.now(timezone.utc) with store.connection() as con: con.execute("CREATE INDEX IF NOT EXISTS telemetry_v2_recent ON records(json_extract(body,'$.mode'),json_extract(body,'$.received_at') DESC) WHERE kind='telemetry_v2'") rows=[json.loads(r[0]) for r in con.execute("SELECT body FROM records WHERE kind='telemetry_v2' AND json_extract(body,'$.mode')=? ORDER BY json_extract(body,'$.received_at') DESC LIMIT 500",(mode,))] latest=rows[0] if rows else None received_age=(at-datetime.fromisoformat(latest['received_at'])).total_seconds() if latest else None measured_age=(at-datetime.fromisoformat(latest['measured_at'])).total_seconds() if latest and latest['measured_at'] else None groups={} for r in rows: groups.setdefault((r['device_id'],r['session_id']),set()).add(r['sequence']) gaps=sum(max(0,b-a-1) for seq in groups.values() for a,b in zip(sorted(seq),sorted(seq)[1:])) result={'mode':mode,'latest':latest,'recent_packets':rows[:50], 'status':'NO TELEMETRY' if not latest else 'REPLAY' if mode=='demo' else 'STALE' if received_age>900 or measured_age is not None and measured_age>900 else 'RECENT' if measured_age is not None else 'CLOCK UNSYNCHRONIZED', 'received_age_seconds':received_age,'measurement_age_seconds':measured_age,'sequence_gaps':gaps, 'gap_scope':'Within boot sessions in the latest 500 received packets; gaps are not a measured packet-loss rate.', 'malformed_packets':len([r for r in store.all_records('validation_issues') if str(r.get('source','')).startswith('/api/v2/telemetry')]), 'missing_sensors':[k for k,v in latest['sensors'].items() if v is None] if latest else list(Sensors.model_fields), 'orbital_link':'UNVERIFIED'} from .spacecraft import assess result['spacecraft']=assess(result) return result router=APIRouter(prefix='/api/v2/telemetry',tags=['Versioned telemetry']) @router.post('') def receive(packet:Packet,x_device_key:str|None=Header(None)): device_auth(x_device_key) result=ingest(packet) from .pipeline import wake if not result['duplicate']:wake() return result @router.get('') def latest(mode:Literal['real','demo']='real'):return status(mode) class Replay(Strict): packets:list[Packet]=Field(min_length=1,max_length=200) @router.post('/replay') def replay(req:Replay,x_device_key:str|None=Header(None)): device_auth(x_device_key) # Validate all records before insertion. Recorded measured packets remain labelled replay. return {'mode':'demo','source':'REPLAY','results':[ingest(p,'demo','replay-file') for p in req.packets]}