implement some features of Venus OS

mk2driver/mk2interface.go

@@ -151,8 +151,202 @@ type ProtocolControl interface {
 	ReadSelected() (int16, error)
 	// ReadRAMVarInfo reads RAM variable metadata via command 0x36.
 	ReadRAMVarInfo(id uint16) (RAMVarInfo, error)
+	// WriteSelectedData writes to the currently selected register via command 0x34.
+	WriteSelectedData(value int16) error
+	// WriteSettingBySelection performs 0x33 (select setting) followed by 0x34 (write data).
+	WriteSettingBySelection(id uint16, value int16) error
+	// WriteRAMVarBySelection performs 0x32 (select RAM var) followed by 0x34 (write data).
+	WriteRAMVarBySelection(id uint16, value int16) error
 	// WriteSettingByID writes a setting via command 0x37.
 	WriteSettingByID(id uint16, value int16) error
 	// WriteRAMVarByID writes a RAM variable via command 0x38.
 	WriteRAMVarByID(id uint16, value int16) error
 }
+
+type RegisterKind string
+
+const (
+	RegisterKindSetting RegisterKind = "setting"
+	RegisterKindRAMVar  RegisterKind = "ram_var"
+)
+
+type RegisterSafetyClass string
+
+const (
+	// RegisterSafetyReadOnly indicates no write path should be exposed.
+	RegisterSafetyReadOnly RegisterSafetyClass = "read_only"
+	// RegisterSafetyOperational indicates normal runtime write usage is expected.
+	RegisterSafetyOperational RegisterSafetyClass = "operational"
+	// RegisterSafetyGuarded indicates writes should be policy-guarded.
+	RegisterSafetyGuarded RegisterSafetyClass = "guarded"
+	// RegisterSafetyCritical indicates high-impact settings that need stricter controls.
+	RegisterSafetyCritical RegisterSafetyClass = "critical"
+)
+
+type TimeoutClass string
+
+const (
+	TimeoutClassFast     TimeoutClass = "fast"
+	TimeoutClassStandard TimeoutClass = "standard"
+	TimeoutClassSlow     TimeoutClass = "slow"
+)
+
+// RegisterMetadata documents known MK2 register IDs and expected value behavior.
+type RegisterMetadata struct {
+	Kind        RegisterKind
+	ID          uint16
+	Name        string
+	Description string
+	Unit        string
+	Scale       float64
+	Writable    bool
+	Signed      bool
+	MinValue    *int16
+	MaxValue    *int16
+	SafetyClass RegisterSafetyClass
+}
+
+// TransactionOptions controls retry and verification semantics for safe writes.
+type TransactionOptions struct {
+	// Retries is the number of additional write attempts after the first try.
+	Retries int
+	// RetryDelay is slept between retries. Zero uses a sensible default.
+	RetryDelay time.Duration
+	// BackoffFactor multiplies retry delay for each additional attempt (1 disables backoff).
+	BackoffFactor float64
+	// ReadBeforeWrite captures previous value before writing when possible.
+	ReadBeforeWrite bool
+	// VerifyAfterWrite reads the register back and compares with written value.
+	VerifyAfterWrite bool
+	// TimeoutClass applies standard timeout buckets when CommandTimeout is not set.
+	TimeoutClass TimeoutClass
+	// CommandTimeout overrides timeout class for each protocol command inside the transaction.
+	CommandTimeout time.Duration
+}
+
+// RegisterTransactionResult reports details about a transactional register write.
+type RegisterTransactionResult struct {
+	Kind          RegisterKind
+	ID            uint16
+	TargetValue   int16
+	PreviousValue *int16
+	VerifiedValue *int16
+	Attempts      int
+	Timeout       time.Duration
+	Duration      time.Duration
+}
+
+// MetadataControl adds register metadata and transactional safety helpers.
+type MetadataControl interface {
+	ProtocolControl
+	// RegisterMetadata returns metadata for a known register.
+	RegisterMetadata(kind RegisterKind, id uint16) (RegisterMetadata, bool)
+	// ListRegisterMetadata returns all known register metadata.
+	ListRegisterMetadata() []RegisterMetadata
+	// ReadRegister reads a setting or RAM var by kind and id.
+	ReadRegister(kind RegisterKind, id uint16) (int16, error)
+	// WriteRegister performs a safe transactional write with optional retry/verify.
+	WriteRegister(kind RegisterKind, id uint16, value int16, opts TransactionOptions) (RegisterTransactionResult, error)
+}
+
+type RegisterAddress struct {
+	Kind RegisterKind `json:"kind"`
+	ID   uint16       `json:"id"`
+}
+
+type RegisterSnapshotEntry struct {
+	Kind       RegisterKind        `json:"kind"`
+	ID         uint16              `json:"id"`
+	Name       string              `json:"name,omitempty"`
+	Value      int16               `json:"value"`
+	Writable   bool                `json:"writable"`
+	Safety     RegisterSafetyClass `json:"safety_class,omitempty"`
+	CapturedAt time.Time           `json:"captured_at"`
+}
+
+type RegisterSnapshot struct {
+	CapturedAt time.Time               `json:"captured_at"`
+	Entries    []RegisterSnapshotEntry `json:"entries"`
+}
+
+type SnapshotDiff struct {
+	Kind      RegisterKind        `json:"kind"`
+	ID        uint16              `json:"id"`
+	Name      string              `json:"name,omitempty"`
+	Current   int16               `json:"current"`
+	Target    int16               `json:"target"`
+	Changed   bool                `json:"changed"`
+	Writable  bool                `json:"writable"`
+	Safety    RegisterSafetyClass `json:"safety_class,omitempty"`
+	DiffValue int32               `json:"diff_value"`
+}
+
+type SnapshotRestoreResult struct {
+	Applied        []RegisterTransactionResult `json:"applied"`
+	RolledBack     bool                        `json:"rolled_back"`
+	RollbackErrors []string                    `json:"rollback_errors,omitempty"`
+}
+
+// SnapshotControl provides register snapshot, diff preview, and rollback-aware restore.
+type SnapshotControl interface {
+	MetadataControl
+	// CaptureSnapshot reads the provided register list. Empty addresses captures known writable registers.
+	CaptureSnapshot(addresses []RegisterAddress) (RegisterSnapshot, error)
+	// DiffSnapshot compares current values against a snapshot.
+	DiffSnapshot(snapshot RegisterSnapshot) ([]SnapshotDiff, error)
+	// RestoreSnapshot applies snapshot target values; if restore fails mid-way it attempts rollback.
+	RestoreSnapshot(snapshot RegisterSnapshot, opts TransactionOptions) (SnapshotRestoreResult, error)
+}
+
+type TraceDirection string
+
+const (
+	TraceDirectionTX TraceDirection = "tx"
+	TraceDirectionRX TraceDirection = "rx"
+)
+
+type ProtocolTrace struct {
+	Timestamp time.Time      `json:"timestamp"`
+	Direction TraceDirection `json:"direction"`
+	Frame     string         `json:"frame"`
+	Command   string         `json:"command,omitempty"`
+	BytesHex  string         `json:"bytes_hex"`
+}
+
+type DriverDiagnostics struct {
+	GeneratedAt      time.Time       `json:"generated_at"`
+	HealthScore      int             `json:"health_score"`
+	LastFrameAt      *time.Time      `json:"last_frame_at,omitempty"`
+	CommandTimeouts  uint64          `json:"command_timeouts"`
+	CommandFailures  uint64          `json:"command_failures"`
+	ChecksumFailures uint64          `json:"checksum_failures"`
+	RecentErrors     []string        `json:"recent_errors,omitempty"`
+	Traces           []ProtocolTrace `json:"traces"`
+}
+
+// DiagnosticsControl exposes recent protocol traces and health information for troubleshooting bundles.
+type DiagnosticsControl interface {
+	DriverDiagnostics(limit int) DriverDiagnostics
+}
+
+type CommandSource string
+
+const (
+	CommandSourceUnknown    CommandSource = "unknown"
+	CommandSourceUI         CommandSource = "ui"
+	CommandSourceMQTT       CommandSource = "mqtt"
+	CommandSourceAutomation CommandSource = "automation"
+)
+
+// SourceAwareSettingsWriter accepts source tags for arbitration and diagnostics.
+type SourceAwareSettingsWriter interface {
+	SettingsWriter
+	WriteRAMVarWithSource(source CommandSource, id uint16, value int16) error
+	WriteSettingWithSource(source CommandSource, id uint16, value int16) error
+	SetPanelStateWithSource(source CommandSource, switchState PanelSwitchState, currentLimitA *float64) error
+	SetStandbyWithSource(source CommandSource, enabled bool) error
+}
+
+type CommandHistoryProvider interface {
+	History(limit int) []CommandEvent
+}