Download backend/telemetry_v2.py from m4az19/saef-api: direct link, hf CLI and curl.
- Browser
- Download file 12.4 kB
-
https://huggingface.co/spaces/m4az19/saef-api/resolve/main/backend/telemetry_v2.py
- Command line
-
hf download hf://spaces/m4az19/saef-api/backend/telemetry_v2.py
-
curl -L -o telemetry_v2.py https://huggingface.co/spaces/m4az19/saef-api/resolve/main/backend/telemetry_v2.py
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') | |
| 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) | |
| 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) | |
| 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) | |
| 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) | |
| 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']) | |
| 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 | |
| def latest(mode:Literal['real','demo']='real'):return status(mode) | |
| class Replay(Strict): | |
| packets:list[Packet]=Field(min_length=1,max_length=200) | |
| 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]} | |