Matterbridge

Certain device types are considered 'composed devices'. Instead of being a single unit, they require you to create the main device and then explicitly add sub-components (like cabinets, surfaces, or parts) using specific methods.

Oven Create an Oven and use .addCabinet(name, tags[]) to add cabinets.

Cooktop Create a Cooktop and use .addSurface(name, tags[]) to add surfaces.

Refrigerator Create a Refrigerator and use .addCabinet(name, tags[]) to add cabinets.

Note: When adding components, you must provide an array of objects containing mfgCode, namespaceId, tag, and label.

// Oven Example
const oven = new Oven('Oven', 'OV1234567890');
oven.addCabinet('Upper Cabinet', [{ mfgCode: null, namespaceId: PositionTag.Top.namespaceId, tag: PositionTag.Top.tag, label: PositionTag.Top.label }]);

// Cooktop Example
const cooktop = new Cooktop('Cooktop', 'CT1234567890');
cooktop.addSurface('Surface Top Left', [
  { mfgCode: null, namespaceId: PositionTag.Top.namespaceId, tag: PositionTag.Top.tag, label: PositionTag.Top.label },
  { mfgCode: null, namespaceId: PositionTag.Left.namespaceId, tag: PositionTag.Left.tag, label: PositionTag.Left.label },
]);

// Refrigerator Example
const refrigerator = new Refrigerator('Refrigerator', 'RE1234567890');
refrigerator.addCabinet('Refrigerator Top', [
  { mfgCode: null, namespaceId: PositionTag.Top.namespaceId, tag: PositionTag.Top.tag, label: 'Refrigerator Top' },
  { mfgCode: null, namespaceId: RefrigeratorTag.Refrigerator.namespaceId, tag: RefrigeratorTag.Refrigerator.tag, label: RefrigeratorTag.Refrigerator.label },
]);

When developing Matterbridge plugins, do not include matterbridge or @matter as a dependency, devDependency, or peerDependency in your package.json.

Why this is required

1. Singleton Requirement: There must be exactly one instance of matterbridge and matter.js in the entire node_modules tree.
2. Module Resolution Conflict: Matterbridge loads plugins as ESM modules using dynamic import(). Node.js module resolution prioritizes a plugin's local node_modules over Matterbridge's node_modules. If a plugin contains its own version of matterbridge, it will use that version instead of the host's version, causing runtime errors and breaking the plugin system.

Best Practices

• Production Publishing: Always publish plugins for production with devDependencies removed to prevent accidental installation of unnecessary packages.
• Dependency Locking: Use npm shrinkwrap to lock direct dependencies, ensuring the user's environment matches your development environment exactly.

Some devices act as controllers (clients) that consume clusters implemented on remote endpoints. Matterbridge handles this via MatterbridgeBindingServer.

Option 1: Explicitly adding client clusters

If you know the specific cluster IDs required, use createDefaultBindingClusterServer(clientList). This registers the IDs in the Binding cluster's clientList and the Descriptor cluster's clientList.

import { ClosureControl } from '@matter/types/clusters/closure-control';
import { closureController } from 'matterbridge';

const device = new MatterbridgeEndpoint(closureController, { id: 'MyClosureController' })
  .createDefaultBindingClusterServer([ClosureControl.id])
  .addRequiredClusters();

await this.registerDevice(device);

Option 2: Automatic client clusters from Device Type

If your DeviceTypeDefinition includes requiredClientClusters or optionalClientClusters, you can populate the binding automatically:

import { closureController } from 'matterbridge';

const device = new MatterbridgeEndpoint(closureController, { id: 'MyClosureController' })
  .addRequiredClusterServers()
  .addRequiredClusterClients() // Automatically adds clusters required by the definition
  .addOptionalClusterClients(); // Automatically adds optional clusters from the definition

await this.registerDevice(device);

import { ClosureControl } from '@matter/types/clusters/closure-control';
import { closureController } from 'matterbridge';

const device = new MatterbridgeEndpoint(closureController, { id: 'MyClosureController' })
  .createDefaultBindingClusterServer([ClosureControl.id]) // advertises ClosureControl as a client cluster
  .addRequiredClusters();

await this.registerDevice(device);

Matterbridge detects the Bun runtime using isBun() and switches package management and path resolution logic accordingly. Key features implemented for Bun include:

• Global Package Resolution: bun link is used to register the local build as the global matterbridge package, allowing plugins to resolve import 'matterbridge' correctly.
• Global Module Discovery: getGlobalNodeModules() resolves to the Bun global modules directory (derived from $BUN_INSTALL or ~/.bun) instead of npm root -g.
• Plugin Management: PluginManager resolves plugins from the Bun global modules directory. Plugin installation, uninstallation, and Matterbridge updates use bun commands instead of npm.
• Docker Recovery: Auto-reinstallation during Docker recreate uses bun if the runtime is detected as Bun.
• Local Plugins: When running on Bun, the --add command for local plugins skips the npm link matterbridge step because bun link already provides the necessary resolution.