@matter/types 0.16.0-alpha.0-20251022-5a69ce65a → 0.16.0-alpha.0-20251027-17770fb28

package/src/clusters/ecosystem-information.ts

@@ -11,11 +11,11 @@ import { FabricScopedAttribute } from "../cluster/Cluster.js";
 import { TlvArray } from "../tlv/TlvArray.js";
 import { TlvOptionalField, TlvField, TlvObject } from "../tlv/TlvObject.js";
 import { TlvString } from "../tlv/TlvString.js";
-import { TlvEpochUs } from "../tlv/TlvNumber.js";
+import { TlvEpochUs, TlvUInt16 } from "../tlv/TlvNumber.js";
 import { TlvEndpointNumber } from "../datatype/EndpointNumber.js";
-import { Descriptor } from "./descriptor.js";
-import { TlvFabricIndex } from "../datatype/FabricIndex.js";
+import { TlvDeviceTypeId } from "../datatype/DeviceTypeId.js";
 import { TypeFromSchema } from "../tlv/TlvSchema.js";
+import { TlvFabricIndex } from "../datatype/FabricIndex.js";
 import { AccessLevel } from "#model";
 import { TlvLocationdesc } from "../globals/Locationdesc.js";
 import { Identity } from "#general";
@@ -23,23 +23,51 @@ import { ClusterRegistry } from "../cluster/ClusterRegistry.js";
 
 export namespace EcosystemInformation {
     /**
-     * @see {@link MatterSpecification.v141.Core} § 9.18.4.1
+     * The device type and revision define endpoint conformance to a release of a device type definition. See the Data
+     * Model specification for more information.
+     *
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.1
+     */
+    export const TlvDeviceType = TlvObject({
+        /**
+         * This shall indicate the device type definition.
+         *
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.1.1
+         */
+        deviceType: TlvField(0, TlvDeviceTypeId),
+
+        /**
+         * This is the implemented revision of the device type definition.
+         *
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.1.2
+         */
+        revision: TlvField(1, TlvUInt16.bound({ min: 1 }))
+    });
+
+    /**
+     * The device type and revision define endpoint conformance to a release of a device type definition. See the Data
+     * Model specification for more information.
+     *
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.1
+     */
+    export interface DeviceType extends TypeFromSchema<typeof TlvDeviceType> {}
+
+    /**
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.2
      */
     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.v141.Core} § 9.18.4.1.1
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.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.v141.Core} § 9.18.4.1.2
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.2
          */
         deviceNameLastEdit: TlvOptionalField(1, TlvEpochUs),
 
