homebridge/dist/bridgeService.d.ts

HomeKit support for the impatient

import type { CharacteristicWarning, InterfaceName, IPAddress, MacAddress, MDNSAdvertiser } from '@homebridge/hap-nodejs';
import type { AccessoryIdentifier, AccessoryName, AccessoryPlugin, HomebridgeAPI, PlatformIdentifier, PlatformName, PluginIdentifier, StaticPlatformPlugin } from './api.js';
import type { ExternalPortsConfiguration, ExternalPortService } from './externalPortService.js';
import type { Logging } from './logger.js';
import type { MatterConfig } from './matter/index.js';
import type { Plugin } from './plugin.js';
import type { HomebridgeOptions } from './server.js';
import { Accessory, Bridge } from '@homebridge/hap-nodejs';
import { PlatformAccessory } from './platformAccessory.js';
import { PluginManager } from './pluginManager.js';
export declare const DEFAULT_BRIDGE_DEFAULTS: {
    readonly vendorName: "Homebridge";
    readonly manufacturer: "homebridge.io";
    readonly model: "homebridge";
};
/**
 * HAP-specific configuration for a bridge. Mirrors the shape of `MatterConfig`
 * so the two protocol blocks are symmetric and can be reasoned about uniformly.
 */
export interface BridgeHapConfig {
    /**
     * Whether HAP is published for this bridge. Default `true` (so omitting the
     * block, or omitting `enabled`, means HAP is on). Set to `false` to suppress
     * the bridge's HAP advertisement while preserving any existing pairing.
     *
     * Both `hap` and `matter` may be disabled on the same bridge; the bridge
     * then advertises nothing (it still loads, it just exposes no accessories).
     */
    enabled?: boolean;
    /**
     * When `true`, the bridge accessory itself is NOT published, but external
     * accessories registered by plugins against this bridge ARE still published
     * (each as its own standalone HAP accessory). Intended to be paired with
     * `enabled: false`; if `externalsOnly: true` is set on its own, validation
     * warns and normalises `enabled` to `false` rather than rejecting the config.
     */
    externalsOnly?: boolean;
}
export interface BridgeConfiguration {
    name: string;
    username: MacAddress;
    pin: string;
    advertiser?: MDNSAdvertiser;
    port?: number;
    bind?: (InterfaceName | IPAddress) | (InterfaceName | IPAddress)[];
    /** 4-character HomeKit setup ID (alphanumeric, e.g. "ABCD"). Validated at runtime. */
    setupID?: string;
    manufacturer?: string;
    model?: string;
    disableIpc?: boolean;
    firmwareRevision?: string;
    serialNumber?: string;
    debugModeEnabled?: boolean;
    /**
     * HAP publishing config. Defaults to enabled when omitted.
     *
     * The object form (`BridgeHapConfig`) is preferred. The bare boolean form
     * (`hap: false` / `hap: true`) is the deprecated v2-beta shorthand, still
     * accepted for back-compat and normalized to `{ enabled: <boolean> }` by
     * `validateHapConfig`. The type allows it so existing configs keep compiling.
     *
     * @deprecated Pass `hap` as a boolean is deprecated; use `{ enabled }` instead.
     */
    hap?: BridgeHapConfig | boolean;
    matter?: MatterConfig;
    env?: {
        DEBUG?: string;
        NODE_OPTIONS?: string;
    };
}
/**
 * Whether HAP is enabled for the given bridge configuration. HAP is on by
 * default; users opt out via `hap: { enabled: false }`. Missing block or
 * missing `enabled` both mean enabled.
 *
 * The legacy boolean form (`hap: false`/`hap: true`) is handled here too.
 * `validateHapConfig` normalizes it to the object shape, but a raw `false`
 * must still read as disabled even if this is reached before normalization —
 * otherwise `!hap` (true for `false`) would wrongly report a disabled bridge
 * as enabled and publish it anyway.
 */
export declare function isHapConfigEnabled(hap: BridgeHapConfig | boolean | undefined): boolean;
/**
 * Whether the bridge is in HAP externalsOnly mode (the bridge accessory itself
 * is suppressed but external accessories still publish). Only the object form
 * carries `externalsOnly`; the legacy boolean form never does, so it is always
 * false there. Accepts the boolean form so callers can pass `bridge.hap`
 * directly without narrowing.
 */
export declare function isHapExternalsOnly(hap: BridgeHapConfig | boolean | undefined): boolean;
/**
 * Validate a `hap` config block. Throws on hard errors (wrong type, conflict
 * between `externalsOnly` and `enabled`). For accessory child bridges, strips
 * `externalsOnly` with a warn-level log because externals are not supported
 * via the accessory plugin API.
 *
 * Mutates the passed block in place when stripping fields.
 */
