saef-api / backend /telemetry_v2.py
m4az19's picture
Deploy SAHAB-1 backend and pretrained AI
20b0a08 verified
Raw History Blame Contribute Delete
12.4 kB
"""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]}