PilotVault/API Server/internal/hub/models.go

package hub

import "encoding/json"

// Telemetry holds the latest flight-controller / battery values for a device.
// Pointers distinguish "not yet reported" (nil) from a genuine zero value.
type Telemetry struct {
	SatelliteCount *int     `json:"satelliteCount,omitempty"`
	IsFlying       *bool    `json:"isFlying,omitempty"`
	FlightMode     *string  `json:"flightMode,omitempty"`
	Altitude       *float64 `json:"altitude,omitempty"`
	Latitude       *float64 `json:"latitude,omitempty"`
	Longitude      *float64 `json:"longitude,omitempty"`
	// Phone's own GPS (reported by the Fly App), distinct from the drone's fix
	// above — used as a location fallback for the Web App's auto bounding box.
	PhoneLatitude  *float64 `json:"phoneLatitude,omitempty"`
	PhoneLongitude *float64 `json:"phoneLongitude,omitempty"`
	VelocityX      *float64 `json:"velocityX,omitempty"`
	VelocityY      *float64 `json:"velocityY,omitempty"`
	VelocityZ      *float64 `json:"velocityZ,omitempty"`
	BatteryPercent *int     `json:"batteryPercent,omitempty"`
}

// DeviceState is the server's aggregated view of one app/drone.
type DeviceState struct {
	DeviceID  string `json:"deviceId"`
	Online    bool   `json:"online"`    // app's websocket is connected to the server
	Connected bool   `json:"connected"` // a drone is connected to the app
	Model     string `json:"model"`
	// Registration is the *SDK* registration state reported by the Fly App
	// ("success", "failed", …) — not the aircraft's FAA/CAA registration number,
	// which lives on the drone's logbook record.
	Registration string `json:"registration"`
	// Identity of the connected aircraft, as it reports itself. The serial and the
	// two firmware versions resolve asynchronously after connect, each on its own
	// schedule, so these fill in over several events rather than all at once.
	//
	// FlightControllerSerial is the flight controller's own serial, not the number
	// on the airframe: MSDK v4 exposes no aircraft-level serial, so the serial a
	// drone is *registered* under is hand-entered on its logbook record instead.
	// It is nonetheless stable per airframe, which is what the fleet auto-add keys on.
	FlightControllerSerial string    `json:"flightControllerSerial"`
	Firmware               string    `json:"firmware"`
	ControllerFirmware     string    `json:"controllerFirmware"`
	Telemetry              Telemetry `json:"telemetry"`
	LastSeenMs             int64     `json:"lastSeenMs"`
}

// TrackPoint is one sample of the drone's GPS track (for the map trail).
type TrackPoint struct {
	Lat float64 `json:"lat"`
	Lng float64 `json:"lng"`
	Alt float64 `json:"alt"`
	TS  int64   `json:"ts"`
}

// ServerToUI is the message a dashboard receives over /ws/ui.
type ServerToUI struct {
	Type     string         `json:"type"` // "snapshot" | "update" | "removed"
	Device   *DeviceState   `json:"device,omitempty"`
	Devices  []*DeviceState `json:"devices,omitempty"`
	DeviceID string         `json:"deviceId,omitempty"` // for "removed"
	Event    map[string]any `json:"event,omitempty"`    // the raw device event that triggered this
	TS       int64          `json:"ts"`
}

// Command is what the server pushes down to a device over /ws/device.
type Command struct {
	Type    string         `json:"type"` // always "command"
	Command string         `json:"command"`
	Payload map[string]any `json:"payload,omitempty"`
	TS      int64          `json:"ts"`
}

// toFloat coerces a JSON-decoded value into a float64.
func toFloat(v any) (float64, bool) {
	switch n := v.(type) {
	case float64:
		return n, true
	case float32:
		return float64(n), true
	case int:
		return float64(n), true
	case int64:
		return float64(n), true
	case json.Number:
		f, err := n.Float64()
		return f, err == nil
	}
	return 0, false
}

// toInt coerces a JSON-decoded value into an int.
func toInt(v any) (int, bool) {
	if f, ok := toFloat(v); ok {
		return int(f), true
	}
	return 0, false
}

// applyIdentity copies the aircraft's self-reported identity from a raw event.
// A field the event omits (or reports null) means "not resolved yet" — the SDK
// answers serial in seconds but firmware can take far longer — so an absent
// value never clears one an earlier event already delivered.
func applyIdentity(s *DeviceState, raw map[string]any) {
	if v, ok := raw["flightControllerSerial"].(string); ok && v != "" {
		s.FlightControllerSerial = v
	}
	if v, ok := raw["firmware"].(string); ok && v != "" {
		s.Firmware = v
	}
	if v, ok := raw["controllerFirmware"].(string); ok && v != "" {
		s.ControllerFirmware = v
	}
}

// applyTelemetry copies any present telemetry fields from a raw event map.
func applyTelemetry(t *Telemetry, raw map[string]any) {
	if v, ok := toInt(raw["satelliteCount"]); ok {
		t.SatelliteCount = &v
	}
	if v, ok := raw["isFlying"].(bool); ok {
		t.IsFlying = &v
	}
	if v, ok := raw["flightMode"].(string); ok {
		t.FlightMode = &v
	}
	if v, ok := toFloat(raw["altitude"]); ok {
		t.Altitude = &v
	}
	if v, ok := toFloat(raw["latitude"]); ok {
		t.Latitude = &v
	}
	if v, ok := toFloat(raw["longitude"]); ok {
		t.Longitude = &v
	}
	if v, ok := toFloat(raw["phoneLatitude"]); ok {
		t.PhoneLatitude = &v
	}
	if v, ok := toFloat(raw["phoneLongitude"]); ok {
		t.PhoneLongitude = &v
	}
	if v, ok := toFloat(raw["velocityX"]); ok {
		t.VelocityX = &v
	}
	if v, ok := toFloat(raw["velocityY"]); ok {
		t.VelocityY = &v
	}
	if v, ok := toFloat(raw["velocityZ"]); ok {
		t.VelocityZ = &v
	}
	// Since the Fly App batches telemetry, the battery rides along as a nested
	// group whose top-level percent is the weakest pack. The standalone
	// "battery" event is still accepted for older app builds.
	if b, ok := raw["battery"].(map[string]any); ok {
		if p, ok := toInt(b["percent"]); ok {
			t.BatteryPercent = &p
		}
	}
}