export declare function validateHapConfig(bridgeConfig: BridgeConfiguration, opts: {
    bridgeLabel: string;
    isAccessoryPlugin?: boolean;
}): void;
export interface AccessoryConfig extends Record<string, any> {
    accessory: AccessoryName | AccessoryIdentifier;
    name: string;
    uuid_base?: string;
    _bridge?: BridgeConfiguration;
}
export interface PlatformConfig extends Record<string, any> {
    platform: PlatformName | PlatformIdentifier;
    name?: string;
    _bridge?: BridgeConfiguration;
}
export interface HomebridgeConfig {
    bridge: BridgeConfiguration;
    /**
     * @deprecated
     */
    mdns?: any;
    accessories: AccessoryConfig[];
    platforms: PlatformConfig[];
    plugins?: PluginIdentifier[];
    /**
     * Array of disabled plugins.
     * Unlike the plugins[] config which prevents plugins from being initialized at all, disabled plugins still have their alias loaded, so
     * we can match config blocks of disabled plugins and show an appropriate message in the logs.
     */
    disabledPlugins?: PluginIdentifier[];
    ports?: ExternalPortsConfiguration;
    matterPorts?: ExternalPortsConfiguration;
}
export interface BridgeOptions extends HomebridgeOptions {
    cachedAccessoriesDir: string;
    cachedAccessoriesItemName: string;
    externalAccessoriesItemName: string;
}
export interface ExternalAccessoryMetadata {
    username: MacAddress;
    plugin: PluginIdentifier;
    displayName: string;
    category: number;
    port?: number;
}
export interface CharacteristicWarningOpts {
    ignoreSlow?: boolean;
}
export declare class BridgeService {
    private api;
    private pluginManager;
    private externalPortService;
    private bridgeOptions;
    private bridgeConfig;
    bridge: Bridge;
    private storageService;
    private readonly allowInsecureAccess;
    private cachedPlatformAccessories;
    private cachedAccessoriesFileLoaded;
    private readonly publishedExternalAccessories;
    private readonly publishedExternalAccessoriesMetadata;
    constructor(api: HomebridgeAPI, pluginManager: PluginManager, externalPortService: ExternalPortService, bridgeOptions: BridgeOptions, bridgeConfig: BridgeConfiguration);
    static printCharacteristicWriteWarning(plugin: Plugin, accessory: Accessory, opts: CharacteristicWarningOpts, warning: CharacteristicWarning): void;
    publishBridge(): void;
    /**
     * Attempt to load the cached accessories from disk.
     */
    loadCachedPlatformAccessoriesFromDisk(): Promise<void>;
    /**
     * Return the name of the backup cache file
     */
    private get backupCacheFileName();
    /**
     * Create a backup of the cached file
     * This is used if we ever have trouble reading the main cache file
     */
    private createCachedAccessoriesBackup;
    /**
     * Restore a cached accessories backup
     * This is used if the main cache file has a JSON syntax error / is corrupted
     */
    private restoreCachedAccessoriesBackup;
    restoreCachedPlatformAccessories(): void;
    /**
     * Save the cached accessories back to disk.
     */
    saveCachedPlatformAccessoriesOnDisk(): void;
    /**
     * Save metadata for currently published external accessories so external tools (e.g. the
     * Homebridge UI) can attribute each accessory to the plugin that published it. The
     * underlying HAP `AccessoryInfo` files do not store plugin attribution.
     */
    saveExternalAccessoriesMetadataOnDisk(): void;
    handleRegisterPlatformAccessories(accessories: PlatformAccessory[]): void;
    handleUpdatePlatformAccessories(accessories: PlatformAccessory[]): void;
    handleUnregisterPlatformAccessories(accessories: PlatformAccessory[]): void;
    handlePublishExternalAccessories(accessories: PlatformAccessory[]): Promise<void>;
    createHAPAccessory(plugin: Plugin, accessoryInstance: AccessoryPlugin, displayName: string, accessoryType: AccessoryName | AccessoryIdentifier, uuidBase?: string): Accessory | undefined;
    loadPlatformAccessories(plugin: Plugin, platformInstance: StaticPlatformPlugin, platformType: PlatformName | PlatformIdentifier, logger: Logging): Promise<void>;
    teardown(): void;
    private static strippingPinCode;
}
//# sourceMappingURL=bridgeService.d.ts.map