Bug Report: Plugin-created devices remain inactive and never receive endpoint numbers

[signal15]

Maybe I'm doing something wrong here.

Environment

• Matterbridge Version: 3.3.8 (also tested with 3.4.5)
• Node.js Version: v20.19.1
• npm Version: 10.8.2
• Operating System: Raspbian GNU/Linux 11 (bullseye)
• Architecture: armv7l (Raspberry Pi 3)
• Bridge Mode: bridge (not childbridge)
• Plugin Type: DynamicPlatform

Summary

When creating a DynamicPlatform plugin, devices created with MatterbridgeEndpoint and registered via registerDevice() remain in an "inactive" state and never receive endpoint numbers. The devices are never added to the Matter endpoint tree, even though registerDevice() completes without throwing an error.

Matterbridge's own virtual devices (RestartMatterbridge, UpdateMatterbridge) work correctly and receive endpoint numbers 2 and 3.

Behavior by Version

Matterbridge 3.3.8

• registerDevice() completes without error
• Devices remain "inactive" with number: undefined
• No error messages are logged
• Devices never become "ready"

Matterbridge 3.4.5

• registerDevice() attempts to add devices to the Matter tree
• Fails with conformance error: Conformance "M": Matter requires you to set this attribute (135) for descriptor.state.0.revision
• Error: "Behaviors have errors" when adding bridged endpoint

Minimal Reproduction

1. Create plugin directory structure

matterbridge-test-plugin/
├── src/
│   ├── index.ts
│   └── platform.ts
├── package.json
└── tsconfig.json

2. package.json

{
  "name": "matterbridge-test-plugin",
  "version": "1.0.0",
  "description": "Minimal reproduction of device registration issue",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  },
  "engines": {
    "node": ">=18.0.0"
  },
  "devDependencies": {
    "@types/node": "^20.10.0",
    "typescript": "^5.3.0"
  }
}

3. tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

4. src/index.ts

import { MatterbridgeDynamicPlatform, PlatformConfig, PlatformMatterbridge } from 'matterbridge';
import { AnsiLogger } from 'matterbridge/logger';
import { TestPlatform } from './platform.js';

export default function createPlatform(
  matterbridge: PlatformMatterbridge,
  log: AnsiLogger,
  config: PlatformConfig,
): MatterbridgeDynamicPlatform {
  return new TestPlatform(matterbridge, log, config);
}

export { TestPlatform } from './platform.js';

5. src/platform.ts

import {
  MatterbridgeDynamicPlatform,
  MatterbridgeEndpoint,
  PlatformConfig,
  PlatformMatterbridge,
  onOffLight,
  dimmableLight,
} from 'matterbridge';
import { AnsiLogger } from 'matterbridge/logger';

export class TestPlatform extends MatterbridgeDynamicPlatform {
  constructor(matterbridge: PlatformMatterbridge, log: AnsiLogger, config: PlatformConfig) {
    super(matterbridge, log, config);
    this.log.logName = 'TestPlatform';
  }

