homebridge-framework

This framework provides an easy-to-use wrapper for the homebridge API. It aims to only provide the features that are actually needed to develop a plugin. The framework is written in TypeScript and it is recommended to also develop the plugins with this framework in TypeScript. Besides the stripped-down API that this framework provides, it automatically manages accessories, services and characteristics. There is no need to explicitely remove those entities from homebridge. If an accessory/service/characteristic is not "used" at runtime, it is removed from homebridge.

Features

• Declarative syntax
• Automatic registration/deregistration of accessories
• Automatic adding/removing of services
• Automatic adding/removing of characteristics
• Typed configuration

Getting Started

Create a new project and add the framework (homebridge-framework) as a devDependency to the NPM package.json file.

Configuration

Create a new interface for your configuration. This will be used to access the configuration strongly typed.

 
export interface MyConfigurationInterface {
    myString: string;
}
 

Platform

In order to use the framework, create a new class that inherits from HomebridgePlatform:

import { HomebridgePlatform, Homebridge } from 'homebridge-framework';
import { MyConfigurationInterface } from './my-configuration-interface';
 
export class MyPlatform extends HomebridgePlatform<MyConfigurationInterface> {
 
    // Overwrite the pluginName property to set the name of your plugin
    public get pluginName(): string {
        return 'my-plugin-name';
    }    
    
    // Overwrite the platformName property to set the name of your platform (used in the config.json file)
    public get platformName(): string {
        return 'FrameworkSamplePlatform';
    }
 
    // Overwrite the initialize method. You can either return void, or Promise<void> if you have asyncronous calls here.
    // "Declare" all your accessories, services and characteristics in this method. 
    // After the execution of this method, the framework will automatically remove all accessories/services/characteristics that
    // have been cached by homebridge but not "declared" while initialization.
    public initialize() {
 
        // === declaration of accessories/services/characteristics ===
 
        // "Declare" an accessory that should be exposed
        // The accessory ID (second parameter) is used to match the accessory from the cached accessories
        const myAccessory = this.useAccessory('My Accessory Name', 'my-accessory-id');
 
        // "Declare" a service for your accessory, e.g. a switch
        // The Homebridge class provides access to a static "list" of services
        const mySwitch = myAccessory.useService(Homebridge.Services.Switch, 'My Switch Name');
 
        // "Declare" a characteristic for your service, e.g. the on characteristic
        // The generic type parameter should match the type of the characteristic
        const onCharacteristic = mySwitch.useCharacteristic<boolean>(Homebridge.Characteristics.On);
 
        // === other features ===
 
        // This is how you can easily set accessory information
        const myAccessoryInformation = new AccessoryInformation();
        myAccessoryInformation.manufacturer = 'Me';
        myAccessoryInformation.model = 'My Accessory';
        myAccessoryInformation.serialNumber = '123';
        myAccessoryInformation.firmwareRevision = '1.1';
        myAccessoryInformation.hardwareRevision = '1.0';
        myAccessory.setInformation(myAccessoryInformation);
 
        // This is how you set the properties of a characteristic (e.g. need for thermostats to set minimum and maximum temperature)
        onCharacteristic.setProperties({
            ...
        });
 
        // This is how you access the value of a characteristic
        const onCharacteristicValue = onCharacteristic.value;
        console.log(onCharacteristicValue);
 
        // This is how you update the value of a characteristic
        onCharacteristic.value = true;
 
        // This is how you handle changes of the value made by the HomeKit user
        onCharacteristic.valueChanged = newValue => {
            console.log(newValue);
        };
 
        // This is how to access the configuration
        console.log(this.configuration.myString);
 
        // === homebridge logging ===
 
        this.logger('default');
        this.logger.debug('debug');
    }
 
}
 

Index file

In order to load the correct platform instance, your main plugin file should look like this:

import { Homebridge } from 'homebridge-framework';
import { MyPlatform } from './my-platform';
 
module.exports = Homebridge.register(new MyPlatform());