Interface Controller<M>

A Controller represents a somewhat more complex arrangement of multiple services which together form a accessory like for example cameras, remotes, tvs or routers. Controllers implementing this interface are capable of being serialized and thus stored on and recreated from disk. Meaning services, characteristic configurations and optionally additional controller states can be persistently saved. As a result, implementors of this interface need to follow strict guidelines on how to initialize their services and characteristics.

The set of services can change though over the lifespan of the implementation (e.g. protocol changes imposed by HAP like the addition of secure-video for cameras). Such changes can be made using initWithServices. See below for more infos.

The constructor of a Controller should only initialize controller specific configuration and states and MUST NOT create any services or characteristics. Additionally, it must implement all necessary methods as noted below. Those methods will get called when the accessory gets added to an Accessory or a Accessory is restored from disk.

interface Controller<M> {
    configureServices(): void;
    constructServices(): M;
    controllerId(): string;
    handleControllerRemoved(): void;
    handleFactoryReset?(): void;
    initWithServices(serviceMap: M): void | M;
}

Type Parameters

Hierarchy (view full)

Methods

  • This method is called to configure the services and their characteristics of the controller. When this method is called, it is guaranteed that either constructServices or initWithServices were called before and all services are already created.

    This method SHOULD set up all necessary event handlers for services and characteristics.

    Returns void

  • This method is called by the accessory the controller is added to. This method is only called if a new controller is constructed (aka the controller is not restored from disk initWithServices). It MUST create all needed services and characteristics. It MAY create links between services or mark them as hidden or primary. It MUST NOT configure any event handlers. The controller SHOULD save created services in internal properties for later access.

    The method must return all created services in a ServiceMap. A ControllerServiceMap basically maps a name to every service on the controller. It is used to potentially recreate a controller for a given ServiceMap using initWithServices.

    The set of services represented by the Controller MUST remain static and can only change over new version of the Controller implementation (see initWithServices)

    Returns M

    a ControllerServiceMap representing all services of a controller indexed by a controller chosen name.

  • Every instance of a Controller must define appropriate identifying material. The returned identifier MUST NOT change over the lifetime of the Controller object.

    Note: The controller can choose to return the same identifier for all controllers of the same type. This will result in the user only being able to add ONE instance of an Controller to an accessory.

    Some predefined identifiers can be found in ControllerIdentifier.

    Returns string

  • This method is called once the Controller is removed from the accessory. The controller MUST reset everything to its initial state (just as it would have been constructed freshly) form the constructor. Adding the Controller back to an accessory after it was removed MUST be supported! If the controller is a SerializableController it MUST NOT call the StateChangeDelegate as a result of a call to this method.

    All service contained in the ControllerServiceMap returned by constructServices will be automatically removed from the Accessory. The Controller MUST remove any references to those services.

    Returns void

  • This method is called to signal a factory reset of the controller and its services and characteristics. A controller MUST reset any configuration or states to default values.

    This method is called once the accessory gets unpaired or the Controller gets removed from the Accessory.

    Returns void

  • This method is called to initialize the controller with already created services. The controller SHOULD save the passed services in internal properties for later access.

    The controller can return a ServiceMap to signal that the set of services changed. A Controller MUST modify the ServiceMap which is passed to the method and MUST NOT create a new one (to support inheritance). It MUST NOT return a ServiceMap if the service configuration did not change! It MUST be able to restore services using a ServiceMap from any point in time.

    Parameters

    • serviceMap: M

      A ControllerServiceMap that represents all services of a controller indexed by the controller chosen name.

    Returns void | M

    optionally a ControllerServiceMap. This can be used to alter the services configuration of a controller.