Interface SerializableController<M, S>

A SerializableController is a Controller which additionally carries states/data (beside services and characteristics) which needs to be persistently stored. For example current target configuration for an AppleTV remote.

Type Parameters


Implemented by


  • 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)


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

    Returns M

  • 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 to restore the controller state from disk. This is only called once, when the data was loaded from disk and the Accessory is to be published. A controller MUST provide backwards compatibility for any configuration layout exposed at any time. A Controller MUST NOT depend on any specific calling order.


    • serialized: S

    Returns void

  • 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 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.


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


    • serviceMap: M

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

    Returns void | M

  • This method can be used to persistently save controller related configuration across reboots. It should return undefined, if the controller data was reset to default values and nothing needs to be stored anymore.


    an arbitrary Controller defined object containing all necessary data

    Returns undefined | S

  • This method is called once upon setup. It supplies a function used by the Controller to signal state changes. The implementing controller SHOULD store the function and call it every time the internal controller state changes. It should be expected that the serialize method will be called next and that the state will be stored to disk. The delegate parameter can be undefined when the controller is removed and the state change delegate is reset.


    Returns void