@@ -48,7 +76,7 @@ export namespace EcosystemInformation {
          *
          * This field shall be present and set to a valid endpoint if the device is accessible through the bridge.
          *
-         * @see {@link MatterSpecification.v141.Core} § 9.18.4.1.3
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.3
          */
         bridgedEndpoint: TlvOptionalField(2, TlvEndpointNumber),
 
@@ -58,7 +86,7 @@ export namespace EcosystemInformation {
          * 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.v141.Core} § 9.18.4.1.4
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.4
          */
         originalEndpoint: TlvOptionalField(3, TlvEndpointNumber),
 
@@ -68,29 +96,27 @@ export namespace EcosystemInformation {
          *
          * This field shall contain a list of valid device type ids.
          *
-         * @see {@link MatterSpecification.v141.Core} § 9.18.4.1.5
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.5
          */
-        deviceTypes: TlvField(4, TlvArray(Descriptor.TlvDeviceType)),
+        deviceTypes: TlvField(4, TlvArray(TlvDeviceType)),
 
         /**
          * This field shall specify the EcosystemLocationStruct entries in the LocationDirectory attribute associated
          * with this EcosystemDeviceStruct.
          *
-         * @see {@link MatterSpecification.v141.Core} § 9.18.4.1.6
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.6
          */
         uniqueLocationIDs: TlvField(5, TlvArray(TlvString, { maxLength: 64 })),
 
         /**
          * This field shall indicate the timestamp of when the UniqueLocationIDs was last modified.
          *
-         * > [!NOTE]
+         * 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.
          *
-         * > 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.v141.Core} § 9.18.4.1.7
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.2.7
          */
         uniqueLocationIDsLastEdit: TlvField(6, TlvEpochUs),
 
@@ -98,12 +124,12 @@ export namespace EcosystemInformation {
     });
 
     /**
-     * @see {@link MatterSpecification.v141.Core} § 9.18.4.1
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.2
      */
     export interface EcosystemDevice extends TypeFromSchema<typeof TlvEcosystemDevice> {}
 
     /**
-     * @see {@link MatterSpecification.v141.Core} § 9.18.4.2
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.3
      */
     export const TlvEcosystemLocation = TlvObject({
         /**
@@ -129,25 +155,27 @@ export namespace EcosystemInformation {
          * Information Cluster server instance changing and the UniqueLocationID on the remote server instance does not
          * change.
          *
-         * @see {@link MatterSpecification.v141.Core} § 9.18.4.2.1
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.3.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.)
+         * 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.v141.Core} § 9.18.4.2.2
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.3.2
          */
         locationDescriptor: TlvField(1, TlvLocationdesc),
 
         /**
          * This field shall indicate the timestamp of when the LocationDescriptor was last modified.
          *
-         * @see {@link MatterSpecification.v141.Core} § 9.18.4.2.3
+         * @see {@link MatterSpecification.v141.Core} § 9.17.4.3.3
          */
         locationDescriptorLastEdit: TlvField(2, TlvEpochUs),
 
@@ -155,7 +183,7 @@ export namespace EcosystemInformation {
     });
 
     /**
-     * @see {@link MatterSpecification.v141.Core} § 9.18.4.2
+     * @see {@link MatterSpecification.v141.Core} § 9.17.4.3
      */
     export interface EcosystemLocation extends TypeFromSchema<typeof TlvEcosystemLocation> {}
 
@@ -173,7 +201,7 @@ export namespace EcosystemInformation {
              * this will contain a single entry, but may grow with more complex device compositions (e.g. another
              * bridge.) An empty list indicates that the information is not available.
              *
-             * @see {@link MatterSpecification.v141.Core} § 9.18.5.1
+             * @see {@link MatterSpecification.v141.Core} § 9.17.5.1
              */
             deviceDirectory: FabricScopedAttribute(
                 0x0,
@@ -190,7 +218,7 @@ export namespace EcosystemInformation {
              *
              * LocationDirectory entries shall be removed if there is no DeviceDirectory that references it.
              *
-             * @see {@link MatterSpecification.v141.Core} § 9.18.5.2
+             * @see {@link MatterSpecification.v141.Core} § 9.17.5.2
              */
             locationDirectory: FabricScopedAttribute(
                 0x1,
@@ -229,7 +257,7 @@ export namespace EcosystemInformation {
      * 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.v141.Core} § 9.18
+     * @see {@link MatterSpecification.v141.Core} § 9.17
      */
     export interface Cluster extends Identity<typeof ClusterInstance> {}
 

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

@@ -77,7 +77,10 @@ export namespace ElectricalEnergyMeasurement {
      * Such a server may also include the systime fields to indicate how many seconds had passed since boot for a given
      * timestamp; this allows for client-side resolution of UTC time for previous reports that only included systime.
      *
-     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1
+     * Elements using this data type shall indicate whether it represents cumulative or periodic energy, e.g. in the
+     * name or in the element description.
+     *
+     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2
      */
     export const TlvEnergyMeasurement = TlvObject({
         /**
@@ -90,7 +93,7 @@ export namespace ElectricalEnergyMeasurement {
          * during the period specified by either the StartTimestamp and EndTimestamp fields, the period specified by the
          * StartSystime and EndSystime fields, or both.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1.1
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.1
          */
         energy: TlvField(0, TlvInt64.bound({ min: 0 })),
 
@@ -106,7 +109,7 @@ export namespace ElectricalEnergyMeasurement {
          * Otherwise, if the server had not yet determined the time in UTC at or before the beginning of the measurement
          * period, or does not have the capability of determining the time in UTC, this field shall be omitted.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1.2
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.2
          */
         startTimestamp: TlvOptionalField(1, TlvEpochS),
 
@@ -120,7 +123,7 @@ export namespace ElectricalEnergyMeasurement {
          * Otherwise, 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 omitted.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1.3
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.3
          */
         endTimestamp: TlvOptionalField(2, TlvEpochS),
 
@@ -137,7 +140,7 @@ export namespace ElectricalEnergyMeasurement {
          * 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.v141.Cluster} § 2.12.5.1.4
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.4
          */
         startSystime: TlvOptionalField(3, TlvSysTimeMS),
 
@@ -152,7 +155,7 @@ export namespace ElectricalEnergyMeasurement {
          * 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.v141.Cluster} § 2.12.5.1.5
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.5
          */
         endSystime: TlvOptionalField(4, TlvSysTimeMS)
     });
@@ -167,7 +170,10 @@ export namespace ElectricalEnergyMeasurement {
      * Such a server may also include the systime fields to indicate how many seconds had passed since boot for a given
      * timestamp; this allows for client-side resolution of UTC time for previous reports that only included systime.
      *
-     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1
+     * Elements using this data type shall indicate whether it represents cumulative or periodic energy, e.g. in the
+     * name or in the element description.
+     *
+     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2
      */
     export interface EnergyMeasurement extends TypeFromSchema<typeof TlvEnergyMeasurement> {}
 
@@ -175,7 +181,7 @@ export namespace ElectricalEnergyMeasurement {
      * This struct shall represent the times at which cumulative measurements were last zero, either due to
      * initialization of the device, or an internal reset of the cumulative value.
      *
-     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2
+     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3
      */
     export const TlvCumulativeEnergyReset = TlvObject({
         /**
@@ -192,7 +198,7 @@ export namespace ElectricalEnergyMeasurement {
          * If the timestamp in UTC when the value of the Energy field on the CumulativeEnergyImported attribute was most
          * recently zero cannot currently be determined, a value of null shall be returned.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.1
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3.1
          */
         importedResetTimestamp: TlvOptionalField(0, TlvNullable(TlvEpochS)),
 
@@ -210,7 +216,7 @@ export namespace ElectricalEnergyMeasurement {
          * If the timestamp in UTC when the value of the Energy field on the CumulativeEnergyExported attribute was most
          * recently zero cannot currently be determined, a value of null shall be returned.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.2
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3.2
          */
         exportedResetTimestamp: TlvOptionalField(1, TlvNullable(TlvEpochS)),
 
@@ -226,7 +232,7 @@ export namespace ElectricalEnergyMeasurement {
          * CumulativeEnergyImported attribute was most recently zero, this field may be omitted; if it is indicated, its
          * value shall be the time elapsed since boot at the UTC time indicated in ImportedResetTimestamp.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.3
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3.3
          */
         importedResetSystime: TlvOptionalField(2, TlvNullable(TlvSysTimeMS)),
 
@@ -242,7 +248,7 @@ export namespace ElectricalEnergyMeasurement {
          * CumulativeEnergyExported attribute was most recently zero, this field may be omitted; if it is indicated, its
          * value shall be the time elapsed since boot at the UTC time indicated in ImportedResetTimestamp.
          *
-         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2.4
+         * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3.4
          */
         exportedResetSystime: TlvOptionalField(3, TlvNullable(TlvSysTimeMS))
     });
@@ -251,7 +257,7 @@ export namespace ElectricalEnergyMeasurement {
      * This struct shall represent the times at which cumulative measurements were last zero, either due to
      * initialization of the device, or an internal reset of the cumulative value.
      *
-     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.2
+     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.3
      */
     export interface CumulativeEnergyReset extends TypeFromSchema<typeof TlvCumulativeEnergyReset> {}
 
@@ -315,6 +321,93 @@ export namespace ElectricalEnergyMeasurement {
      */
     export interface PeriodicEnergyMeasuredEvent extends TypeFromSchema<typeof TlvPeriodicEnergyMeasuredEvent> {}
 
+    /**
+     * @see {@link MatterSpecification.v141.Cluster} § 2.12.5.1
+     */
+    export enum MeasurementType {
+        Unspecified = 0,
+
+        /**
+         * Voltage in millivolts (mV)
+         */
+        Voltage = 1,
+
+        /**
+         * Active current in milliamps (mA)
+         */
+        ActiveCurrent = 2,
+
+        /**
+         * Reactive current in milliamps (mA)
+         */
+        ReactiveCurrent = 3,
+
+        /**
+         * Apparent current in milliamps (mA)
+         */
+        ApparentCurrent = 4,
+
+        /**
+         * Active power in milliwatts (mW)
+         */
+        ActivePower = 5,
+
+        /**
+         * Reactive power in millivolt-amps reactive (mVAR)
+         */
+        ReactivePower = 6,
+
+        /**
+         * Apparent power in millivolt-amps (mVA)
+         */
+        ApparentPower = 7,
+
+        /**
+         * Root mean squared voltage in millivolts (mV)
+         */
+        RmsVoltage = 8,
+
+        /**
+         * Root mean squared current in milliamps (mA)
+         */
+        RmsCurrent = 9,
+
+        /**
+         * Root mean squared power in milliwatts (mW)
+         */
+        RmsPower = 10,
+
+        /**
+         * AC frequency in millihertz (mHz)
+         */
+        Frequency = 11,
+
+        /**
+         * Power Factor ratio in+/- 1/100ths of a percent.
+         */
+        PowerFactor = 12,
+
+        /**
+         * AC neutral current in milliamps (mA)
+         */
+        NeutralCurrent = 13,
+
+        /**
+         * Electrical energy in milliwatt-hours (mWh)
+         */
+        ElectricalEnergy = 14,
+
+        /**
+         * Reactive power in millivolt-amp-hours reactive (mVARh)
+         */
+        ReactiveEnergy = 15,
+
+        /**
+         * Apparent power in millivolt-amp-hours (mVAh)
+         */
+        ApparentEnergy = 16
+    }
+
     /**
      * A ElectricalEnergyMeasurementCluster supports these elements if it supports features ImportedEnergy and
      * CumulativeEnergy.
@@ -338,7 +431,7 @@ export namespace ElectricalEnergyMeasurement {
              *
              * @see {@link MatterSpecification.v141.Cluster} § 2.12.6.2
              */
-            cumulativeEnergyImported: Attribute(0x1, TlvNullable(TlvEnergyMeasurement), { default: null })
+            cumulativeEnergyImported: Attribute(0x1, TlvNullable(TlvEnergyMeasurement))
         }
     });
 
@@ -365,7 +458,7 @@ export namespace ElectricalEnergyMeasurement {
              *
              * @see {@link MatterSpecification.v141.Cluster} § 2.12.6.3
              */
-            cumulativeEnergyExported: Attribute(0x2, TlvNullable(TlvEnergyMeasurement), { default: null })
+            cumulativeEnergyExported: Attribute(0x2, TlvNullable(TlvEnergyMeasurement))
         }
     });
 
@@ -392,7 +485,7 @@ export namespace ElectricalEnergyMeasurement {
              *
              * @see {@link MatterSpecification.v141.Cluster} § 2.12.6.4
              */
-            periodicEnergyImported: Attribute(0x3, TlvNullable(TlvEnergyMeasurement), { default: null })
+            periodicEnergyImported: Attribute(0x3, TlvNullable(TlvEnergyMeasurement))
         }
     });
 
@@ -419,7 +512,7 @@ export namespace ElectricalEnergyMeasurement {
              *
              * @see {@link MatterSpecification.v141.Cluster} § 2.12.6.5
              */
-            periodicEnergyExported: Attribute(0x4, TlvNullable(TlvEnergyMeasurement), { default: null })
+            periodicEnergyExported: Attribute(0x4, TlvNullable(TlvEnergyMeasurement))
         }
     });