or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md core-api.md hap-integration.md index.md logging.md platform-accessories.md plugin-system.md

tile.json

Configuration

Homebridge provides comprehensive type-safe configuration interfaces for bridges, accessories, platforms, and server options. The configuration system supports both single-bridge and child-bridge architectures, with extensive customization options for HomeKit integration and plugin behavior.

Capabilities

Bridge Configuration

Configuration for HomeKit bridges, including network settings and device identification.

/**
 * Bridge configuration interface
 * Defines HomeKit bridge identity and network settings
 */
interface BridgeConfiguration {
  /** Human-readable name for the bridge */
  name: string;
  /** MAC address format username (XX:XX:XX:XX:XX:XX) */
  username: string;
  /** HomeKit pairing PIN (XXX-XX-XXX format) */
  pin: string;
  /** MDNS advertiser type (optional) */
  advertiser?: MDNSAdvertiser;
  /** Port number for HAP server (optional, default: random) */
  port?: number;
  /** IP address(es) to bind to (optional) */
  bind?: string | string[];
  /** HomeKit setup ID for QR code - 4 character string (optional) */
  setupID?: string;
  /** Manufacturer name (optional) */
  manufacturer?: string;
  /** Model name (optional) */
  model?: string;
  /** Disable IPC communication (optional) */
  disableIpc?: boolean;
  /** Firmware revision (optional) */
  firmwareRevision?: string;
  /** Serial number (optional) */
  serialNumber?: string;
  /** Environment variables for child bridge (optional) */
  env?: {
    DEBUG?: string;
    NODE_OPTIONS?: string;
    [key: string]: string | undefined;
  };
}

Usage Examples:

// Basic bridge configuration
const bridgeConfig: BridgeConfiguration = {
  name: "Homebridge Living Room",
  username: "CC:22:3D:E3:CE:30",
  pin: "031-45-154"
};

// Advanced bridge configuration
const advancedBridgeConfig: BridgeConfiguration = {
  name: "Homebridge Security System",
  username: "CC:22:3D:E3:CE:31", 
  pin: "031-45-155",
  port: 51826,
  bind: ["192.168.1.100", "::1"],
  setupID: "1QJ8",
  manufacturer: "Custom Systems Inc",
  model: "Security Bridge v2",
  firmwareRevision: "2.1.0",
  serialNumber: "SB-2021-001",
  disableIpc: false,
  env: {
    DEBUG: "*",
    NODE_ENV: "production"
  }
};

// Child bridge configuration in accessory config
const accessoryWithChildBridge: AccessoryConfig = {
  accessory: "SecurityCamera",
  name: "Front Door Camera",
  _bridge: {
    name: "Camera Bridge",
    username: "CC:22:3D:E3:CE:32",
    pin: "031-45-156",
    port: 51827
  }
};

Homebridge Configuration

Main configuration file structure for the entire Homebridge instance.

/**
 * Main Homebridge configuration structure
 * Root configuration object for config.json
 */
interface HomebridgeConfig {
  /** Primary bridge configuration */
  bridge: BridgeConfiguration;
  /** @deprecated MDNS configuration (use bridge.advertiser instead) */
  mdns?: any;
  /** Array of individual accessory configurations */
  accessories: AccessoryConfig[];
  /** Array of platform configurations */
  platforms: PlatformConfig[];
  /** Array of plugin names to load (optional) */
  plugins?: string[];
  /** Array of plugin names to disable (optional) */
  disabledPlugins?: string[];
  /** External port configuration for cameras (optional) */
  ports?: ExternalPortsConfiguration;
}

Usage Examples:

// Complete Homebridge configuration
const homebridgeConfig: HomebridgeConfig = {
  bridge: {
    name: "Homebridge Main",
    username: "CC:22:3D:E3:CE:30",
    pin: "031-45-154",
    port: 51826
  },
  accessories: [
    {
      accessory: "Switch",
      name: "Garage Door",
      switchType: "stateful"
    },
    {
      accessory: "TemperatureSensor", 
      name: "Outdoor Temperature",
      _bridge: {
        name: "Sensor Bridge",
        username: "CC:22:3D:E3:CE:31",
        pin: "031-45-155"
      }
    }
  ],
  platforms: [
    {
      platform: "SmartThings",
      name: "SmartThings Hub",
      appUrl: "https://api.smartthings.com",
      accessToken: "your-token-here"
    },
    {
      platform: "Nest",
      name: "Nest Thermostat",
      _bridge: {
        name: "Climate Bridge", 
        username: "CC:22:3D:E3:CE:32",
        pin: "031-45-156"
      }
    }
  ],
  plugins: [
    "homebridge-smartthings",
    "homebridge-nest"
  ],
  disabledPlugins: [
    "homebridge-old-plugin"
  ],
  ports: {
    start: 52100,
    end: 52150
  }
};

