@matter/types 0.13.0-alpha.0-20250304-d4a7592a4 → 0.13.0-alpha.0-20250311-3eb0af5f2

package/src/clusters/ecosystem-information.ts

@@ -0,0 +1,200 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*** THIS FILE IS GENERATED, DO NOT EDIT ***/
+
+import { MutableCluster } from "../cluster/mutation/MutableCluster.js";
+import { TlvOptionalField, TlvField, TlvObject } from "../tlv/TlvObject.js";
+import { TlvString } from "../tlv/TlvString.js";
+import { TlvEpochUs } from "../tlv/TlvNumber.js";
+import { TlvEndpointNumber } from "../datatype/EndpointNumber.js";
+import { TlvArray } from "../tlv/TlvArray.js";
+import { Descriptor } from "./descriptor.js";
+import { TlvFabricIndex } from "../datatype/FabricIndex.js";
+import { TypeFromSchema } from "../tlv/TlvSchema.js";
+import { TlvLocationdesc } from "../globals/Locationdesc.js";
+import { Identity } from "#general";
+import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
+
+export namespace EcosystemInformation {
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 9.18.4.1
+     */
+    export const TlvEcosystemDevice = TlvObject({
+        /**
+         * This field shall indicate the device’s name, which is provided externally if the user consents. (For
+         * example, provided by the user in an ecosystem specific interface.)
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.1
+         */
+        deviceName: TlvOptionalField(0, TlvString.bound({ maxLength: 64 })),
+
+        /**
+         * This field shall be present and set if the DeviceName field is present.
+         *
+         * This field shall indicate the timestamp of when the DeviceName was last modified.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.2
+         */
+        deviceNameLastEdit: TlvOptionalField(1, TlvEpochUs),
+
+        /**
+         * This field shall indicate the endpoint this EcosystemDeviceStruct is associated with on this Bridge.
+         *
+         * This field shall be present and set to a valid endpoint if the device is accessible through the bridge.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.3
+         */
+        bridgedEndpoint: TlvOptionalField(2, TlvEndpointNumber),
+
+        /**
+         * This field shall indicate the endpoint this EcosystemDeviceStruct is associated with on the original device
+         * represented by this bridge’s Bridged Node. If this bridge is receiving the device from another bridge, then
+         * the OriginalEndpoint field value would be the same on both bridges. This field shall be present and set to a
+         * valid endpoint on the original device if that device is a Matter device.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.4
+         */
+        originalEndpoint: TlvOptionalField(3, TlvEndpointNumber),
+
+        /**
+         * This field shall indicate all of the DeviceTypes within the DeviceTypeList in the Descriptor Cluster
+         * associated with this EcosystemDeviceStruct entry.
+         *
+         * This field shall contain a list of valid device type ids.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.5
+         */
+        deviceTypes: TlvField(4, TlvArray(Descriptor.TlvDeviceType)),
+
+        /**
+         * This field shall specify the EcosystemLocationStruct entries in the LocationDirectory attribute associated
+         * with this EcosystemDeviceStruct.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.6
+         */
+        uniqueLocationIDs: TlvField(5, TlvArray(TlvString, { maxLength: 64 })),
+
+        /**
+         * This field shall indicate the timestamp of when the UniqueLocationIDs was last modified.
+         *
+         * NOTE
+         *
+         * If multiple server instances update the UniqueLocationIDs field at the same time, it is possible one of the
+         * updates will be missed. This is considered an acceptable limitation to reduce the complexity of the design.
+         * Since this is meant to be provided from user input, it is unlikely these signals would be happening at one
+         * time.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.1.7
+         */
+        uniqueLocationIDsLastEdit: TlvField(6, TlvEpochUs),
+
+        fabricIndex: TlvField(254, TlvFabricIndex)
+    });
+
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 9.18.4.1
+     */
+    export interface EcosystemDevice extends TypeFromSchema<typeof TlvEcosystemDevice> {}
+
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 9.18.4.2
+     */
+    export const TlvEcosystemLocation = TlvObject({
+        /**
+         * This field shall indicate a unique identifier for a specific Ecosystem Information Cluster server instance
+         * representing the location independent of its LocationDescriptor field.
+         *
+         * UniqueLocationID can be used by the client to determine if the change is a relocation of the device or just
+         * a renaming of the location.
+         *
+         * No guarantees are given for consistency of the ID between server instances. The same location may be
+         * represented by different IDs on different Ecosystem Information Cluster server instances, so only the
+         * history from a single server instance should be considered when evaluating a change.
+         *
+         * UniqueLocationID shall be changed when the LocationDescriptor changes from one existing location to another
+         * location as a result of an external interaction. (For example, the user changes the location assignment.)
+         *
+         * UniqueLocationID shall NOT be changed when the LocationDescriptor changes name, but still represents the
+         * same location. (For example, the user renames a room.)
+         *
+         * UniqueLocationID shall be changed when LocationDescriptor changes as a result of another Ecosystem
+         * Information Cluster server instance changing and the UniqueLocationID on the remote server instance also
+         * changes.
+         *
+         * UniqueLocationID shall NOT be changed when LocationDescriptor changes as a result of another Ecosystem
+         * Information Cluster server instance changing and the UniqueLocationID on the remote server instance does not
+         * change.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.2.1
+         */
+        uniqueLocationId: TlvField(0, TlvString.bound({ maxLength: 64 })),
+
+        /**
+         * This field shall indicate the location (e.g. living room, driveway) and associated metadata that is provided
+         * externally if the user consents. (For example, provided by the user in an ecosystem specific interface.)
+         *
+         * "Location" in this context is typically used by the user’s grouping into rooms, areas or other logical
+         * groupings of how devices are used. So a device might be part of multiple such "Locations"s.
+         *
+         * @see {@link MatterSpecification.v13.Core} § 9.18.4.2.2
+         */
+        locationDescriptor: TlvField(1, TlvLocationdesc),
+
+        locationDescriptorLastEdit: TlvField(2, TlvEpochUs),
+        fabricIndex: TlvField(254, TlvFabricIndex)
+    });
+
+    /**
+     * @see {@link MatterSpecification.v13.Core} § 9.18.4.2
+     */
+    export interface EcosystemLocation extends TypeFromSchema<typeof TlvEcosystemLocation> {}
+
+    /**
+     * @see {@link Cluster}
+     */
+    export const ClusterInstance = MutableCluster({ id: 0x750, name: "EcosystemInformation", revision: 1 });
+
+    /**
+     * The Ecosystem Information Cluster provides extended device information for all the logical devices represented
+     * by a Bridged Node. The Ecosystem Information Cluster presents the view of device name and location metadata for
+     * presentation by a client of the cluster to a user. This cluster is intended to support Fabric Synchronization
+     * and be present on an endpoint with the BridgedNode device type listed in the DeviceTypeList of the endpoint’s
+     * Descriptor cluster.
+     *
+     * This augments the Bridged Device Basic Information Cluster in the following ways:
+     *
+     *   • The Ecosystem Information Cluster adds support for providing a name and location for individual endpoints.
+     *     (The endpoints do not need to be present on the Bridge for their name and location information to be
+     *     present.)
+     *
+     *   • The Ecosystem Information Cluster adds metadata to support conflict resolution between multiple sources of
+     *     the name and location data.
+     *
+     *   • The Ecosystem Information Cluster supports user control for the presence of the name and location
+     *     information by specifying more restricted access.
+     *
+     * A client SHOULD use the information provided by the Ecosystem Information Cluster to help the user organize and
+     * interact with their devices. Some examples may include:
+     *
+     *   • Directly organizing and labeling the devices in a client’s user interface.
+     *
+     *   • Providing hints in the user interface, which can assist the user in organizing and labeling their devices.
+     *
+     * For the purposes of the Ecosystem Information Cluster section, an instance of the Ecosystem Information Cluster
+     * will be referred to as an "instance".
+     *
+     * @see {@link MatterSpecification.v13.Core} § 9.18
+     */
+    export interface Cluster extends Identity<typeof ClusterInstance> {}
+
+    export const Cluster: Cluster = ClusterInstance;
+    export const Complete = Cluster;
+}
+
+export type EcosystemInformationCluster = EcosystemInformation.Cluster;
+export const EcosystemInformationCluster = EcosystemInformation.Cluster;
+ClusterRegistry.register(EcosystemInformation.Complete);

