[Discussion] MatterController API

[mfucci]

This goal of this thread is to discuss the APIs that the MatterController library will provide.

APIs can be grouped into 3 categories:

1. initial setup
2. device discovery
3. device operation

Current proposal:

Initial setup
There are two different scenarios, either MatterController is the root of the fabric or another controller is the root and he needs to be commissioned.

Commission by another fabric controller:
MatterController.awaitCommissioning(commissioningOptions): Promise

Root of the fabric:
MatterController.createRootFabric(): RootFabric
MatterController.discoverCommissionableDevices(): Promise<DeviceAddress[]>
MatterController.commissionDevice(fabric: RootFabric, deviceAddress, commissioningOptions): Promise

Note: with those APIs, the controller can be commissioned multiple times, create multiple fabrics and be hybrid...

Device discovery
MatterController.discoverDevices(fabric: Fabric): Promise<MatterDevice[]>
MatterController,getDevice(nodeId): Promise

Device operation
MatterDevice.getCluster(ClusterDef): ClusterClient
ClusterClient: autogenerated using some Typescript magic

• getAttributeName: Promise
• set[AttributeName](value: AttributeType): Promise
• subscribe[AttributeName](callback: (value: AttributeType) => void): Promise
• [command](args: CommandArgs): Promise

[mfucci]

Usage example:

import { MatterController } from "./matter/MatterController";

const controller = new MatterController();
const temperatureSensor = controller.getNode(1).getCluster(TemperatureSensorCluster);
const acSwitch = controller.getNode(2).getCluster(OnOffCluster);

acSwitch.subscribeOn(on => {
    if (on) {
        console.log("AC has been turned on");
    } else {
        console.log("AC has been turned off");
    }
});

temperatureSensor.subscribeTemperature(temperature => {
    console.log(`Temperature is: ${temperature}`);
    const acOn = acSwitch.getOn();
    if (!acOn && temperature > Fahrenheit(80)) acSwitch.on();
    if (acOn && temperature < Fahrenheit(75)) acSwitch.off();
}, { interval: Minutes(5) });

[jottinger]

Where does TemperatureSensorCluster come from in this? The biggest barrier Matter has is in lack of clear docs; without diminishing the importance of the border router, I think the most emphasis should be on border router discovery for clients, and interacting with the matter network as a client - such that we can query what objects are in the mesh, and interact with them. We may already have the feature set, but it NEEDS documentation.

[Apollon77]

I also had written this in other discussion. In fac the "MatterController" needs to expose methods also like "getEndpoints/Devices" and in fact needs to return all clusters and how they belong together as a "structure" or the IDS in a way that you can iterate over it yourself.

The above example is"I know that there is a tempateratureController on that device with number 1.

In fcat we just start to implement out all clusters (starting with the basic ones), so there will be some more stuff needed for the above example to work

[jottinger]

I'm all for being able to set up a border router via software, but honestly, most clients will have a border router locally anyway - Eero, Google Nest, even the Nanoleaf has a border router now, so border routers tend to be local without having to do anything. But I think it's of prime importance that clients be able to FIND the border router and mesh easily - it's not difficult, they're available over MDNS, but that exposes the individual routers and not the mesh - and interact with the mesh easily as well.

[mfucci]

TemperatureSensorCluster: my thoughts was that Matter devices are commissioned either through node-matter or another controller and node-matter is added part of the fabric, and that the user will know the node #1 is the temperature sensor

Device discovery: to discover Matter devices on the network, the logic is already implemented in MDNS scanner but not exposed yet. To know what device is what, device manufacturer + device type + productName + nodeLabel should work well.

Border router: as far as I understood, those ones act as network components for Thread and should be transparent for Matter perspective. Everyone will be part of the same Thread mesh, regardless which border router is used and how many are used. The route from one device to another can be automatically updated to use another border router.. This is part of Thread, not Matter.
Can you explain in more details your concerns with the border routers?

[ilbertt]

Are there any updates on this?
I guess that now the node-matter implementation of the Matter Controller can only perform the commissioning via IP right?

[Apollon77]

The work is in progress. I woork on a new high level API which will then include this. Right now we only have support for IP (but Thread should be possible using a border Router with a "to IPv6 interface" ... I just ordered some stuff to try that soon but did not yet arrived ;-) ... With some other plans would still need at least 2-3 weeks ...

[Apollon77]

Whats you plan and usecase?

[ilbertt]

The idea would be to expose Matter devices through the Web of Things standard, in order to make them reachable through the Internet in a standard way. The only well supported WoT implementation is written in node, and that's why we need Matter in node. I was trying to bind the official Matter C++ SDK using Node C++ addons, but I cannot understand how to import it correctly. I guess this is one of the reasons you started developing node-matter right? 😅

[Apollon77]

The main reasy was that we do not wanted a native dependency hell :-) So in fact yes. So stay tuned for the new high level API, that will allow bridged devices also

[ilbertt]

Great! Looking forward to it!