Sensors¶
Detection sensors (motion, object, face, license-plate, audio, classifier, clip) and smart-home sensors (contact, doorbell, lock, garage, light, switch, PTZ, security system, environmental). Plus the sensor-level model specs and shared detection types (Detection, BoundingBox, TrackedDetection).
Note
The reference below is auto-generated from Go doc comments via gomarkdoc. Re-run scripts/gen-api-docs.sh to refresh it.
type AudioDetector¶
AudioDetector is implemented by plugins that classify audio events. The runtime resamples and buffers audio to match ModelSpec before each call.
type AudioDetector interface {
// ModelSpec declares the expected audio input format.
ModelSpec() AudioModelSpec
// DetectAudio analyzes a single audio frame and returns the audio result.
DetectAudio(audio AudioFrameData) (*AudioResult, error)
}
type AudioDetectorSensor¶
AudioDetectorSensor is an audio sensor that consumes audio frames from the backend pipeline. Pair with an AudioDetector implementation.
type AudioDetectorSensor struct {
AudioSensor
}
func NewAudioDetectorSensor¶
func NewAudioDetectorSensor(name string) *AudioDetectorSensor
NewAudioDetectorSensor creates a new AudioDetectorSensor with the given name.
type AudioFormat¶
AudioFormat identifies the sample format of an audio buffer.
type AudioFormat string
Supported audio sample formats.
const (
AudioFormatPCM16 AudioFormat = "pcm16" // 16-bit signed integer PCM
AudioFormatFloat32 AudioFormat = "float32" // 32-bit float
)
type AudioFrameData¶
AudioFrameData is audio frame data delivered to audio detector sensors by the backend pipeline.
type AudioFrameData struct {
CameraID string `msgpack:"cameraId" json:"cameraId"` // Camera the frame originated from
Data []byte `msgpack:"data" json:"data"` // Raw audio sample buffer
SampleRate int `msgpack:"sampleRate" json:"sampleRate"` // Sample rate of the buffer in Hz
Channels int `msgpack:"channels" json:"channels"` // Channel count of the buffer (typically 1 = mono)
Format AudioFormat `msgpack:"format" json:"format"` // Sample format: pcm16 = 16-bit signed integer PCM, float32 = 32-bit float
Decibels float64 `msgpack:"decibels" json:"decibels"` // Pre-computed decibel level for this frame, if available
Timestamp int64 `msgpack:"timestamp" json:"timestamp"` // Capture timestamp in milliseconds since epoch
}
type AudioLabel¶
AudioLabel is one of the built-in audio labels or any custom string emitted by an audio detector.
type AudioLabel = string
type AudioModelSpec¶
AudioModelSpec describes an audio detection model.
type AudioModelSpec struct {
Input AudioInputSpec `msgpack:"input" json:"input"` // Required input audio format
}
type AudioResult¶
AudioResult is the return value of AudioDetector.DetectAudio.
type AudioResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether an audio event is detected in this frame
Detections []Detection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
Decibels float64 `msgpack:"decibels" json:"decibels"` // Optional decibel level computed for this frame
}
type AudioSensor¶
AudioSensor reports audio events and decibel levels.
Plugin authors call ReportDetections to push detected audio events (the `detected` flag is auto-derived from the list) and SetDecibels to publish the audio level.
type AudioSensor struct {
BaseSensor
}
func NewAudioSensor¶
func NewAudioSensor(name string) *AudioSensor
NewAudioSensor creates a new AudioSensor with the given name.
func (*AudioSensor) ClearDetections¶
func (s *AudioSensor) ClearDetections()
ClearDetections explicitly clears audio detection state (detected = false, detections = []).
func (*AudioSensor) GetCategory¶
func (s *AudioSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*AudioSensor) GetDecibels¶
func (s *AudioSensor) GetDecibels() float64
GetDecibels returns the current audio level in decibels.
func (*AudioSensor) GetDetections¶
func (s *AudioSensor) GetDetections() []Detection
GetDetections returns the current audio detections.
func (*AudioSensor) GetType¶
func (s *AudioSensor) GetType() SensorType
GetType returns SensorTypeAudio.
func (*AudioSensor) IsDetected¶
func (s *AudioSensor) IsDetected() bool
IsDetected reports whether an audio event is currently detected.
func (*AudioSensor) ReportDetections¶
func (s *AudioSensor) ReportDetections(detected bool, detections []Detection)
ReportDetections reports detected audio events.
- ReportDetections(true, nil) — audio detected without specifics. The SDK synthesizes a single full-frame "audio" detection.
- ReportDetections(true, [...]) — audio detected with explicit detections.
- ReportDetections(false, nil) — clear.
Example:
sensor.ReportDetections(true, []Detection{
{Label: "glass_break", Confidence: 0.91, Box: &BoundingBox{X: 0, Y: 0, Width: 1, Height: 1}},
})
sensor.ReportDetections(false, nil)
func (*AudioSensor) SetDecibels¶
func (s *AudioSensor) SetDecibels(value float64)
SetDecibels updates the current audio level (in decibels).
Example:
sensor.SetDecibels(72)
func (*AudioSensor) ToJSON¶
func (s *AudioSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*AudioSensor) UpdateValue¶
func (s *AudioSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only audio sensors. State is reported via ReportDetections / SetDecibels.
type BaseSensor¶
BaseSensor is the base struct for all sensors. Embed this in concrete sensor types.
type BaseSensor struct {
// contains filtered or unexported fields
}
func NewBaseSensor¶
func NewBaseSensor(name string) BaseSensor
NewBaseSensor creates a new BaseSensor with the given name.
func (*BaseSensor) GetCameraID¶
func (s *BaseSensor) GetCameraID() string
func (*BaseSensor) GetCapabilities¶
func (s *BaseSensor) GetCapabilities() []string
func (*BaseSensor) GetDisplayName¶
func (s *BaseSensor) GetDisplayName() string
func (*BaseSensor) GetID¶
func (s *BaseSensor) GetID() string
func (*BaseSensor) GetName¶
func (s *BaseSensor) GetName() string
func (*BaseSensor) GetPluginID¶
func (s *BaseSensor) GetPluginID() string
func (*BaseSensor) GetValue¶
func (s *BaseSensor) GetValue(property string) any
GetValue returns the current value of a sensor property.
func (*BaseSensor) GetValues¶
func (s *BaseSensor) GetValues() map[string]any
GetValues returns a snapshot of all property values.
Example:
snapshot := sensor.GetValues()
fmt.Println(snapshot)
func (*BaseSensor) HasCapability¶
func (s *BaseSensor) HasCapability(cap string) bool
HasCapability returns true if the sensor has the given capability.
func (*BaseSensor) IsAssigned¶
func (s *BaseSensor) IsAssigned() bool
IsAssigned returns whether this sensor is currently assigned to a camera.
func (*BaseSensor) OnAssignmentChanged¶
func (s *BaseSensor) OnAssignmentChanged(callback func(bool)) *Disposable
OnAssignmentChanged subscribes to assignment state changes. The callback receives true when the sensor is assigned to a camera, false when unassigned.
func (*BaseSensor) OnCapabilitiesChanged¶
func (s *BaseSensor) OnCapabilitiesChanged(callback func([]string)) *Disposable
OnCapabilitiesChanged returns a Disposable that fires when capabilities change.
func (*BaseSensor) OnPropertyChanged¶
func (s *BaseSensor) OnPropertyChanged(callback func(SensorPropertyChange)) *Disposable
OnPropertyChanged subscribes to property changes. Returns a Disposable to unsubscribe.
func (*BaseSensor) SetCapabilities¶
func (s *BaseSensor) SetCapabilities(caps []string)
func (*BaseSensor) SetDisplayName¶
func (s *BaseSensor) SetDisplayName(name string)
SetDisplayName sets the display name (the only mutable identifier on a sensor). name is the human-readable label shown in the UI.
Example:
sensor.SetDisplayName("Front Door Motion")
func (*BaseSensor) Storage¶
func (s *BaseSensor) Storage() *DeviceStorage
Storage returns the sensor's storage instance. Returns nil if storage has not been set yet (i.e. sensor not yet added to a camera).
type BatteryInfo¶
BatteryInfo reports battery level, charging state, and low-battery alerts.
type BatteryInfo struct{ BaseSensor }
func NewBatteryInfo¶
func NewBatteryInfo(name string) *BatteryInfo
NewBatteryInfo creates a new BatteryInfo.
func (*BatteryInfo) GetCategory¶
func (s *BatteryInfo) GetCategory() SensorCategory
func (*BatteryInfo) GetCharging¶
func (s *BatteryInfo) GetCharging() ChargingState
GetCharging returns the charging state.
func (*BatteryInfo) GetLevel¶
func (s *BatteryInfo) GetLevel() int
GetLevel returns the battery level (0–100).
func (*BatteryInfo) GetType¶
func (s *BatteryInfo) GetType() SensorType
func (*BatteryInfo) IsLow¶
func (s *BatteryInfo) IsLow() bool
IsLow returns whether the battery is critically low.
func (*BatteryInfo) SetCharging¶
func (s *BatteryInfo) SetCharging(value ChargingState)
SetCharging sets the charging state.
Example:
battery.SetCharging(ChargingStateCharging)
func (*BatteryInfo) SetLevel¶
func (s *BatteryInfo) SetLevel(value int)
SetLevel sets the battery level (clamped to [0,100]).
Example:
battery.SetLevel(87)
func (*BatteryInfo) SetLow¶
func (s *BatteryInfo) SetLow(value bool)
SetLow sets the low-battery alert flag.
Example:
battery.SetLow(true)
func (*BatteryInfo) ToJSON¶
func (s *BatteryInfo) ToJSON() sensorJSON
func (*BatteryInfo) UpdateValue¶
func (s *BatteryInfo) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only battery sensors.
type BoundingBox¶
BoundingBox is the bounding box of a detection. All coordinates are normalized to 0-1 (fraction of frame dimensions), so they are independent of resolution.
type BoundingBox struct {
X float64 `msgpack:"x" json:"x"` // X coordinate of the top-left corner (0-1)
Y float64 `msgpack:"y" json:"y"` // Y coordinate of the top-left corner (0-1)
Width float64 `msgpack:"width" json:"width"` // Width as a fraction of frame width (0-1)
Height float64 `msgpack:"height" json:"height"` // Height as a fraction of frame height (0-1)
}
type ChargingState¶
ChargingState defines battery charging states.
type ChargingState string
const (
ChargingStateNotCharging ChargingState = "NOT_CHARGING" // Battery is not charging
ChargingStateNotChargeable ChargingState = "NOT_CHARGEABLE" // Device has no rechargeable battery
ChargingStateCharging ChargingState = "CHARGING" // Battery is currently charging
ChargingStateFull ChargingState = "FULL" // Battery is fully charged
)
type ClassifierDetection¶
ClassifierDetection is a classifier detection result with an open attribute for classifier categories. The Attribute field of the embedded Detection holds the classifier category (e.g. "bird", "delivery").
type ClassifierDetection struct {
Detection
SubAttribute string `msgpack:"subAttribute" json:"subAttribute"` // Classifier sub-category (e.g. "woodpecker", "amazon")
}
type ClassifierDetector¶
ClassifierDetector is implemented by plugins that run image classification models against pre-cropped trigger regions.
type ClassifierDetector interface {
// ModelSpec declares the expected input dimensions and trigger labels. The
// runtime scales frames to match.
ModelSpec() ModelSpec
// DetectClassifications classifies a batch of pre-cropped, pre-scaled
// trigger regions and must return exactly one ClassifierResult per input
// frame, in the same order.
DetectClassifications(frames []VideoFrameData) ([]ClassifierResult, error)
}
type ClassifierDetectorSensor¶
ClassifierDetectorSensor is a classifier sensor that consumes video frames from the backend pipeline. Pair with a ClassifierDetector implementation.
type ClassifierDetectorSensor struct {
ClassifierSensor
}
func NewClassifierDetectorSensor¶
func NewClassifierDetectorSensor(name string) *ClassifierDetectorSensor
NewClassifierDetectorSensor creates a new ClassifierDetectorSensor with the given name.
type ClassifierResult¶
ClassifierResult is the return value of ClassifierDetector.DetectClassifications.
type ClassifierResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether any classification result is emitted for this frame
Detections []ClassifierDetection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
}
type ClassifierSensor¶
ClassifierSensor reports classification results from image analysis.
Plugin authors call ReportDetections to push classification results. The `detected` flag and `labels` are auto-derived from the detection list.
type ClassifierSensor struct{ BaseSensor }
func NewClassifierSensor¶
func NewClassifierSensor(name string) *ClassifierSensor
NewClassifierSensor creates a new ClassifierSensor with the given name.
func (*ClassifierSensor) ClearDetections¶
func (s *ClassifierSensor) ClearDetections()
ClearDetections explicitly clears classifier state (detected = false, detections = [], labels = []).
func (*ClassifierSensor) GetCategory¶
func (s *ClassifierSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*ClassifierSensor) GetDetections¶
func (s *ClassifierSensor) GetDetections() []ClassifierDetection
GetDetections returns the current classification results.
func (*ClassifierSensor) GetLabels¶
func (s *ClassifierSensor) GetLabels() []string
GetLabels returns the unique labels of the current detections.
func (*ClassifierSensor) GetType¶
func (s *ClassifierSensor) GetType() SensorType
GetType returns SensorTypeClassifier.
func (*ClassifierSensor) IsDetected¶
func (s *ClassifierSensor) IsDetected() bool
IsDetected reports whether any classification result is currently active.
func (*ClassifierSensor) ReportDetections¶
func (s *ClassifierSensor) ReportDetections(detected bool, detections []ClassifierDetection)
ReportDetections reports classification results. The `detected` flag and `labels` are auto-derived from the detection list.
- ReportDetections(true, nil) — generic classification trigger; the SDK synthesizes a single full-frame detection with empty attribute and sub-attribute.
- ReportDetections(true, [...]) — explicit classifier detections.
- ReportDetections(false, nil) — clear.
Example:
sensor.ReportDetections(true, []ClassifierDetection{
{Detection: Detection{Label: "animal", Confidence: 0.88, Box: &BoundingBox{X: 0.1, Y: 0.2, Width: 0.3, Height: 0.4}, Attribute: "bird"}, SubAttribute: "woodpecker"},
})
sensor.ReportDetections(false, nil)
func (*ClassifierSensor) ToJSON¶
func (s *ClassifierSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*ClassifierSensor) UpdateValue¶
func (s *ClassifierSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only classifier sensors. State is reported via ReportDetections.
type ClipDetector¶
ClipDetector is implemented by plugins that generate CLIP embeddings for downstream semantic search.
type ClipDetector interface {
// ModelSpec declares the expected input dimensions and trigger labels.
ModelSpec() ModelSpec
// DetectEmbeddings produces CLIP embeddings for a batch of pre-cropped,
// pre-scaled trigger regions. Must return exactly one ClipResult per
// input frame, in the same order; use VideoFrameData.Label to tag the
// emitted embedding.
DetectEmbeddings(frames []VideoFrameData) ([]ClipResult, error)
}
type ClipDetectorSensor¶
ClipDetectorSensor is a frame-only sensor that generates CLIP embeddings from video frames. Pair with a ClipDetector implementation.
type ClipDetectorSensor struct{ BaseSensor }
func NewClipDetectorSensor¶
func NewClipDetectorSensor(name string) *ClipDetectorSensor
NewClipDetectorSensor creates a new ClipDetectorSensor with the given name.
func (*ClipDetectorSensor) GetCategory¶
func (s *ClipDetectorSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*ClipDetectorSensor) GetType¶
func (s *ClipDetectorSensor) GetType() SensorType
GetType returns SensorTypeClip.
func (*ClipDetectorSensor) ToJSON¶
func (s *ClipDetectorSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*ClipDetectorSensor) UpdateValue¶
func (s *ClipDetectorSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op — the clip detector sensor has no externally writable properties.
type ClipEmbedding¶
ClipEmbedding is a CLIP embedding result for a detected region.
type ClipEmbedding struct {
Label string `msgpack:"label" json:"label"` // Detection label this embedding was computed for (e.g. "person", "vehicle")
Box BoundingBox `msgpack:"box" json:"box"` // Bounding box of the detected region in normalized coordinates
Embedding []float64 `msgpack:"embedding" json:"embedding"` // CLIP embedding vector
}
type ClipResult¶
ClipResult is the return value of ClipDetector.DetectEmbeddings.
type ClipResult struct {
Embeddings []ClipEmbedding `msgpack:"embeddings" json:"embeddings"` // Embeddings emitted for this frame
EmbeddingModel string `msgpack:"embeddingModel" json:"embeddingModel"` // Identifier of the embedding model used to produce the vectors
}
type ContactSensor¶
ContactSensor reports door/window open-close state.
type ContactSensor struct{ BaseSensor }
func NewContactSensor¶
func NewContactSensor(name string) *ContactSensor
NewContactSensor creates a new ContactSensor.
func (*ContactSensor) GetCategory¶
func (s *ContactSensor) GetCategory() SensorCategory
func (*ContactSensor) GetType¶
func (s *ContactSensor) GetType() SensorType
func (*ContactSensor) IsDetected¶
func (s *ContactSensor) IsDetected() bool
IsDetected returns whether the contact is open.
func (*ContactSensor) SetDetected¶
func (s *ContactSensor) SetDetected(detected bool)
SetDetected reports contact state (true = open, false = closed).
Example:
contact.SetDetected(true)
func (*ContactSensor) ToJSON¶
func (s *ContactSensor) ToJSON() sensorJSON
func (*ContactSensor) UpdateValue¶
func (s *ContactSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only contact sensors.
type Detection¶
Detection is a single detection result emitted by any detection sensor.
type Detection struct {
Label string `msgpack:"label" json:"label"` // Detection label (e.g. "person", "vehicle")
Confidence float64 `msgpack:"confidence" json:"confidence"` // Confidence score in the range 0-1
Box *BoundingBox `msgpack:"box,omitempty" json:"box,omitempty"` // Bounding box in normalized coordinates
Attribute string `msgpack:"attribute,omitempty" json:"attribute,omitempty"` // Optional sub-detection attribute (face, license_plate, or classifier-specific)
}
type DetectionAttribute¶
DetectionAttribute identifies the kind of a sub-detection (face, license plate, ...).
type DetectionAttribute = string
type DetectionLabel¶
DetectionLabel is a label identifying a type of detection.
type DetectionLabel = string
type DoorbellTrigger¶
DoorbellTrigger triggers doorbell ring events.
type DoorbellTrigger struct {
BaseSensor
// contains filtered or unexported fields
}
func NewDoorbellTrigger¶
func NewDoorbellTrigger(name string) *DoorbellTrigger
NewDoorbellTrigger creates a new DoorbellTrigger.
func (*DoorbellTrigger) GetCategory¶
func (s *DoorbellTrigger) GetCategory() SensorCategory
func (*DoorbellTrigger) GetType¶
func (s *DoorbellTrigger) GetType() SensorType
func (*DoorbellTrigger) IsRinging¶
func (s *DoorbellTrigger) IsRinging() bool
IsRinging returns whether the doorbell is currently ringing.
func (*DoorbellTrigger) ToJSON¶
func (s *DoorbellTrigger) ToJSON() sensorJSON
func (*DoorbellTrigger) Trigger¶
func (s *DoorbellTrigger) Trigger()
Trigger fires a doorbell ring event. Sets `ring=true` and auto-resets after ringAutoResetMs. Re-triggering while ringing resets the timer (extends the ring phase).
Example:
doorbell.Trigger()
func (*DoorbellTrigger) UpdateValue¶
func (s *DoorbellTrigger) UpdateValue(property string, value any) error
UpdateValue is the cross-process consumer entry point. Writing `ring=true` (any truthy value) dispatches to `Trigger()` so a UI test button or external automation can fire the doorbell using the same flow as a real hardware ring (auto-reset included). Writing `ring=false` is ignored — the auto-reset timer owns the off transition.
type FaceDetection¶
FaceDetection is a face detection result, extending Detection with face-specific fields. The Attribute field of the embedded Detection is fixed to "face".
type FaceDetection struct {
Detection
Identity string `msgpack:"identity,omitempty" json:"identity,omitempty"` // Recognized identity name, if matched against known faces
Embedding []float64 `msgpack:"embedding,omitempty" json:"embedding,omitempty"` // Face embedding vector for recognition/comparison
Thumbnail []byte `msgpack:"thumbnail,omitempty" json:"thumbnail,omitempty"` // JPEG thumbnail crop of the detected face
}
type FaceDetector¶
FaceDetector is implemented by plugins that perform face detection and recognition on pre-cropped person regions.
type FaceDetector interface {
// ModelSpec declares the expected input dimensions and trigger labels. The
// runtime scales frames to match.
ModelSpec() ModelSpec
// DetectFaces analyzes a batch of pre-cropped, pre-scaled person regions
// and must return exactly one FaceResult per input frame, in the same order.
DetectFaces(frames []VideoFrameData) ([]FaceResult, error)
}
type FaceDetectorSensor¶
FaceDetectorSensor is a face sensor that consumes video frames from the backend pipeline. Pair with a FaceDetector implementation.
type FaceDetectorSensor struct {
FaceSensor
}
func NewFaceDetectorSensor¶
func NewFaceDetectorSensor(name string) *FaceDetectorSensor
NewFaceDetectorSensor creates a new FaceDetectorSensor with the given name.
type FaceResult¶
FaceResult is the return value of FaceDetector.DetectFaces.
type FaceResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether any face is detected in this frame
Detections []FaceDetection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
}
type FaceSensor¶
FaceSensor reports detected faces and optional identity matches.
Plugin authors call ReportDetections to push detected faces. The `detected` flag is auto-derived from the detection list.
type FaceSensor struct{ BaseSensor }
func NewFaceSensor¶
func NewFaceSensor(name string) *FaceSensor
NewFaceSensor creates a new FaceSensor with the given name.
func (*FaceSensor) ClearDetections¶
func (s *FaceSensor) ClearDetections()
ClearDetections explicitly clears face detection state (detected = false, detections = []).
func (*FaceSensor) GetCategory¶
func (s *FaceSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*FaceSensor) GetDetections¶
func (s *FaceSensor) GetDetections() []FaceDetection
GetDetections returns the current face detections.
func (*FaceSensor) GetType¶
func (s *FaceSensor) GetType() SensorType
GetType returns SensorTypeFace.
func (*FaceSensor) IsDetected¶
func (s *FaceSensor) IsDetected() bool
IsDetected reports whether any face is currently detected.
func (*FaceSensor) ReportDetections¶
func (s *FaceSensor) ReportDetections(detected bool, detections []FaceDetection)
ReportDetections reports detected faces.
- ReportDetections(true, nil) — face detected without specifics; the SDK synthesizes a single full-frame face detection without identity.
- ReportDetections(true, [...]) — explicit face detections with identity, embedding, and/or thumbnail.
- ReportDetections(false, nil) — clear.
Example:
sensor.ReportDetections(true, []FaceDetection{
{Detection: Detection{Label: "person", Confidence: 0.94, Box: &BoundingBox{X: 0.4, Y: 0.2, Width: 0.15, Height: 0.25}, Attribute: "face"}, Identity: "Alice"},
})
sensor.ReportDetections(false, nil)
func (*FaceSensor) ToJSON¶
func (s *FaceSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*FaceSensor) UpdateValue¶
func (s *FaceSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only face sensors. State is reported via ReportDetections.
type GarageControl¶
GarageControl is a garage door control sensor. Override SetTargetState (by embedding GarageControl in your own type and shadowing the method) to drive hardware and call the embedded GarageControl's SetTargetState once the hardware confirms — the base implementation updates both targetState and currentState.
For long-running transitions (Opening/Closing intermediate states) override SetTargetState and write currentState separately as the door moves.
type GarageControl struct{ BaseSensor }
func NewGarageControl¶
func NewGarageControl(name string) *GarageControl
NewGarageControl creates a new GarageControl.
func (*GarageControl) GetCategory¶
func (s *GarageControl) GetCategory() SensorCategory
func (*GarageControl) GetCurrentState¶
func (s *GarageControl) GetCurrentState() GarageState
GetCurrentState returns the actual current garage door state.
func (*GarageControl) GetTargetState¶
func (s *GarageControl) GetTargetState() GarageState
GetTargetState returns the desired target garage door state.
func (*GarageControl) GetType¶
func (s *GarageControl) GetType() SensorType
func (*GarageControl) IsObstructionDetected¶
func (s *GarageControl) IsObstructionDetected() bool
IsObstructionDetected returns whether an obstruction is detected.
func (*GarageControl) SetCurrentState¶
func (s *GarageControl) SetCurrentState(value GarageState)
SetCurrentState publishes the actual door state. Use this to drive long-running transitions (e.g. Open → Closing → Closed) independently of the user-requested target state. Read-only from cross-process consumers (`UpdateValue` ignores it).
Example:
garage.SetCurrentState(GarageStateClosing)
func (*GarageControl) SetObstructionDetected¶
func (s *GarageControl) SetObstructionDetected(detected bool)
SetObstructionDetected publishes the obstruction detection state.
Example:
garage.SetObstructionDetected(true)
func (*GarageControl) SetTargetState¶
func (s *GarageControl) SetTargetState(value GarageState)
SetTargetState sets the target state. Writes both targetState and currentState.
Example:
garage.SetTargetState(GarageStateOpen)
func (*GarageControl) ToJSON¶
func (s *GarageControl) ToJSON() sensorJSON
func (*GarageControl) UpdateValue¶
func (s *GarageControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Only `targetState` is externally writable. Numeric values arriving via msgpack may be any int/uint/float width — `toInt64` normalizes them.
type GarageState¶
GarageState defines garage door states (HomeKit-compatible values).
type GarageState int
const (
GarageStateOpen GarageState = 0 // Garage door is open
GarageStateClosed GarageState = 1 // Garage door is closed
GarageStateOpening GarageState = 2 // Garage door is opening
GarageStateClosing GarageState = 3 // Garage door is closing
GarageStateStopped GarageState = 4 // Garage door is stopped
)
type HumidityInfo¶
HumidityInfo reports current relative humidity (0–100%).
type HumidityInfo struct{ BaseSensor }
func NewHumidityInfo¶
func NewHumidityInfo(name string) *HumidityInfo
NewHumidityInfo creates a new HumidityInfo.
func (*HumidityInfo) GetCategory¶
func (s *HumidityInfo) GetCategory() SensorCategory
func (*HumidityInfo) GetCurrent¶
func (s *HumidityInfo) GetCurrent() float64
GetCurrent returns the current relative humidity.
func (*HumidityInfo) GetType¶
func (s *HumidityInfo) GetType() SensorType
func (*HumidityInfo) SetCurrent¶
func (s *HumidityInfo) SetCurrent(value float64)
SetCurrent sets the current relative humidity (clamped to [0,100]).
func (*HumidityInfo) ToJSON¶
func (s *HumidityInfo) ToJSON() sensorJSON
func (*HumidityInfo) UpdateValue¶
func (s *HumidityInfo) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only humidity sensors.
type LeakSensor¶
LeakSensor reports water leak detection state.
type LeakSensor struct{ BaseSensor }
func NewLeakSensor¶
func NewLeakSensor(name string) *LeakSensor
NewLeakSensor creates a new LeakSensor.
func (*LeakSensor) GetCategory¶
func (s *LeakSensor) GetCategory() SensorCategory
func (*LeakSensor) GetType¶
func (s *LeakSensor) GetType() SensorType
func (*LeakSensor) IsDetected¶
func (s *LeakSensor) IsDetected() bool
IsDetected returns whether a leak is detected.
func (*LeakSensor) SetDetected¶
func (s *LeakSensor) SetDetected(detected bool)
SetDetected reports leak detection state (true when a water leak is currently detected).
Example:
leak.SetDetected(true)
func (*LeakSensor) ToJSON¶
func (s *LeakSensor) ToJSON() sensorJSON
func (*LeakSensor) UpdateValue¶
func (s *LeakSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only leak sensors.
type LicensePlateDetection¶
LicensePlateDetection is a license plate detection result, extending Detection with OCR fields. The Attribute field of the embedded Detection is fixed to "license_plate".
type LicensePlateDetection struct {
Detection
PlateText string `msgpack:"plateText,omitempty" json:"plateText,omitempty"` // Recognized plate text (e.g. "ABC 1234")
}
type LicensePlateDetector¶
LicensePlateDetector is implemented by plugins that perform license plate detection and OCR on pre-cropped vehicle regions.
type LicensePlateDetector interface {
// ModelSpec declares the expected input dimensions and trigger labels. The
// runtime scales frames to match.
ModelSpec() ModelSpec
// DetectLicensePlates analyzes a batch of pre-cropped, pre-scaled vehicle
// regions and must return exactly one LicensePlateResult per input frame,
// in the same order.
DetectLicensePlates(frames []VideoFrameData) ([]LicensePlateResult, error)
}
type LicensePlateDetectorSensor¶
LicensePlateDetectorSensor is a license plate sensor that consumes video frames from the backend pipeline. Pair with a LicensePlateDetector implementation.
type LicensePlateDetectorSensor struct {
LicensePlateSensor
}
func NewLicensePlateDetectorSensor¶
func NewLicensePlateDetectorSensor(name string) *LicensePlateDetectorSensor
NewLicensePlateDetectorSensor creates a new LicensePlateDetectorSensor with the given name.
type LicensePlateResult¶
LicensePlateResult is the return value of LicensePlateDetector.DetectLicensePlates.
type LicensePlateResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether any license plate is detected in this frame
Detections []LicensePlateDetection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
}
type LicensePlateSensor¶
LicensePlateSensor reports detected license plates and OCR results.
Plugin authors call ReportDetections to push detected plates. The `detected` flag is auto-derived from the detection list.
type LicensePlateSensor struct{ BaseSensor }
func NewLicensePlateSensor¶
func NewLicensePlateSensor(name string) *LicensePlateSensor
NewLicensePlateSensor creates a new LicensePlateSensor with the given name.
func (*LicensePlateSensor) ClearDetections¶
func (s *LicensePlateSensor) ClearDetections()
ClearDetections explicitly clears license plate state (detected = false, detections = []).
func (*LicensePlateSensor) GetCategory¶
func (s *LicensePlateSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*LicensePlateSensor) GetDetections¶
func (s *LicensePlateSensor) GetDetections() []LicensePlateDetection
GetDetections returns the current license plate detections.
func (*LicensePlateSensor) GetType¶
func (s *LicensePlateSensor) GetType() SensorType
GetType returns SensorTypeLicensePlate.
func (*LicensePlateSensor) IsDetected¶
func (s *LicensePlateSensor) IsDetected() bool
IsDetected reports whether any license plate is currently detected.
func (*LicensePlateSensor) ReportDetections¶
func (s *LicensePlateSensor) ReportDetections(detected bool, detections []LicensePlateDetection)
ReportDetections reports detected license plates.
- ReportDetections(true, nil) — plate detected without specifics; the SDK synthesizes a single full-frame detection with empty plateText.
- ReportDetections(true, [...]) — explicit plate detections with OCR text.
- ReportDetections(false, nil) — clear.
Example:
sensor.ReportDetections(true, []LicensePlateDetection{
{Detection: Detection{Label: "vehicle", Confidence: 0.93, Box: &BoundingBox{X: 0.2, Y: 0.5, Width: 0.2, Height: 0.08}, Attribute: "license_plate"}, PlateText: "ABC 1234"},
})
sensor.ReportDetections(false, nil)
func (*LicensePlateSensor) ToJSON¶
func (s *LicensePlateSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*LicensePlateSensor) UpdateValue¶
func (s *LicensePlateSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only license plate sensors. State is reported via ReportDetections.
type LightControl¶
LightControl is a light on/off and brightness control sensor. Override SetOn / SetOff (by embedding LightControl in your own type and shadowing the methods) to drive your hardware, then call the embedded LightControl's methods to sync the SDK state.
Plugins that have no hardware-action use case can leave the methods unoverridden — the base implementation just updates the state.
For hardware-pushed updates (someone manually flipped the switch), call the embedded LightControl's SetOn / SetOff directly from your event handler — that bypasses any plugin override and only syncs state.
type LightControl struct{ BaseSensor }
func NewLightControl¶
func NewLightControl(name string) *LightControl
NewLightControl creates a new LightControl.
func (*LightControl) GetBrightness¶
func (s *LightControl) GetBrightness() int
GetBrightness returns the brightness level (0–100).
func (*LightControl) GetCategory¶
func (s *LightControl) GetCategory() SensorCategory
func (*LightControl) GetType¶
func (s *LightControl) GetType() SensorType
func (*LightControl) IsOn¶
func (s *LightControl) IsOn() bool
IsOn returns whether the light is on.
func (*LightControl) SetBrightness¶
func (s *LightControl) SetBrightness(value int)
SetBrightness sets the brightness level (clamped to [0, 100]). Override (via embedding) to drive hardware and call the embedded LightControl's SetBrightness to sync the SDK state.
Example:
light.SetBrightness(75)
func (*LightControl) SetOff¶
func (s *LightControl) SetOff()
SetOff turns the light off. Override (via embedding) to drive hardware and call the embedded LightControl's SetOff to sync the SDK state.
Example:
light.SetOff()
func (*LightControl) SetOn¶
func (s *LightControl) SetOn()
SetOn turns the light on. Override (via embedding) to drive hardware and call the embedded LightControl's SetOn to sync the SDK state.
Example:
light.SetOn()
func (*LightControl) ToJSON¶
func (s *LightControl) ToJSON() sensorJSON
func (*LightControl) UpdateValue¶
func (s *LightControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Numeric values arriving via msgpack may be any int/uint/float width — `toInt64` normalizes them. Boolean values are checked directly.
type LockControl¶
LockControl is a lock/unlock control sensor. Override SetTargetState (by embedding LockControl in your own type and shadowing the method) to drive hardware and call the embedded LockControl's SetTargetState once the hardware confirms — the base implementation updates both targetState and currentState to the new value.
For asymmetric flows (long-running unlock with intermediate state) override SetTargetState and write currentState separately when transitions complete.
type LockControl struct{ BaseSensor }
func NewLockControl¶
func NewLockControl(name string) *LockControl
NewLockControl creates a new LockControl.
func (*LockControl) GetCategory¶
func (s *LockControl) GetCategory() SensorCategory
func (*LockControl) GetCurrentState¶
func (s *LockControl) GetCurrentState() LockState
GetCurrentState returns the current lock state.
func (*LockControl) GetTargetState¶
func (s *LockControl) GetTargetState() LockState
GetTargetState returns the target lock state.
func (*LockControl) GetType¶
func (s *LockControl) GetType() SensorType
func (*LockControl) SetCurrentState¶
func (s *LockControl) SetCurrentState(value LockState)
SetCurrentState publishes the actual lock state. Use this to drive transitions where the physical state diverges from the user-requested target — e.g. motorized smart locks that take time to rotate (publish LockStateUnknown while moving), or hardware reporting an out-of-band state change. Read-only from cross-process consumers (`UpdateValue` ignores it).
Example:
lock.SetCurrentState(LockStateUnknown)
func (*LockControl) SetTargetState¶
func (s *LockControl) SetTargetState(value LockState)
SetTargetState sets the target lock state. Writes both targetState and currentState.
Example:
lock.SetTargetState(LockStateSecured)
func (*LockControl) ToJSON¶
func (s *LockControl) ToJSON() sensorJSON
func (*LockControl) UpdateValue¶
func (s *LockControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Numeric values arriving via msgpack may be any int/uint/float width — the `toInt64` helper normalizes them so the LockState cast is consistent.
type LockState¶
LockState defines lock states (HomeKit-compatible values).
type LockState int
const (
LockStateSecured LockState = 0 // Lock is secured (locked)
LockStateUnsecured LockState = 1 // Lock is unsecured (unlocked)
LockStateUnknown LockState = 2 // Lock state is unknown
)
type ModelSpec¶
ModelSpec describes a detection model with fixed output labels (face, classifier, license plate). It declares the input shape the backend should produce and the trigger labels that should activate this detector.
type ModelSpec struct {
Input VideoInputSpec `msgpack:"input" json:"input"` // Required input frame dimensions and pixel format
TriggerLabels []string `msgpack:"triggerLabels" json:"triggerLabels"` // Labels emitted by an upstream object detector that activate this detector
EmbeddingModel string `msgpack:"embeddingModel,omitempty" json:"embeddingModel,omitempty"` // Embedding model identifier for face recognition
}
type MotionDetector¶
MotionDetector is implemented by plugins that analyze video frames for motion. The runtime calls DetectMotion at the configured frame interval and applies the returned MotionResult to the associated MotionSensor.
type MotionDetector interface {
// DetectMotion analyzes a single video frame and returns the motion result.
DetectMotion(frame VideoFrameData) (*MotionResult, error)
}
type MotionDetectorSensor¶
MotionDetectorSensor is a motion sensor that consumes video frames from the backend pipeline. Pair with a MotionDetector implementation; the backend invokes the detector at the configured frame interval and forwards results to this sensor.
type MotionDetectorSensor struct {
MotionSensor
}
func NewMotionDetectorSensor¶
func NewMotionDetectorSensor(name string) *MotionDetectorSensor
NewMotionDetectorSensor creates a new MotionDetectorSensor with the given name.
type MotionResult¶
MotionResult is the return value of MotionDetector.DetectMotion.
type MotionResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether motion is detected in this frame
Detections []Detection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
}
type MotionSensor¶
MotionSensor reports motion state and detection results.
Plugin authors call ReportDetections to push detection results. The `detected` flag is auto-derived from the detection list. `blocked` is read-only and is set by the backend (dwell logic) — ReportDetections becomes a no-op while the sensor is blocked.
type MotionSensor struct {
BaseSensor
}
func NewMotionSensor¶
func NewMotionSensor(name string) *MotionSensor
NewMotionSensor creates a new MotionSensor with the given name.
func (*MotionSensor) ClearDetections¶
func (s *MotionSensor) ClearDetections()
ClearDetections explicitly clears motion state (detected = false, detections = []).
func (*MotionSensor) GetCategory¶
func (s *MotionSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*MotionSensor) GetDetections¶
func (s *MotionSensor) GetDetections() []Detection
GetDetections returns the current motion detections.
func (*MotionSensor) GetType¶
func (s *MotionSensor) GetType() SensorType
GetType returns SensorTypeMotion.
func (*MotionSensor) IsBlocked¶
func (s *MotionSensor) IsBlocked() bool
IsBlocked reports whether the sensor is currently blocked by the backend dwell logic.
func (*MotionSensor) IsDetected¶
func (s *MotionSensor) IsDetected() bool
IsDetected reports whether motion is currently detected.
func (*MotionSensor) ReportDetections¶
func (s *MotionSensor) ReportDetections(detected bool, detections []Detection)
ReportDetections reports a motion detection result.
- ReportDetections(true, nil) — motion detected without bounding box. The SDK synthesizes a single full-frame "motion" detection.
- ReportDetections(true, [...]) — motion detected with explicit detections.
- ReportDetections(false, nil) — no motion (clears detections).
No-op while the sensor is blocked by the backend dwell logic.
Example:
sensor.ReportDetections(true, []Detection{
{Label: "motion", Confidence: 0.85, Box: &BoundingBox{X: 0.1, Y: 0.2, Width: 0.3, Height: 0.4}},
})
sensor.ReportDetections(false, nil)
func (*MotionSensor) ToJSON¶
func (s *MotionSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*MotionSensor) UpdateValue¶
func (s *MotionSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only motion sensors. State is reported via ReportDetections.
type ObjectDetector¶
ObjectDetector is implemented by plugins that detect objects in video frames. The runtime scales frames to match ModelSpec before each call.
type ObjectDetector interface {
// ModelSpec declares the expected input dimensions.
ModelSpec() ObjectModelSpec
// DetectObjects analyzes a single video frame and returns the object result.
DetectObjects(frame VideoFrameData) (*ObjectResult, error)
}
type ObjectDetectorSensor¶
ObjectDetectorSensor is an object sensor that consumes video frames from the backend pipeline. Pair with an ObjectDetector implementation.
type ObjectDetectorSensor struct {
ObjectSensor
}
func NewObjectDetectorSensor¶
func NewObjectDetectorSensor(name string) *ObjectDetectorSensor
NewObjectDetectorSensor creates a new ObjectDetectorSensor with the given name.
type ObjectModelSpec¶
ObjectModelSpec describes an object detection model. Only declares input dimensions — the output label set is dynamic and comes from the model itself.
type ObjectModelSpec struct {
Input VideoInputSpec `msgpack:"input" json:"input"` // Required input frame dimensions and pixel format
}
type ObjectResult¶
ObjectResult is the return value of ObjectDetector.DetectObjects.
type ObjectResult struct {
Detected bool `msgpack:"detected" json:"detected"` // Whether any object is detected in this frame
Detections []TrackedDetection `msgpack:"detections" json:"detections"` // Detections emitted for this frame
}
type ObjectSensor¶
ObjectSensor reports detected objects (person, vehicle, animal, etc.).
Plugin authors call ReportDetections to push detection results. The `detected` flag and `labels` are auto-derived from the detection list.
type ObjectSensor struct {
BaseSensor
}
func NewObjectSensor¶
func NewObjectSensor(name string) *ObjectSensor
NewObjectSensor creates a new ObjectSensor with the given name.
func (*ObjectSensor) ClearDetections¶
func (s *ObjectSensor) ClearDetections()
ClearDetections explicitly clears detection state (detected = false, detections = [], labels = []).
func (*ObjectSensor) GetCategory¶
func (s *ObjectSensor) GetCategory() SensorCategory
GetCategory returns SensorCategorySensor.
func (*ObjectSensor) GetDetections¶
func (s *ObjectSensor) GetDetections() []TrackedDetection
GetDetections returns the current object detections.
func (*ObjectSensor) GetLabels¶
func (s *ObjectSensor) GetLabels() []string
GetLabels returns the unique labels of the current detections.
func (*ObjectSensor) GetType¶
func (s *ObjectSensor) GetType() SensorType
GetType returns SensorTypeObject.
func (*ObjectSensor) IsDetected¶
func (s *ObjectSensor) IsDetected() bool
IsDetected reports whether any object is currently detected.
func (*ObjectSensor) ReportDetections¶
func (s *ObjectSensor) ReportDetections(detected bool, detections []TrackedDetection)
ReportDetections reports detected objects. The `detected` flag and `labels` are auto-derived from the detection list.
- ReportDetections(true, nil) — generic trigger; synthesizes a single full-frame "motion" detection as a fallback.
- ReportDetections(true, [...]) — explicit detections.
- ReportDetections(false, nil) — clear.
Example:
sensor.ReportDetections(true, []TrackedDetection{
{Detection: Detection{Label: "person", Confidence: 0.92, Box: &BoundingBox{X: 0.1, Y: 0.2, Width: 0.3, Height: 0.4}}},
})
sensor.ReportDetections(false, nil)
func (*ObjectSensor) ToJSON¶
func (s *ObjectSensor) ToJSON() sensorJSON
ToJSON serializes this sensor to a JSON-safe representation for RPC transport.
func (*ObjectSensor) UpdateValue¶
func (s *ObjectSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only object sensors. State is reported via ReportDetections.
type OccupancySensor¶
OccupancySensor reports occupancy/presence state.
type OccupancySensor struct{ BaseSensor }
func NewOccupancySensor¶
func NewOccupancySensor(name string) *OccupancySensor
NewOccupancySensor creates a new OccupancySensor.
func (*OccupancySensor) GetCategory¶
func (s *OccupancySensor) GetCategory() SensorCategory
func (*OccupancySensor) GetType¶
func (s *OccupancySensor) GetType() SensorType
func (*OccupancySensor) IsDetected¶
func (s *OccupancySensor) IsDetected() bool
IsDetected returns whether occupancy is detected.
func (*OccupancySensor) SetDetected¶
func (s *OccupancySensor) SetDetected(detected bool)
SetDetected reports occupancy state (true when the area is currently occupied).
Example:
occupancy.SetDetected(true)
func (*OccupancySensor) ToJSON¶
func (s *OccupancySensor) ToJSON() sensorJSON
func (*OccupancySensor) UpdateValue¶
func (s *OccupancySensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only occupancy sensors.
type PTZControl¶
PTZControl is a pan-tilt-zoom camera control sensor. Override SetPosition / SetVelocity / SetTargetPreset (by embedding PTZControl in your own type and shadowing the methods) to drive hardware, then call the corresponding embedded method after success to sync the SDK state. For hardware-pushed state updates (e.g. PTZ position change events), call the embedded methods directly from your event handler — that bypasses any plugin override and only syncs state.
Set capabilities to advertise supported axes and features. Use SetPresets to publish the discovered preset list and SetMoving to publish movement state.
type PTZControl struct{ BaseSensor }
func NewPTZControl¶
func NewPTZControl(name string) *PTZControl
NewPTZControl creates a new PTZControl.
func (*PTZControl) GetCategory¶
func (s *PTZControl) GetCategory() SensorCategory
func (*PTZControl) GetPosition¶
func (s *PTZControl) GetPosition() PTZPosition
GetPosition returns the current PTZ position.
func (*PTZControl) GetPresets¶
func (s *PTZControl) GetPresets() []string
GetPresets returns the list of available preset names.
func (*PTZControl) GetType¶
func (s *PTZControl) GetType() SensorType
func (*PTZControl) GoHome¶
func (s *PTZControl) GoHome()
GoHome moves the PTZ to the home position (0, 0, 0).
Example:
ptz.GoHome()
func (*PTZControl) IsMoving¶
func (s *PTZControl) IsMoving() bool
IsMoving returns whether the PTZ is currently moving.
func (*PTZControl) SetMoving¶
func (s *PTZControl) SetMoving(value bool)
SetMoving publishes the movement state.
Example:
ptz.SetMoving(true)
func (*PTZControl) SetPosition¶
func (s *PTZControl) SetPosition(value PTZPosition)
SetPosition sets the absolute PTZ position.
Example:
ptz.SetPosition(PTZPosition{Pan: 0.25, Tilt: -0.1, Zoom: 0.5})
func (*PTZControl) SetPresets¶
func (s *PTZControl) SetPresets(value []string)
SetPresets publishes the discovered preset list.
Example:
ptz.SetPresets([]string{"Home", "Driveway", "Backyard"})
func (*PTZControl) SetTargetPreset¶
func (s *PTZControl) SetTargetPreset(value string)
SetTargetPreset sets the target preset ID.
Example:
ptz.SetTargetPreset("Driveway")
func (*PTZControl) SetVelocity¶
func (s *PTZControl) SetVelocity(value PTZDirection)
SetVelocity sets the continuous-move velocity.
Example:
ptz.SetVelocity(PTZDirection{PanSpeed: 0.5, TiltSpeed: 0, ZoomSpeed: 0})
func (*PTZControl) ToJSON¶
func (s *PTZControl) ToJSON() sensorJSON
func (*PTZControl) UpdateValue¶
func (s *PTZControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Only Position, Velocity, and TargetPreset are externally writable.
type SecuritySystem¶
SecuritySystem is a security system arm/disarm control sensor.
type SecuritySystem struct{ BaseSensor }
func NewSecuritySystem¶
func NewSecuritySystem(name string) *SecuritySystem
NewSecuritySystem creates a new SecuritySystem.
func (*SecuritySystem) GetCategory¶
func (s *SecuritySystem) GetCategory() SensorCategory
func (*SecuritySystem) GetCurrentState¶
func (s *SecuritySystem) GetCurrentState() SecuritySystemState
GetCurrentState returns the current security system state.
func (*SecuritySystem) GetTargetState¶
func (s *SecuritySystem) GetTargetState() SecuritySystemState
GetTargetState returns the target security system state.
func (*SecuritySystem) GetType¶
func (s *SecuritySystem) GetType() SensorType
func (*SecuritySystem) SetCurrentState¶
func (s *SecuritySystem) SetCurrentState(value SecuritySystemState)
SetCurrentState publishes the actual security system state. Use this to drive transitions that diverge from the user-requested target — most notably the AlarmTriggered state when an intruder is detected, or arming-delay intermediate states. Read-only from cross-process consumers (`UpdateValue` ignores it).
Example:
alarm.SetCurrentState(SecuritySystemStateAlarmTriggered)
func (*SecuritySystem) SetTargetState¶
func (s *SecuritySystem) SetTargetState(value SecuritySystemState)
SetTargetState sets the target state. Writes both targetState and currentState.
Example:
alarm.SetTargetState(SecuritySystemStateAwayArm)
func (*SecuritySystem) ToJSON¶
func (s *SecuritySystem) ToJSON() sensorJSON
func (*SecuritySystem) UpdateValue¶
func (s *SecuritySystem) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Numeric values arriving via msgpack may be any int/uint/float width — `toInt64` normalizes them.
type SecuritySystemState¶
SecuritySystemState defines security system states.
type SecuritySystemState int
const (
SecuritySystemStateStayArm SecuritySystemState = 0 // Armed, occupants home
SecuritySystemStateAwayArm SecuritySystemState = 1 // Armed, occupants away
SecuritySystemStateNightArm SecuritySystemState = 2 // Armed for night mode
SecuritySystemStateDisarmed SecuritySystemState = 3 // System disarmed
SecuritySystemStateAlarmTriggered SecuritySystemState = 4 // Alarm is triggered
)
type Sensor¶
Sensor is the interface all sensors must implement.
Plugin-author state-modifying methods (`SetOn`, `ReportDetections`, etc.) live on the concrete sensor types, not on Sensor. Code that holds a Sensor reference can READ state and observe changes, plus invoke `UpdateValue` for cross-process generic property writes (HomeKit bridge etc.).
type Sensor interface {
GetID() string
GetType() SensorType
GetCategory() SensorCategory
GetName() string
GetDisplayName() string
SetDisplayName(name string)
GetPluginID() string
GetCameraID() string
GetCapabilities() []string
SetCapabilities(caps []string)
HasCapability(cap string) bool
// GetValue returns the current value of a sensor property.
GetValue(property string) any
// GetValues returns a snapshot of all property values.
GetValues() map[string]any
// UpdateValue is the cross-process consumer entry point. Concrete sensor types
// implement it to dispatch known properties to semantic methods (`SetOn`,
// `SetTargetState`, ...) so plugin-side hardware-action overrides are honored.
// Read-only sensors implement it as a no-op. Plugin authors **must not** call
// this — they should call the semantic methods directly.
UpdateValue(property string, value any) error
OnPropertyChanged(callback func(SensorPropertyChange)) *Disposable
OnCapabilitiesChanged(callback func([]string)) *Disposable
OnAssignmentChanged(callback func(bool)) *Disposable
ToJSON() sensorJSON
}
type SensorCategory¶
SensorCategory categorizes a sensor's role in the system.
type SensorCategory string
const (
SensorCategorySensor SensorCategory = "sensor" // Reports detected state (read-only from user perspective)
SensorCategoryControl SensorCategory = "control" // Accepts commands (light, PTZ, siren, etc.)
SensorCategoryTrigger SensorCategory = "trigger" // Fires one-shot events (doorbell ring)
SensorCategoryInfo SensorCategory = "info" // Read-only informational data (battery level)
)
type SensorTriggerRef¶
SensorTriggerRef is a stable reference to a sensor for cascade trigger configuration. Uses composite key (sensorType + sensorName + pluginId) instead of UUID so references survive plugin restarts.
type SensorTriggerRef struct {
// SensorType is the sensor type (e.g. "contact", "doorbell").
SensorType SensorType `msgpack:"sensorType" json:"sensorType"`
// SensorName is the sensor name (stable across restarts).
SensorName string `msgpack:"sensorName" json:"sensorName"`
// PluginID is the plugin ID that provides this sensor.
PluginID string `msgpack:"pluginId" json:"pluginId"`
}
type SensorTriggerSettings¶
SensorTriggerSettings is configuration for sensor cascade triggers (contact, doorbell, switch, light, etc.).
type SensorTriggerSettings struct {
// Timeout is the sensor trigger timeout in seconds.
Timeout int `msgpack:"timeout" json:"timeout"`
// Triggers are sensors that also trigger the detection cascade (in addition to motion/audio).
Triggers []SensorTriggerRef `msgpack:"triggers" json:"triggers"`
}
type SensorType¶
SensorType identifies the kind of sensor. Each maps to a smart-home concept.
type SensorType string
const (
SensorTypeMotion SensorType = "motion" // Video-based motion detection
SensorTypeObject SensorType = "object" // Object detection (person, vehicle, animal, etc.)
SensorTypeAudio SensorType = "audio" // Audio event detection
SensorTypeFace SensorType = "face" // Face detection and recognition
SensorTypeLicensePlate SensorType = "licensePlate" // License plate detection and OCR
SensorTypeClassifier SensorType = "classifier" // Generic image classification
SensorTypeClip SensorType = "clip" // CLIP embedding generation
SensorTypeContact SensorType = "contact" // Door/window open-close contact sensor
SensorTypeLight SensorType = "light" // Light on/off and brightness control
SensorTypeSiren SensorType = "siren" // Siren on/off and volume control
SensorTypeSwitch SensorType = "switch" // Generic on/off switch
SensorTypeLock SensorType = "lock" // Lock/unlock control
SensorTypePTZ SensorType = "ptz" // Pan-tilt-zoom camera control
SensorTypeSecuritySystem SensorType = "securitySystem" // Security system arm/disarm control
SensorTypeDoorbell SensorType = "doorbell" // Doorbell ring trigger
SensorTypeTemperature SensorType = "temperature" // Temperature sensor (°C)
SensorTypeHumidity SensorType = "humidity" // Humidity sensor (0–100%)
SensorTypeOccupancy SensorType = "occupancy" // Occupancy/presence sensor
SensorTypeSmoke SensorType = "smoke" // Smoke detector
SensorTypeLeak SensorType = "leak" // Water leak detector
SensorTypeGarage SensorType = "garage" // Garage door opener
SensorTypeBattery SensorType = "battery" // Battery level and charging state
)
type SirenControl¶
SirenControl is a siren on/off and volume control sensor. Override SetActive / SetInactive (by embedding SirenControl in your own type and shadowing the methods) to drive your hardware, then call the embedded SirenControl's methods to sync the SDK state. For hardware-pushed updates, call the embedded methods directly from your event handler — that bypasses any plugin override and only syncs state.
type SirenControl struct{ BaseSensor }
func NewSirenControl¶
func NewSirenControl(name string) *SirenControl
NewSirenControl creates a new SirenControl.
func (*SirenControl) GetCategory¶
func (s *SirenControl) GetCategory() SensorCategory
func (*SirenControl) GetType¶
func (s *SirenControl) GetType() SensorType
func (*SirenControl) GetVolume¶
func (s *SirenControl) GetVolume() int
GetVolume returns the siren volume (0–100).
func (*SirenControl) IsActive¶
func (s *SirenControl) IsActive() bool
IsActive returns whether the siren is active.
func (*SirenControl) SetActive¶
func (s *SirenControl) SetActive()
SetActive activates the siren.
Example:
siren.SetActive()
func (*SirenControl) SetInactive¶
func (s *SirenControl) SetInactive()
SetInactive deactivates the siren.
Example:
siren.SetInactive()
func (*SirenControl) SetVolume¶
func (s *SirenControl) SetVolume(value int)
SetVolume sets the siren volume (clamped to [0,100]).
Example:
siren.SetVolume(80)
func (*SirenControl) ToJSON¶
func (s *SirenControl) ToJSON() sensorJSON
func (*SirenControl) UpdateValue¶
func (s *SirenControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Numeric values arriving via msgpack may be any int/uint/float width — `toInt64` normalizes them. Boolean values are checked directly.
type SmokeSensor¶
SmokeSensor reports smoke detection state.
type SmokeSensor struct{ BaseSensor }
func NewSmokeSensor¶
func NewSmokeSensor(name string) *SmokeSensor
NewSmokeSensor creates a new SmokeSensor.
func (*SmokeSensor) GetCategory¶
func (s *SmokeSensor) GetCategory() SensorCategory
func (*SmokeSensor) GetType¶
func (s *SmokeSensor) GetType() SensorType
func (*SmokeSensor) IsDetected¶
func (s *SmokeSensor) IsDetected() bool
IsDetected returns whether smoke is detected.
func (*SmokeSensor) SetDetected¶
func (s *SmokeSensor) SetDetected(detected bool)
SetDetected reports smoke detection state (true when smoke is currently detected).
Example:
smoke.SetDetected(true)
func (*SmokeSensor) ToJSON¶
func (s *SmokeSensor) ToJSON() sensorJSON
func (*SmokeSensor) UpdateValue¶
func (s *SmokeSensor) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only smoke sensors.
type SwitchControl¶
SwitchControl is a generic on/off switch control sensor. Override SetOn / SetOff (by embedding SwitchControl in your own type and shadowing the methods) to drive hardware, then call the embedded SwitchControl's methods to sync the SDK state. For hardware-pushed updates, call the embedded methods directly from your event handler — that bypasses any plugin override and only syncs state.
type SwitchControl struct{ BaseSensor }
func NewSwitchControl¶
func NewSwitchControl(name string) *SwitchControl
NewSwitchControl creates a new SwitchControl.
func (*SwitchControl) GetCategory¶
func (s *SwitchControl) GetCategory() SensorCategory
func (*SwitchControl) GetType¶
func (s *SwitchControl) GetType() SensorType
func (*SwitchControl) IsOn¶
func (s *SwitchControl) IsOn() bool
IsOn returns whether the switch is on.
func (*SwitchControl) SetOff¶
func (s *SwitchControl) SetOff()
SetOff turns the switch off.
Example:
sw.SetOff()
func (*SwitchControl) SetOn¶
func (s *SwitchControl) SetOn()
SetOn turns the switch on.
Example:
sw.SetOn()
func (*SwitchControl) ToJSON¶
func (s *SwitchControl) ToJSON() sensorJSON
func (*SwitchControl) UpdateValue¶
func (s *SwitchControl) UpdateValue(property string, value any) error
UpdateValue dispatches generic property writes to semantic methods. Numeric values arriving via msgpack may be any int/uint/float width — `toInt64` normalizes them. Boolean values are checked directly.
type TemperatureInfo¶
TemperatureInfo reports current temperature in °C.
type TemperatureInfo struct{ BaseSensor }
func NewTemperatureInfo¶
func NewTemperatureInfo(name string) *TemperatureInfo
NewTemperatureInfo creates a new TemperatureInfo.
func (*TemperatureInfo) GetCategory¶
func (s *TemperatureInfo) GetCategory() SensorCategory
func (*TemperatureInfo) GetCurrent¶
func (s *TemperatureInfo) GetCurrent() float64
GetCurrent returns the current temperature in °C.
func (*TemperatureInfo) GetType¶
func (s *TemperatureInfo) GetType() SensorType
func (*TemperatureInfo) SetCurrent¶
func (s *TemperatureInfo) SetCurrent(value float64)
SetCurrent sets the current temperature (clamped to [-270,100]).
func (*TemperatureInfo) ToJSON¶
func (s *TemperatureInfo) ToJSON() sensorJSON
func (*TemperatureInfo) UpdateValue¶
func (s *TemperatureInfo) UpdateValue(property string, value any) error
UpdateValue is a no-op for read-only temperature sensors.
type TrackVelocity¶
TrackVelocity is the signed centroid velocity vector in normalized units per frame. Positive X = moving right, positive Y = moving down. Consumers doing motion prediction (PTZ autotrack, trajectory estimation) should use this instead of deriving velocity from frame-to-frame position deltas.
type TrackVelocity struct {
X float64 `msgpack:"x" json:"x"`
Y float64 `msgpack:"y" json:"y"`
}
type TrackedDetection¶
TrackedDetection extends Detection with tracking metadata (stable IDs, velocity). Tracking fields are omitempty — plugins return plain Detection, and the server-side tracker fills these in.
type TrackedDetection struct {
Detection
TrackId *int `msgpack:"trackId,omitempty" json:"trackId,omitempty"` // Stable sequential ID for this object across frames
TrackAge *int `msgpack:"trackAge,omitempty" json:"trackAge,omitempty"` // Number of frames this object has been continuously tracked
TrackSpeed *float64 `msgpack:"trackSpeed,omitempty" json:"trackSpeed,omitempty"` // Velocity magnitude in normalized units per frame; 0 = stationary
TrackVelocity *TrackVelocity `msgpack:"trackVelocity,omitempty" json:"trackVelocity,omitempty"` // Signed centroid velocity vector in normalized units per frame
TrackLost *bool `msgpack:"trackLost,omitempty" json:"trackLost,omitempty"` // True if the object was not matched in the current frame
}