  override async onStart(reason?: string): Promise<void> {
    this.log.info(`Starting test platform${reason ? ` (${reason})` : ''}`);

    // Create a simple on/off light device
    const device1 = new MatterbridgeEndpoint(
      onOffLight,
      { id: 'test-light-1' },
      true, // debug
    );

    device1.createDefaultBridgedDeviceBasicInformationClusterServer(
      'Test Light 1',        // deviceName
      'test-001',            // serialNumber
      0x0001,                // vendorId
      'TestVendor',          // vendorName
      'test-light-1',        // productName
    );

    device1.addRequiredClusterServers();

    device1.addCommandHandler('on', async () => {
      this.log.info('Light 1 ON command received');
    });
    device1.addCommandHandler('off', async () => {
      this.log.info('Light 1 OFF command received');
    });

    // Register the device
    try {
      this.log.info('Registering device: Test Light 1');
      await this.registerDevice(device1);
      this.log.info('registerDevice() completed for Test Light 1');
    } catch (err) {
      this.log.error(`Failed to register device: ${err}`);
    }

    // Create a dimmable light device
    const device2 = new MatterbridgeEndpoint(
      dimmableLight,
      { id: 'test-dimmer-1' },
      true,
    );

    device2.createDefaultBridgedDeviceBasicInformationClusterServer(
      'Test Dimmer 1',
      'test-002',
      0x0001,
      'TestVendor',
      'test-dimmer-1',
    );

    device2.addRequiredClusterServers();

    device2.addCommandHandler('on', async () => {
      this.log.info('Dimmer 1 ON command received');
    });
    device2.addCommandHandler('off', async () => {
      this.log.info('Dimmer 1 OFF command received');
    });
    device2.addCommandHandler('moveToLevel', async ({ request }) => {
      this.log.info(`Dimmer 1 MOVE_TO_LEVEL: ${request.level}`);
    });

    try {
      this.log.info('Registering device: Test Dimmer 1');
      await this.registerDevice(device2);
      this.log.info('registerDevice() completed for Test Dimmer 1');
    } catch (err) {
      this.log.error(`Failed to register device: ${err}`);
    }

    this.log.info('onStart completed');
  }

  override async onConfigure(): Promise<void> {
    this.log.info('onConfigure called');
  }

  override async onShutdown(reason?: string): Promise<void> {
    this.log.info(`Shutting down${reason ? ` (${reason})` : ''}`);
  }
}

6. Plugin config file (~/.matterbridge/matterbridge-test-plugin.config.json)

{
  "name": "matterbridge-test-plugin",
  "type": "DynamicPlatform"
}

7. Build and install

cd matterbridge-test-plugin
npm install
npm run build
matterbridge -add .
matterbridge -bridge

Expected Behavior

After registerDevice() is called, the devices should:

1. Be added to the Matter endpoint tree (aggregator)
2. Receive endpoint numbers (e.g., 4, 5, ...)
3. Transition from "inactive" to "ready" state
4. Appear as bridged devices when the bridge is commissioned

Actual Behavior

Matterbridge 3.3.8 Log Output

[22:35:24.582] [Endpoint] Matterbridge ready endpoint#: 0 type: RootNode (0x16)
[22:35:24.643] [Endpoint] Matterbridge.Matterbridge ready endpoint#: 1 type: Aggregator (0xe)
[22:35:24.881] [Endpoint] Matterbridge.Matterbridge.RestartMatterbridge:outlet ready endpoint#: 2 type: OnOffPlugInUnit (0x10a)
[22:35:24.982] [Endpoint] Matterbridge.Matterbridge.UpdateMatterbridge:outlet ready endpoint#: 3 type: OnOffPlugInUnit (0x10a)

[22:35:34.861] [test-light-1] new MatterbridgeEndpoint: 0x0100-MA-onofflight mode: undefined id: test-light-1 number: undefined taglist: undefined
[22:35:34.873] [Test Light 1] addRequiredClusterServers for test-light-1
[22:35:34.880] [TestPlatform] Registering device: Test Light 1
[22:35:34.882] [TestPlatform] Device with name Test Light 1 has no bridgedNode device type. Adding it...
[22:35:34.882] [TestPlatform] registerDevice() completed for Test Light 1

# Device stays inactive - never gets endpoint number
# When trying to update attributes later:
[22:36:05.863] [Test Light 1] setAttribute onOff.onOff error: Endpoint test-light-1:undefined is in the inactive state

Key observations:

• Virtual devices (RestartMatterbridge, UpdateMatterbridge) become "ready" with endpoint numbers 2 and 3
• Plugin devices show number: undefined and never transition to "ready"
• No error is thrown by registerDevice()
• The message "Device with name ... has no bridgedNode device type. Adding it..." appears, indicating registerDevice() is processing the device
• When attempting to update device attributes, error shows device is "inactive"

