feat: publish adaptive-link OSD contract and keep overlay above video (#3)
This commit is contained in:
+181
-24
@@ -1,9 +1,21 @@
|
||||
// Package osd is the shared flight OSD snapshot contract between the Ground
|
||||
// Station supervisor and the kiosk display process. The supervisor owns the
|
||||
// RC, arming, power and video state and publishes immutable snapshots;
|
||||
// the display renders the latest fresh snapshot on the transparent OSD
|
||||
// overlay. The snapshot is a plain value: everything published is copied, so
|
||||
// a reader can never observe or mutate a half-written state.
|
||||
// RC, arming, video and operator-configuration state and publishes immutable
|
||||
// snapshots; the display renders the latest fresh snapshot on the transparent
|
||||
// OSD overlay. The snapshot is a plain value: everything published is copied,
|
||||
// so a reader can never observe or mutate a half-written state.
|
||||
//
|
||||
// The adaptive-link contract is modeled as four distinct values that must
|
||||
// never be collapsed into one another: the operator configuration (selected
|
||||
// power table plus the temporary CH6 maxPower ceiling), the ground-station
|
||||
// policy (requested runtime level), the aircraft VTX acknowledgment (applied
|
||||
// level and lifecycle) and the observed receiver link. Their producers —
|
||||
// adaptive control, the VTX ack transport and WFB RX metric ingestion — do
|
||||
// not exist yet and stay out of scope; until they arrive the snapshot carries
|
||||
// explicit pending/unknown states instead of fabricated data. CH6 is operator
|
||||
// intent only: it constrains what may be requested and is never proof of
|
||||
// applied VTX power, and static configuration is never rendered or serialized
|
||||
// as applied VTX state.
|
||||
package osd
|
||||
|
||||
import (
|
||||
@@ -23,12 +35,18 @@ import (
|
||||
const (
|
||||
Magic0 byte = 'G'
|
||||
Magic1 byte = 'O'
|
||||
Version byte = 1
|
||||
Version byte = 2
|
||||
|
||||
// Size is the fixed encoded snapshot length: magic and version, frame
|
||||
// sequence and timestamp, all 16 final RC channels, one flags byte,
|
||||
// the publish time and the CRC.
|
||||
Size = 3 + 2 + 4 + protocol.Channels*2 + 1 + 8 + 2
|
||||
// the publish time, the four adaptive-link contract values and the CRC.
|
||||
Size = 3 + 2 + 4 + protocol.Channels*2 + 1 + 8 + // 50: v2 header block
|
||||
1 + // operator maxPower ceiling
|
||||
4 + 8 + // operator table generation + hash
|
||||
1 + 8 + 8 + // policy level + reason + timestamp
|
||||
4 + 8 + 1 + 1 + // ack table generation + hash + level + lifecycle
|
||||
8 + // link freshness age
|
||||
2 // CRC
|
||||
|
||||
// DefaultStatePath is where the supervisor publishes snapshots and
|
||||
// where the display reads them unless configured otherwise. It lives
|
||||
@@ -48,13 +66,48 @@ const (
|
||||
// dead UART must end OSD rendering instead of freezing stale telemetry
|
||||
// over live video.
|
||||
Freshness = 2 * time.Second
|
||||
|
||||
// MaxVTXLevel is the upper bound of the VTX power level domain shared
|
||||
// by the operator ceiling, the ground-station policy and the applied
|
||||
// acknowledgment.
|
||||
MaxVTXLevel uint8 = 127
|
||||
)
|
||||
|
||||
// VTX acknowledgment lifecycle states.
|
||||
const (
|
||||
// VTXLifecyclePending means no acknowledgment has arrived yet.
|
||||
VTXLifecyclePending uint8 = 0
|
||||
// VTXLifecycleApplied means the VTX acknowledged applying the level.
|
||||
VTXLifecycleApplied uint8 = 1
|
||||
// VTXLifecycleError means the acknowledgment reported a lifecycle error.
|
||||
VTXLifecycleError uint8 = 2
|
||||
)
|
||||
|
||||
// Snapshot flag bits in the encoded record.
|
||||
const (
|
||||
flagArmed byte = 1 << iota
|
||||
flagPower
|
||||
flagVideo
|
||||
flagTableSelected
|
||||
flagPolicyPending
|
||||
flagAckPending
|
||||
flagLinkKnown
|
||||
)
|
||||
|
||||
// Fixed field offsets of the encoded record.
|
||||
const (
|
||||
publishedOffset = 42
|
||||
opMaxPowerOffset = 50
|
||||
opTableGenOffset = 51
|
||||
opTableHashOffset = 55
|
||||
policyLevelOffset = 63
|
||||
policyReasonOffset = 64
|
||||
policyTimeOffset = 72
|
||||
ackTableGenOffset = 80
|
||||
ackTableHashOffset = 84
|
||||
ackLevelOffset = 92
|
||||
ackLifecycleOffset = 93
|
||||
linkAgeOffset = 94
|
||||
crcOffset = Size - 2
|
||||
)
|
||||
|
||||
var (
|
||||
@@ -64,24 +117,95 @@ var (
|
||||
ErrCRC = errors.New("groundstation/osd: invalid snapshot crc")
|
||||
)
|
||||
|
||||
// Table identifies a selectable VTX power table by generation and content
|
||||
// hash. Zero generation and hash mean no table is selected yet. The
|
||||
// identifiers are the operator's opaque selection of a table target — the
|
||||
// table generator (future work) owns real identity — and a statically
|
||||
// configured selection is operator intent: it is never applied VTX state.
|
||||
type Table struct {
|
||||
Gen uint32
|
||||
Hash uint64
|
||||
}
|
||||
|
||||
// Selected reports whether a table has been selected at all.
|
||||
func (t Table) Selected() bool { return t.Gen != 0 || t.Hash != 0 }
|
||||
|
||||
// OperatorConfig is the operator's configuration intent: the selected power
|
||||
// table plus the temporary CH6 maxPower ceiling. It is never proof of
|
||||
// applied VTX power: the ceiling constrains what the system may request,
|
||||
// while the applied state comes only from a VTX acknowledgment.
|
||||
type OperatorConfig struct {
|
||||
Table Table
|
||||
MaxPower uint8 // maxPower ceiling in the 0..127 level domain
|
||||
}
|
||||
|
||||
// GSPolicy is the ground station's requested runtime VTX power level with
|
||||
// the reason and time of the request. No policy producer exists yet (the
|
||||
// adaptive controller is future work), so published policies stay Pending
|
||||
// rather than fabricating a level. Within the 0..127 domain, level 0 is an
|
||||
// explicit off / no-runtime-command request; only Pending marks the absent
|
||||
// producer.
|
||||
type GSPolicy struct {
|
||||
Pending bool
|
||||
Level uint8 // requested level, 0..127; 0 is explicit off
|
||||
Reason [8]byte // producer-defined short reason tag
|
||||
TimestampMS int64
|
||||
}
|
||||
|
||||
// VTXAck is the aircraft VTX's acknowledgment: the table it accepted, the
|
||||
// level it applied and its lifecycle/error state. No acknowledgment
|
||||
// transport exists yet, so published acks stay Pending. Applied level 0 is
|
||||
// an explicit applied-off state; only Pending marks the absent transport.
|
||||
type VTXAck struct {
|
||||
Pending bool
|
||||
Table Table
|
||||
Level uint8 // applied level, 0..127; 0 is explicit off
|
||||
Lifecycle uint8
|
||||
}
|
||||
|
||||
// GSObservedLink is the ground-station receiver's link observation with its
|
||||
// freshness. WFB RX metrics are out of scope until that producer exists, so
|
||||
// the observation stays explicitly UNKNOWN instead of carrying fabricated
|
||||
// numbers.
|
||||
type GSObservedLink struct {
|
||||
Known bool // false = explicitly unknown
|
||||
AgeMS int64 // freshness of the metrics at publication; 0 while unknown
|
||||
}
|
||||
|
||||
// Snapshot is one immutable flight state: the final RC channels, the arm
|
||||
// state derived from the configured arm channel, the requested CH6 WFB power
|
||||
// and the supervisor's decoded-video presence knowledge — its video
|
||||
// launcher ownership, the only decoded-video signal the supervisor has —
|
||||
// plus the provenance of the RC frame it was built from. The display never
|
||||
// renders from this field: it gates on the video lifecycle it observes on
|
||||
// the display server itself. PublishedMS is stamped at publication and is
|
||||
// what the display uses to reject stale snapshots.
|
||||
// state derived from the configured arm channel, the supervisor's
|
||||
// decoded-video presence knowledge and the four adaptive-link contract
|
||||
// values, plus the provenance of the RC frame it was built from. The display
|
||||
// never renders from the Video field: it gates on the video lifecycle it
|
||||
// observes on the display server itself. PublishedMS is stamped at
|
||||
// publication and is what the display uses to reject stale snapshots.
|
||||
type Snapshot struct {
|
||||
Sequence uint16
|
||||
TimestampMS uint32
|
||||
Channels [protocol.Channels]int16
|
||||
Armed bool
|
||||
Power bool
|
||||
Video bool
|
||||
OpConfig OperatorConfig
|
||||
Policy GSPolicy
|
||||
Ack VTXAck
|
||||
Link GSObservedLink
|
||||
PublishedMS int64
|
||||
}
|
||||
|
||||
// CeilingFromChannel maps the final CH6 channel onto the temporary operator
|
||||
// maxPower ceiling: the full channel range -1024..1024 scales linearly onto
|
||||
// the 0..127 level domain with clamping. The ceiling is operator intent
|
||||
// only and never proof of applied VTX power.
|
||||
func CeilingFromChannel(channel int16) uint8 {
|
||||
if channel <= -1024 {
|
||||
return 0
|
||||
}
|
||||
if channel >= 1024 {
|
||||
return MaxVTXLevel
|
||||
}
|
||||
return uint8((int32(channel) + 1024) * int32(MaxVTXLevel) / 2048)
|
||||
}
|
||||
|
||||
func Encode(snapshot Snapshot) []byte {
|
||||
buf := make([]byte, Size)
|
||||
buf[0], buf[1], buf[2] = Magic0, Magic1, Version
|
||||
@@ -94,15 +218,35 @@ func Encode(snapshot Snapshot) []byte {
|
||||
if snapshot.Armed {
|
||||
flags |= flagArmed
|
||||
}
|
||||
if snapshot.Power {
|
||||
flags |= flagPower
|
||||
}
|
||||
if snapshot.Video {
|
||||
flags |= flagVideo
|
||||
}
|
||||
if snapshot.OpConfig.Table.Selected() {
|
||||
flags |= flagTableSelected
|
||||
}
|
||||
if snapshot.Policy.Pending {
|
||||
flags |= flagPolicyPending
|
||||
}
|
||||
if snapshot.Ack.Pending {
|
||||
flags |= flagAckPending
|
||||
}
|
||||
if snapshot.Link.Known {
|
||||
flags |= flagLinkKnown
|
||||
}
|
||||
buf[41] = flags
|
||||
binary.LittleEndian.PutUint64(buf[42:50], uint64(snapshot.PublishedMS))
|
||||
binary.LittleEndian.PutUint16(buf[Size-2:], protocol.CRC16CCITT(buf[:Size-2]))
|
||||
binary.LittleEndian.PutUint64(buf[publishedOffset:opMaxPowerOffset], uint64(snapshot.PublishedMS))
|
||||
buf[opMaxPowerOffset] = snapshot.OpConfig.MaxPower
|
||||
binary.LittleEndian.PutUint32(buf[opTableGenOffset:opTableHashOffset], snapshot.OpConfig.Table.Gen)
|
||||
binary.LittleEndian.PutUint64(buf[opTableHashOffset:policyLevelOffset], snapshot.OpConfig.Table.Hash)
|
||||
buf[policyLevelOffset] = snapshot.Policy.Level
|
||||
copy(buf[policyReasonOffset:policyTimeOffset], snapshot.Policy.Reason[:])
|
||||
binary.LittleEndian.PutUint64(buf[policyTimeOffset:ackTableGenOffset], uint64(snapshot.Policy.TimestampMS))
|
||||
binary.LittleEndian.PutUint32(buf[ackTableGenOffset:ackTableHashOffset], snapshot.Ack.Table.Gen)
|
||||
binary.LittleEndian.PutUint64(buf[ackTableHashOffset:ackLevelOffset], snapshot.Ack.Table.Hash)
|
||||
buf[ackLevelOffset] = snapshot.Ack.Level
|
||||
buf[ackLifecycleOffset] = snapshot.Ack.Lifecycle
|
||||
binary.LittleEndian.PutUint64(buf[linkAgeOffset:crcOffset], uint64(snapshot.Link.AgeMS))
|
||||
binary.LittleEndian.PutUint16(buf[crcOffset:], protocol.CRC16CCITT(buf[:crcOffset]))
|
||||
return buf
|
||||
}
|
||||
|
||||
@@ -117,7 +261,7 @@ func Decode(buf []byte) (Snapshot, error) {
|
||||
if buf[2] != Version {
|
||||
return snapshot, ErrVersion
|
||||
}
|
||||
if got, want := binary.LittleEndian.Uint16(buf[Size-2:]), protocol.CRC16CCITT(buf[:Size-2]); got != want {
|
||||
if got, want := binary.LittleEndian.Uint16(buf[crcOffset:]), protocol.CRC16CCITT(buf[:crcOffset]); got != want {
|
||||
return snapshot, fmt.Errorf("%w: got %04x want %04x", ErrCRC, got, want)
|
||||
}
|
||||
snapshot.Sequence = binary.LittleEndian.Uint16(buf[3:5])
|
||||
@@ -127,9 +271,22 @@ func Decode(buf []byte) (Snapshot, error) {
|
||||
}
|
||||
flags := buf[41]
|
||||
snapshot.Armed = flags&flagArmed != 0
|
||||
snapshot.Power = flags&flagPower != 0
|
||||
snapshot.Video = flags&flagVideo != 0
|
||||
snapshot.PublishedMS = int64(binary.LittleEndian.Uint64(buf[42:50]))
|
||||
snapshot.OpConfig.MaxPower = buf[opMaxPowerOffset]
|
||||
snapshot.OpConfig.Table.Gen = binary.LittleEndian.Uint32(buf[opTableGenOffset:opTableHashOffset])
|
||||
snapshot.OpConfig.Table.Hash = binary.LittleEndian.Uint64(buf[opTableHashOffset:policyLevelOffset])
|
||||
snapshot.Policy.Level = buf[policyLevelOffset]
|
||||
copy(snapshot.Policy.Reason[:], buf[policyReasonOffset:policyTimeOffset])
|
||||
snapshot.Policy.TimestampMS = int64(binary.LittleEndian.Uint64(buf[policyTimeOffset:ackTableGenOffset]))
|
||||
snapshot.Ack.Table.Gen = binary.LittleEndian.Uint32(buf[ackTableGenOffset:ackTableHashOffset])
|
||||
snapshot.Ack.Table.Hash = binary.LittleEndian.Uint64(buf[ackTableHashOffset:ackLevelOffset])
|
||||
snapshot.Ack.Level = buf[ackLevelOffset]
|
||||
snapshot.Ack.Lifecycle = buf[ackLifecycleOffset]
|
||||
snapshot.Link.AgeMS = int64(binary.LittleEndian.Uint64(buf[linkAgeOffset:crcOffset]))
|
||||
snapshot.Policy.Pending = flags&flagPolicyPending != 0
|
||||
snapshot.Ack.Pending = flags&flagAckPending != 0
|
||||
snapshot.Link.Known = flags&flagLinkKnown != 0
|
||||
snapshot.PublishedMS = int64(binary.LittleEndian.Uint64(buf[publishedOffset:opMaxPowerOffset]))
|
||||
return snapshot, nil
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user