Platform Plugins
API.registerPlatform
API.registerPlatform(platformName: string, constructor: PlatformPluginConstructor): void
Register a "Platform" type plugin. Platform style plugins can expose any number of accessories and can dynamically remove and add accessories at any time. Only a single instance of a given platform may be configured in the Homebridge config.json
.
module.exports = (api) => {
api.registerPlatform('ExamplePlatformName', ExamplePlatformPlugin);
}
class ExamplePlatformPlugin {
constructor(log, config, api) {
log.debug('Example Platform Plugin Loaded');
}
}
API.registerPlatformAccessories
API.registerPlatformAccessories(pluginIdentifier: string, platformName: string, accessories: PlatformAccessory[]): void
Publish one or more accessories to Homebridge.
class ExamplePlatformPlugin {
constructor(log, config, api) {
// store restored cached accessories here
this.accessories = [];
/**
* Platforms should wait until the "didFinishLaunching" event has fired before
* registering any new accessories.
*/
api.on('didFinishLaunching', () => {
const uuid = api.hap.uuid.generate('SOMETHING UNIQUE');
// check the accessory was not restored from cache
if (!this.accessories.find(accessory => accessory.UUID === uuid)) {
// create a new accessory
const accessory = new this.api.platformAccessory('DISPLAY NAME', uuid);
// register the accessory
api.registerPlatformAccessories('PLUGIN_NAME', 'PLATFORM_NAME', [accessory]);
}
});
}
/**
* REQUIRED - Homebridge will call the "configureAccessory" method once for every cached
* accessory restored
*/
configureAccessory(accessory) {
this.accessories.push(accessory);
}
}
API.unregisterPlatformAccessories
API.unregisterPlatformAccessories(pluginIdentifier: string, platformName: string, accessories: PlatformAccessory[]): void
Remove one or more accessories from Homebridge.
class ExamplePlatformPlugin {
constructor(log, config, api) {
// store restored cached accessories here
this.accessories = [];
/**
* Platforms should wait until the "didFinishLaunching" event has fired before
* registering any new accessories.
*/
api.on('didFinishLaunching', () => {
// for the example just remove the first restored cached accessory
const accessory = this.accessories[0];
api.unregisterPlatformAccessories('PLUGIN_NAME', 'PLATFORM_NAME', [accessory]);
});
}
/**
* Homebridge will call the "configureAccessory" method once for every cached
* accessory restored
*/
configureAccessory(accessory) {
this.accessories.push(accessory);
}
}
API.publishExternalAccessories
API.publishExternalAccessories(pluginIdentifier: string, accessories: PlatformAccessory[]): void
Accessories published externally will need to be paired seperately by the user. Common uses for external accessories include Cameras and TVs.
API.updatePlatformAccessories
API.updatePlatformAccessories(accessories: PlatformAccessory[]): void
Platform Accessory
API.platformAccessory
API.platformAccessory(displayName: string, uuid: string, category?: any): PlatformAccessory
Creates a new platform accessory. It will not be active until you register the created accessory with API.registerPlatformAccessories
method.
class ExamplePlatformPlugin {
constructor(log, config, api) {
this.api = api;
const uuid = this.api.hap.uuid.generate('SOMETHING UNIQUE');
const accessory = new this.api.platformAccessory('DISPLAY NAME', uuid);
}
}
PlatformAccessory.addService
PlatformAccessory.addService(service: Service, ...constructorArgs: any[]): Service
Adds a new service to a platform accessory.
class ExamplePlatformPlugin {
constructor(log, config, api) {
this.api = api;
const accessory = new this.api.platformAccessory('DISPLAY NAME', uuid);
// get the LightBulb service if it exists
let service = accessory.getService(this.api.hap.Service.Lightbulb);
// otherwise create a new LightBulb service
if (!service) {
service = accessory.addService(this.api.Service.Lightbulb);
}
}
}
If you are adding more than one service of the same type to an accessory, you will need to give the service a name and "subtype".
const service2 = accessory.addService(Service.Lightbulb, 'Light Bulb 1', 'USER_DEFINED_SUBTYPE');
PlatformAccessory.getService
PlatformAccessory.getService(name: string | T): any
Returns an existing service from the platform accessory.
const service = accessory.getService(this.api.hap.Service.Lightbulb);
If you have added more than one service of the same type to an accessory, you will need to get the service using the name you defined when adding it.
const service2 = accessory.getService('Light Bulb 1');
PlatformAccessory.removeService
PlatformAccessory.removeService(service: Service): void
Removes the service from the platform accessory.
PlatformAccessory.context
PlatformAccessory.context
Store custom data with accessory that will persist through Homebridge restarts.
class ExamplePlatformPlugin {
constructor(log, config, api) {
this.api = api;
const uuid = this.api.hap.uuid.generate('SOMETHING UNIQUE');
const accessory = new this.api.platformAccessory('DISPLAY NAME', uuid);
// data stored on the context object will persist through restarts
accessory.context.myData = 'anything';
}
}
PlatformAccessory.services
PlatformAccessory.services: Service[]
An array of services currently added to the accessory.