Matterbridge 3.4.5 Log Output

[22:12:37.755] [Matterbridge] Error adding bridged endpoint Master Bath Vanity (dimmer-01-1) for plugin matterbridge-test-plugin: Behaviors have errors
stack: EndpointBehaviorsError [AggregateError]: Behaviors have errors
    at file:///usr/lib/node_modules/matterbridge/node_modules/@matter/node/dist/esm/endpoint/properties/Behaviors.js:161:21
    at crash (file:///usr/lib/node_modules/matterbridge/node_modules/@matter/node/dist/esm/behavior/internal/BehaviorBacking.js:64:22)
  Caused by: [conformance] Validating Matterbridge.Matterbridge.part2.descriptor.state.0.revision: Conformance "M": Matter requires you to set this attribute (135)
    at requireValue (file:///usr/lib/node_modules/matterbridge/node_modules/@matter/node/dist/esm/behavior/state/validation/conformance-compiler.js:352:13)
    at Object.revision (file:///usr/lib/node_modules/matterbridge/node_modules/@matter/node/dist/esm/behavior/state/validation/conformance.js:13:15)

In 3.4.5, the actual root cause is visible: the revision attribute in the descriptor cluster's deviceTypeList is not being set, causing a Matter conformance validation failure.

Investigation Notes

1. Tried registering in onStart(): Same result - devices remain inactive
2. Tried registering in onConfigure(): Same result
3. Tried using [bridgedNode, onOffLight] array: Same conformance error in 3.4.5
4. Tried different device types (onOffOutlet, dimmableOutlet): Same error
5. Virtual devices work: RestartMatterbridge and UpdateMatterbridge devices created by Matterbridge itself work correctly
6. The difference: Virtual devices are created via addVirtualDevice() helper, not through the plugin registerDevice() path

Hypothesis

The issue appears to be in how registerDevice() (or the underlying #addBridgedEndpoint) constructs the endpoint's descriptor cluster. The deviceTypeList entries are missing the required revision field:

// deviceTypeList entries should look like:
{ deviceType: 0x0100, revision: 2 }  // onOffLight with revision

// But they appear to be missing revision:
{ deviceType: 0x0100 }  // Missing revision field

The virtual devices created by addVirtualDevice() must be setting this correctly, while the path through registerDevice() is not.

Workaround Attempts

• None successful. All device types tried result in the same behavior.

Additional Context

This is blocking the development of a Matterbridge plugin for the Litetouch 2000 lighting control system. The plugin successfully:

• Connects to the lighting controller via serial port
• Polls for status updates
• Creates MatterbridgeEndpoint devices
• Registers devices without error

But the devices never appear in Matter controllers because they're never added to the endpoint tree.

Related

The error pattern (AggregateError: Behaviors have errors) has been seen in related projects:

• https://github.com/t0bst4r/home-assistant-matter-hub (similar conformance issues)

---

Request: Could you please investigate why plugin-created devices via registerDevice() don't receive endpoint numbers and remain inactive? The 3.4.5 error message about missing revision in descriptor.state.0 seems to point to the root cause.

[signal15]

Ok, not a bug. It was a PEBKAC error.

The root cause was missing the bridgedNode device type in the device type array. When creating Matter bridged devices, you must include bridgedNode as the first device type:

// BROKEN - single device type
new MatterbridgeEndpoint(dimmableLight, ...)

// WORKING - array with bridgedNode first
new MatterbridgeEndpoint([bridgedNode, dimmableLight], ...)

The bridgedNode device type (0x0013) includes the required revision field (value 3) that Matter's descriptor cluster validation requires. Without it, Matterbridge 3.4.5's stricter validation rejected the devices with "Conformance M: Matter requires you to set this attribute" errors. In 3.3.8, the devices just silently stayed inactive.

[Luligu]

Ok.
I don't think so.

Check if you correctly linked the active instance of matterbridge to the plugin.