package/src/clusters/electrical-energy-measurement.ts

@@ -125,31 +125,31 @@ export namespace ElectricalEnergyMeasurement {
         endTimestamp: TlvOptionalField(2, TlvEpochS),
 
         /**
-         * This field shall indicate the seconds since boot at the beginning of the period during which the value of
-         * the Energy field was measured.
+         * This field shall indicate the time elapsed since boot at the beginning of the period during which the value
+         * of the Energy field was measured.
          *
-         * If this EnergyMeasurementStruct represents cumulative energy, this field shall be omitted.
+         * If this EnergyMeasurementStruct represents cumulative energy, this field shall be omitted. Otherwise, if the
+         * server had not yet determined the time in UTC at the start of the measurement
          *
-         * Otherwise, if the server had not yet determined the time in UTC at the start of the measurement period, or
-         * does not have the capability of determining the time in UTC, this field shall be indicated.
+         * period, or does not have the capability of determining the time in UTC, this field shall be indicated.
          *
          * Otherwise, if the server had determined the time in UTC at or before the beginning of the measurement
-         * period, this field may be omitted; if it is indicated, its value shall be the seconds since boot at the UTC
-         * time indicated in StartTimestamp.
+         * period, this field may be omitted; if it is indicated, its value shall be the time elapsed since boot at the
+         * UTC time indicated in StartTimestamp.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 2.12.5.1.4
          */
         startSystime: TlvOptionalField(3, TlvSysTimeMS),
 
         /**
-         * This field shall indicate the seconds since boot at the end of the period during which the value of the
+         * This field shall indicate the time elapsed since boot at the end of the period during which the value of the
          * Energy field was measured.
          *
          * If the server had not yet determined the time in UTC by the end of the measurement period, or does not have
          * the capability of determining the time in UTC, this field shall be indicated.
          *
          * Otherwise, if the server had determined the time in UTC by the end of the measurement period, this field may
-         * be omitted; if it is indicated, its value shall be the seconds since boot at the UTC time indicated in
+         * be omitted; if it is indicated, its value shall be the time elapsed since boot at the UTC time indicated in
          * EndTimestamp.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 2.12.5.1.5
@@ -200,9 +200,8 @@ export namespace ElectricalEnergyMeasurement {
          * This field shall indicate the timestamp in UTC when the value of the Energy field on the
          * CumulativeEnergyExported attribute was most recently zero.
          *
-         * If the server had determined the time in UTC when the value of the Energy field on the Cumula
-         *
-         * tiveEnergyExported attribute was most recently zero, this field shall be indicated.
+         * If the server had determined the time in UTC when the value of the Energy field on the
+         * CumulativeEnergyExported attribute was most recently zero, this field shall be indicated.
          *
          * Otherwise, if the server had not yet determined the time in UTC when the value of the Energy field on the
          * CumulativeEnergyExported attribute was most recently zero, or does not have the capability of determining
@@ -216,7 +215,7 @@ export namespace ElectricalEnergyMeasurement {
         exportedResetTimestamp: TlvOptionalField(1, TlvNullable(TlvEpochS)),
 
         /**
-         * This field shall indicate the seconds since boot when the value of the Energy field on the
+         * This field shall indicate the time elapsed since boot when the value of the Energy field on the
          * CumulativeEnergyImported attribute was most recently zero.
          *
          * If the server had not yet determined the time in UTC when the value of the Energy field on the
@@ -225,14 +224,14 @@ export namespace ElectricalEnergyMeasurement {
          *
          * Otherwise, if the server had determined the time in UTC when the value of the Energy field on the
          * CumulativeEnergyImported attribute was most recently zero, this field may be omitted; if it is indicated,
-         * its value shall be the seconds since boot at the UTC time indicated in ImportedResetTimestamp.
+         * its value shall be the time elapsed since boot at the UTC time indicated in ImportedResetTimestamp.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 2.12.5.2.3
          */
         importedResetSystime: TlvOptionalField(2, TlvNullable(TlvSysTimeMS)),
 
         /**
-         * This field shall indicate the seconds since boot when the value of the Energy field on the
+         * This field shall indicate the time elapsed since boot when the value of the Energy field on the
          * CumulativeEnergyExported attribute was most recently zero.
          *
          * If the server had not yet determined the time in UTC when the value of the Energy field on the
@@ -241,7 +240,7 @@ export namespace ElectricalEnergyMeasurement {
          *
          * Otherwise, if the server had determined the time in UTC when the value of the Energy field on the
          * CumulativeEnergyExported attribute was most recently zero, this field may be omitted; if it is indicated,
-         * its value shall be the seconds since boot at the UTC time indicated in ImportedResetTimestamp.
+         * its value shall be the time elapsed since boot at the UTC time indicated in ImportedResetTimestamp.
          *
          * @see {@link MatterSpecification.v13.Cluster} § 2.12.5.2.4
          */