Accessory Configuration

Configuration interface for individual accessory plugins.

/**
 * Accessory configuration interface
 * Base configuration for all accessory plugins
 */
interface AccessoryConfig extends Record<string, any> {
  /** Accessory type identifier (matches plugin registration) */
  accessory: string;
  /** Display name for the accessory */
  name: string;
  /** Custom UUID base for generating accessory UUID (optional) */
  uuid_base?: string;
  /** Child bridge configuration (optional) */
  _bridge?: BridgeConfiguration;
}

Usage Examples:

// Basic accessory configuration
const lightConfig: AccessoryConfig = {
  accessory: "HttpLight",
  name: "Living Room Light",
  url: "http://192.168.1.100/api/light",
  timeout: 5000
};

// Accessory with custom UUID base
const sensorConfig: AccessoryConfig = {
  accessory: "TemperatureSensor",
  name: "Basement Temperature", 
  uuid_base: "basement-temp-sensor",
  pin: 4,
  interval: 60000
};

// Accessory with child bridge
const cameraConfig: AccessoryConfig = {
  accessory: "Camera",
  name: "Security Camera",
  streamUrl: "rtsp://192.168.1.200/stream",
  _bridge: {
    name: "Camera Bridge",
    username: "CC:22:3D:E3:CE:33",
    pin: "031-45-157",
    port: 51828
  }
};

// Complex accessory configuration
interface SmartSwitchConfig extends AccessoryConfig {
  accessory: "SmartSwitch";
  name: string;
  ipAddress: string;
  port: number;
  protocol: "http" | "mqtt";
  authentication?: {
    username: string;
    password: string;
  };
  polling?: {
    interval: number;
    enabled: boolean;
  };
}

const switchConfig: SmartSwitchConfig = {
  accessory: "SmartSwitch",
  name: "Kitchen Switch",
  ipAddress: "192.168.1.101",
  port: 80,
  protocol: "http",
  authentication: {
    username: "admin",
    password: "secure123"
  },
  polling: {
    interval: 10000,
    enabled: true
  }
};

Platform Configuration

Configuration interface for platform plugins.

/**
 * Platform configuration interface
 * Base configuration for all platform plugins
 */
interface PlatformConfig extends Record<string, any> {
  /** Platform type identifier (matches plugin registration) */
  platform: string;
  /** Display name for the platform (optional) */
  name?: string;
  /** Child bridge configuration (optional) */
  _bridge?: BridgeConfiguration;
}

Usage Examples:

// Basic platform configuration
const smartThingsConfig: PlatformConfig = {
  platform: "SmartThings",
  name: "SmartThings Hub",
  appUrl: "https://api.smartthings.com",
  accessToken: "your-access-token"
};

// Platform with child bridge
const nestConfig: PlatformConfig = {
  platform: "Nest",
  name: "Nest Platform",
  refreshToken: "your-refresh-token",
  _bridge: {
    name: "Nest Bridge",
    username: "CC:22:3D:E3:CE:34", 
    pin: "031-45-158"
  }
};

// Complex platform configuration with typed interface
interface MyPlatformConfig extends PlatformConfig {
  platform: "MyPlatform";
  name?: string;
  apiEndpoint: string;
  apiKey: string;
  pollingInterval?: number;
  enabledDeviceTypes?: string[];
  rooms?: Array<{
    id: string;
    name: string;
    devices: string[];
  }>;
}

const myPlatformConfig: MyPlatformConfig = {
  platform: "MyPlatform",
  name: "Smart Home Platform", 
  apiEndpoint: "https://api.smarthome.com/v1",
  apiKey: "sk_live_abc123",
  pollingInterval: 30000,
  enabledDeviceTypes: ["light", "switch", "sensor"],
  rooms: [
    {
      id: "living-room",
      name: "Living Room",
      devices: ["light-001", "switch-002"]
    },
    {
      id: "kitchen", 
      name: "Kitchen",
      devices: ["light-003", "sensor-004"]
    }
  ]
};

