Getting Started - homebridge-plugins/homebridge-matter GitHub Wiki

import type { API } from 'homebridge'

export function registerMyDevice(api: API) {
  const accessory = {
    // Identity
    UUID: api.matter.uuid.generate('unique-device-id'),
    displayName: 'My Device',
    deviceType: api.matter.deviceTypes.OnOffLight,
    serialNumber: 'DEVICE-001',
    manufacturer: 'My Company',
    model: 'Model v1',

    // Optional: Persistent context storage
    context: {
      deviceId: 'my-device-123',
    },

    // State: Initial values for all cluster attributes
    // These values are only used when the accessory is first created
    // After that, Homebridge automatically persists and restores state across restarts
    clusters: {
      onOff: {
        onOff: false, // Initial state (only used on first creation)
      },
    },

    // Handlers: Respond to commands from Home app
    handlers: {
      onOff: {
        on: async () => {
          // Control your physical device
        },
        off: async () => {
          // Control your physical device
        },
      },
    },
  }

  return [accessory]
}

{
  UUID: api.matter.uuid.generate('unique-id'),  // Must be unique per device
  displayName: 'Living Room Light',             // Name shown in Home app
  deviceType: api.matter.deviceTypes.OnOffLight, // Matter device type
  serialNumber: 'LIGHT-001',                     // Unique serial number
  manufacturer: 'My Company',                    // Manufacturer name
  model: 'Smart Light v1',                       // Model identifier
}

// Common examples
api.matter.deviceTypes.OnOffLight
api.matter.deviceTypes.DimmableLight
api.matter.deviceTypes.TemperatureSensor
api.matter.deviceTypes.Thermostat
api.matter.deviceTypes.DoorLock
// ... see full list below

{
  context: {
    deviceId: 'my-light-123',
    lastKnownState: true,
    customData: { /* anything */ }
  },
}

// Access later:
const deviceId = accessory.context.deviceId

clusters: {
  onOff: {
    onOff: false,  // Boolean: true = on, false = off
  },
  levelControl: {
    currentLevel: 127,  // Number: 1-254 (127 = 50%)
    minLevel: 1,        // Minimum brightness
    maxLevel: 254,      // Maximum brightness
  },
}

import type { API } from 'homebridge'

import axios from 'axios'

export function registerLight(api: API, deviceId: string, ipAddress: string) {
  const accessory = {
    // Identity
    UUID: api.matter.uuid.generate(`http-light-${deviceId}`),
    displayName: `Light ${deviceId}`,
    deviceType: api.matter.deviceTypes.OnOffLight,
    serialNumber: `HTTP-${deviceId}`,
    manufacturer: 'Generic HTTP',
    model: 'v1.0',

    // Context: Store device information
    context: {
      deviceId,
      ipAddress,
    },

    // Initial state (only used on first creation)
    clusters: {
      onOff: {
        onOff: false,
      },
    },

    // Handlers: Control the physical device
    handlers: {
      onOff: {
        on: async () => {
          // Turn on the physical light
          await axios.post(`http://${ipAddress}/api/light`, {
            state: 'on',
          })
          // Homebridge automatically updates Matter state to onOff: true
        },
        off: async () => {
          // Turn off the physical light
          await axios.post(`http://${ipAddress}/api/light`, {
            state: 'off',
          })
          // Homebridge automatically updates Matter state to onOff: false
        },
      },
    },
  }

  return [accessory]
}

import type { API, DynamicPlatformPlugin, Logger, MatterAccessory, PlatformAccessory, PlatformConfig } from 'homebridge'

export class MyPlatform implements DynamicPlatformPlugin {
  private matterAccessories: Map<string, MatterAccessory> = new Map()

  constructor(
    public readonly log: Logger,
    public readonly config: PlatformConfig,
    public readonly api: API,
  ) {
    this.api.on('didFinishLaunching', async () => {
      // Discover devices from your API/network
      const newAccessories = this.discoverNewAccessories()

      // Register ONLY new accessories (cached ones are automatically restored)
      if (newAccessories.length > 0) {
        await this.api.matter.registerPlatformAccessories(PLUGIN_NAME, PLATFORM_NAME, newAccessories)
      }
    })
  }

  configureAccessory(accessory: PlatformAccessory) {
    // Required by DynamicPlatformPlugin interface (for HAP accessories)
    // Not used for Matter accessories
  }

  configureMatterAccessory(accessory: MatterAccessory) {
    // Called for each cached Matter accessory on startup
    // Re-attach handlers here, accessory is automatically re-registered
    this.matterAccessories.set(accessory.UUID, accessory)

    // Re-attach handlers based on accessory.context data
    // (See examples below)
  }

  private discoverNewAccessories(): MatterAccessory[] {
    // Discover devices from your API/network
    const allDevices = this.discoverDevices()

    // Only return devices that aren't already cached
    return allDevices
      .filter(device => !this.matterAccessories.has(this.generateUUID(device)))
      .map(device => this.createAccessory(device))
  }
}