controller

Documentation

Overview

Package controller provides a framework for managing entity-driven connectors.

It uses the engine's WatchEntities RPC to watch a specific entity by ID, starting the run function when the entity appears and restarting it when the entity's Config changes.

Index

• func Push(ctx context.Context, entities ...*pb.Entity) error
• func Run(ctx context.Context, entityID string, run RunFunc, opts ...Option) error
• func RunPolled(ctx context.Context, entityID string, run PollFunc) error
• func WatchChildren(ctx context.Context, serviceEntityID, controllerName string, ...) error
• type ChildHandler
• type DeviceClass
• type Option
  • func WithOnUpdate(fn func(*pb.Entity)) Option
• type PollFunc
• type RunFunc

Functions

func Push

func Push(ctx context.Context, entities ...*pb.Entity) error

Push pushes one or more entities to the world service.

func Run

func Run(ctx context.Context, entityID string, run RunFunc, opts ...Option) error

Run watches a single entity by ID using WatchEntities and runs the provided function when the entity has a Config. If the Config changes, the running function is cancelled and restarted.

func RunPolled

func RunPolled(ctx context.Context, entityID string, run PollFunc) error

RunPolled watches a single entity by ID using WatchEntities and runs a polling loop when the entity has a Config. The PollFunc is called once per cycle; the interval between cycles is determined by the PollFunc's return value.

func WatchChildren

func WatchChildren(ctx context.Context, serviceEntityID, controllerName string, classes []DeviceClass, handler ChildHandler) error

WatchChildren watches for device entities parented to serviceEntityID. When a child with a recognized device_class appears, it pushes ConfigurableComponent (schema for that class) + Controller onto it and starts handler(ctx, entityID) in a goroutine. When the child expires or is unobserved, the handler's context is cancelled.

Types

type ChildHandler

type ChildHandler func(ctx context.Context, entityID string) error

ChildHandler is called per child device. It should block until done or ctx cancelled.

type DeviceClass

type DeviceClass struct {
	Class  string
	Label  string
	Schema *structpb.Struct
}

DeviceClass describes one type of child device that a service supports.

type Option

type Option func(*runConfig)

Option configures optional behavior for Run.

func WithOnUpdate

func WithOnUpdate(fn func(*pb.Entity)) Option

WithOnUpdate registers a callback that is invoked for every entity update that does not change Config (i.e. non-restart updates). This allows the running function to react to component changes like PTZ commands. The callback is only called while the run function is active.

type PollFunc

type PollFunc func(ctx context.Context, entity *pb.Entity) (time.Duration, error)

PollFunc does one unit of work (one sweep, one poll). It returns the desired delay before the next poll and an error. On error, the framework retries with backoff (ignoring the returned duration). On success, the framework waits for the returned duration before calling again. A duration <= 0 is treated as 30s.

type RunFunc

type RunFunc func(ctx context.Context, entity *pb.Entity, ready func()) error

RunFunc is called for each entity that has Config on this controller. It should block until done or ctx is cancelled. On error, the framework retries with backoff. The function must call ready() once it has validated the configuration and is operational. If it returns an error without calling ready(), the error is treated as a configuration validation failure.