Server Options

Configuration options for Homebridge server behavior.

/**
 * Homebridge server options
 * Controls server behavior and plugin loading
 */
interface HomebridgeOptions {
  /** Keep cached accessories when plugins are missing */
  keepOrphanedCachedAccessories?: boolean;
  /** Hide QR code in console output */
  hideQRCode?: boolean;
  /** Allow unauthenticated access (development only) */
  insecureAccess?: boolean;
  /** Custom path for loading plugins */
  customPluginPath?: string;
  /** Disable timestamp prefixes in log output */
  noLogTimestamps?: boolean;
  /** Enable debug level logging */
  debugModeEnabled?: boolean;  
  /** Force colored output in logs */
  forceColourLogging?: boolean;
  /** Custom path for Homebridge storage */
  customStoragePath?: string;
  /** Only load plugins from customPluginPath */
  strictPluginResolution?: boolean;
}

Usage Examples:

// Development server options
const devOptions: HomebridgeOptions = {
  debugModeEnabled: true,
  forceColourLogging: true,
  hideQRCode: false,
  insecureAccess: true, // Development only!
  noLogTimestamps: false
};

// Production server options
const prodOptions: HomebridgeOptions = {
  keepOrphanedCachedAccessories: false,
  hideQRCode: true,
  debugModeEnabled: false,
  customStoragePath: "/var/lib/homebridge",
  strictPluginResolution: true,
  customPluginPath: "/usr/local/lib/node_modules"
};

// Docker deployment options
const dockerOptions: HomebridgeOptions = {
  customStoragePath: "/homebridge",
  forceColourLogging: false,
  noLogTimestamps: true,
  keepOrphanedCachedAccessories: true
};

External Ports Configuration

Configuration for external port ranges used by camera streaming and other services.

/**
 * External ports configuration
 * Defines port range for camera streaming and other external services
 */
interface ExternalPortsConfiguration {
  /** Starting port number */
  start: number;
  /** Ending port number */
  end: number;
}

Usage Examples:

// Basic port configuration
const portsConfig: ExternalPortsConfiguration = {
  start: 52100,
  end: 52150
};

// Large camera deployment
const cameraPortsConfig: ExternalPortsConfiguration = {
  start: 55000,
  end: 55500
};

// Use in main configuration
const configWithPorts: HomebridgeConfig = {
  bridge: {
    name: "Homebridge Camera Hub",
    username: "CC:22:3D:E3:CE:30",
    pin: "031-45-154"
  },
  accessories: [],
  platforms: [
    {
      platform: "Camera",
      name: "Security Cameras"
    }
  ],
  ports: {
    start: 52100,
    end: 52200
  }
};

Configuration Validation

Helper patterns for validating configuration objects.

// Type-safe configuration validation
function validateBridgeConfig(config: any): config is BridgeConfiguration {
  return (
    typeof config.name === "string" &&
    typeof config.username === "string" &&
    typeof config.pin === "string" &&
    /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/.test(config.username) &&
    /^\d{3}-\d{2}-\d{3}$/.test(config.pin)
  );
}

function validateAccessoryConfig(config: any): config is AccessoryConfig {
  return (
    typeof config.accessory === "string" &&
    typeof config.name === "string" &&
    config.accessory.length > 0 &&
    config.name.length > 0
  );
}

// Configuration merging with defaults
function mergeWithDefaults<T extends PlatformConfig>(
  config: T,
  defaults: Partial<T>
): T {
  return { ...defaults, ...config };
}

const defaultPlatformConfig = {
  pollingInterval: 30000,
  enableLogging: true,
  maxRetries: 3
};

const finalConfig = mergeWithDefaults(userConfig, defaultPlatformConfig);

Types

interface MDNSAdvertiser {
  type: "avahi" | "resolved" | "ciao";
  interface?: string;
}

interface MDNSOptions {
  interface?: string;
  type?: "avahi" | "resolved" | "ciao";
}

Version

Tile

Files

configuration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Configuration

Capabilities

Bridge Configuration

Homebridge Configuration

Accessory Configuration

Platform Configuration

Server Options

External Ports Configuration

Configuration Validation

Types

configuration.mddocs/