"use strict";
var import_Resource = require("#models/Resource.js");
/**
 * @license
 * Copyright 2022-2026 Matter.js Authors
 * SPDX-License-Identifier: Apache-2.0
 */
import_Resource.Resource.add({
  tag: "cluster",
  name: "ServiceArea",
  pics: "SEAR",
  xref: "cluster\xA71.17",
  details: 'This cluster provides an interface for controlling the areas where a device should operate, for reporting the status at each area, and for querying the current area.\nThe device may operate at one area at a time, as in the case of a mobile device, such as a robot. Other devices may operate at (service) multiple areas simultaneously, as in the case of a sensor that can monitor multiple areas. This cluster specification uses the term "operate" to describe both the operating and servicing actions, regardless of the device type.\nThe cluster allows the client to select one or more areas on the server, to indicate where the device SHOULD attempt to operate. An area is one of a list of options that may be presented by a client for a user choice, or understood by the client, via the semantic data of the area.\nThe area semantic data is a combination of semantic tags, indicating one or more of the following: the building floor, area type, landmark, and relative position.',
  children: [
    {
      tag: "attribute",
      name: "FeatureMap",
      xref: "cluster\xA71.17.4",
      children: [
        {
          tag: "field",
          name: "SELRUN",
          xref: "cluster\xA71.17.4.1",
          details: "This feature indicates whether this device allows changing the selected areas, by using the SelectAreas command, while operating."
        },
        { tag: "field", name: "PROG", details: "The device implements the progress reporting feature" },
        { tag: "field", name: "MAPS", details: "The device has map support" }
      ]
    },
    {
      tag: "attribute",
      name: "SupportedAreas",
      xref: "cluster\xA71.17.6.1",
      details: `This attribute shall contain the list of areas that can be included in the SelectedAreas attribute's list. Each item in this list represents a unique area, as indicated by the AreaID field of AreaStruct.
Each entry in this list shall have a unique value for the AreaID field.
If the SupportedMaps attribute is not empty, each entry in this list shall have a unique value for the combination of the MapID and AreaInfo fields.
If the SupportedMaps attribute is empty, each entry in this list shall have a unique value for the AreaInfo field and shall have the MapID field set to null.
An empty value indicates that the device is currently unable to provide the list of supported areas.
> [!NOTE]
> NOTE: due to the maximum size of this list and to the fact that the entries may include strings (see LocationName), care must be taken by implementers to avoid creating a data structure that is overly large, which can result in significant latency in accessing this attribute.
The value of this attribute may change at any time via an out-of-band interaction outside of the server, such as interactions with a user interface, or due to internal device changes.
When removing entries in the SupportedAreas attribute list the server shall adjust the values of the SelectedAreas, CurrentArea, and Progress attributes such that they only reference valid entries in the updated SupportedAreas attribute list. These changes to the SelectedAreas, CurrentArea, and Progress attributes may result in the server setting some or all of them to empty (for SelectedAreas and Progress) or null (for CurrentArea), or updating them with data that matches the constraints from the description of the respective attributes. These actions are required to ensure having a consistent representation of the maps and locations available to the clients.
The SupportedAreas attribute list changes mentioned above SHOULD NOT be allowed while the device is operating, to reduce the impact on the clients, and the potential confusion for the users.
A few examples are provided below.
Valid list of areas:
  - AreaID=0, LocationName="yellow bedroom", MapID=null
  - AreaID=1, LocationName="orange bedroom", MapID=null
Valid list of areas:
  - AreaID=5, LocationName="hallway", MapID=1
  - AreaID=3, LocationName="hallway", MapID=2`
    },
    {
      tag: "attribute",
      name: "SupportedMaps",
      xref: "cluster\xA71.17.6.2",
      details: 'This attribute shall contain the list of supported maps.\nA map is a full or a partial representation of a home, known to the device. For example:\n  - a single level home may be represented using a single map\n  - a two level home may be represented using two maps, one for each level\n  - a single level home may be represented using two maps, each including a different set of rooms, such as "map of living room and kitchen" and "map of bedrooms and hallway"\n  - a single level home may be represented using one map for the indoor areas (living room, bedrooms etc.) and one for the outdoor areas (garden, swimming pool etc.)\nEach map includes one or more areas - see the SupportedAreas attribute. In the context of this cluster specification, a map is effectively a group label for a set of areas, rather than a graphical representation that the clients can display to the users. The clients that present the list of available areas for user selection (see the SelectAreas command) may choose to filter the SupportedAreas list based on the associated map. For example, the clients may allow the user to indicate that the device is to operate on the first floor, and allow the user to choose only from the areas situated on that level.\nIf empty, that indicates that the device is currently unable to provide this information.\nEach entry in this list shall have a unique value for the MapID field.\nEach entry in this list shall have a unique value for the Name field.\n> [!NOTE]\n> NOTE: due to the maximum size of this list and to the fact that the entries may include strings (see the Name field of the MapStruct data type), care must be taken by implementers to avoid creating a data structure that is overly large, which can result in significant latency in accessing this attribute.\nThe value of this attribute may change at any time via an out-of-band interaction outside of the server, such as interactions with a user interface.\nWhen updating the SupportedMaps attribute list by deleting entries, or by setting the attribute to an empty list, the SupportedAreas attribute shall be updated such that all entries in that list meet the constraints indicated in the description of the SupportedAreas attribute. This may result in the server removing entries from the SupportedAreas attribute list. See the SupportedAreas attribute description for the implications of changing that attribute.\nThe SupportedMaps attribute list changes mentioned above SHOULD NOT be allowed while the device is operating, to reduce the impact on the clients, and the potential confusion for the users.'
    },
    {
      tag: "attribute",
      name: "SelectedAreas",
      xref: "cluster\xA71.17.6.3",
      details: "Indicates the set of areas where the device SHOULD attempt to operate.\nThe mobile devices may travel without operating across any areas while attempting to reach the areas indicated by the SelectedAreas attribute. For example, a robotic vacuum cleaner may drive without cleaning when traveling without operating.\nIf this attribute is empty, the device is not constrained to operate in any specific areas.\nIf this attribute is not empty:\n  - each item in this list shall match the AreaID field of an entry in the SupportedAreas attribute's list\n  - each entry in this list shall have a unique value"
    },
    {
      tag: "attribute",
      name: "CurrentArea",
      xref: "cluster\xA71.17.6.4",
      details: "If the device is mobile, this attribute shall indicate the area where the device is currently located, regardless of whether it is operating or not, such as while traveling between areas.\nIf the device is not mobile and can operate at multiple areas sequentially, this attribute shall indicate the area which is currently being serviced, or the area which is currently traversed by the device. For example, a camera device may use this attribute to indicate which area it currently takes video of (serviced area) or which area it currently has in view but not taking video of (e.g. an area which is traversed while panning).\n> [!NOTE]\n> NOTE: A device may traverse an area regardless of the status of the area (pending, skipped, or completed).\nIf a device can simultaneously operate at multiple areas, such as in the case of a sensor that can monitor multiple areas at the same time, the CurrentArea attribute shall NOT be implemented, since it doesn't apply. Else this attribute shall be optionally implemented.\nA null value indicates that the device is currently unable to provide this information. For example, the device is traversing an unknown area, or the SupportedAreas attribute was updated and the area where the device is located was removed from that list.\nIf not null, the value of this attribute shall match the AreaID field of an entry on the SupportedAreas attribute's list."
    },
    {
      tag: "attribute",
      name: "EstimatedEndTime",
      xref: "cluster\xA71.17.6.5",
      details: "Indicates the estimated Epoch time for completing operating at the area indicated by the CurrentArea attribute, in seconds.\nA value of 0 means that the operation has completed.\nWhen this attribute is null, that represents that there is no time currently defined until operation completion. This may happen, for example, because no operation is in progress or because the completion time is unknown.\nNull if the CurrentArea attribute is null.\nIf the Progress attribute is available, and it contains an entry matching CurrentArea, the server may use the time estimate provided in the EstimatedTime field of that entry to compute the EstimatedEndTime attribute.\nThe value of this attribute shall only be reported in the following cases:\n  - when it changes to or from 0\n  - when it decreases\n  - when it changes to or from null\n    > [!NOTE]\n    > NOTE: If the device is capable of pausing its operation, this attribute may be set to null, to indicate that completion time is unknown, or increment the value while being in the paused state."
    },
    {
      tag: "attribute",
      name: "Progress",
      xref: "cluster\xA71.17.6.6",
      details: "Indicates the operating status at one or more areas.\nEach entry in this list shall have a unique value for the AreaID field.\nFor each entry in this list, the AreaID field shall match an entry on the SupportedAreas attribute's list.\nWhen this attribute is empty, that represents that no progress information is currently available.\nIf the SelectedAreas attribute is empty, indicating the device is not constrained to operate in any specific areas, the Progress attribute list may change while the device operates, due to the device adding new entries dynamically, when it determines which ones it can attempt to operate at.\nIf the SelectedAreas attribute is not empty, and the device starts operating:\n  - the Progress attribute list shall be updated so each entry of SelectedAreas has a matching Progress list entry, based on the AreaID field\n  - the length of the Progress and SelectedAreas list shall be the same\n  - the entries in the Progress list shall be initialized by the server, by having their status set to Pending or Operating, and the TotalOperationalTime field set to null\nWhen the device ends operation unexpectedly, such as due to an error, the server shall update all Progress list entries with the Status field set to Operating or Pending to Skipped.\nWhen the device finishes operating, successfully or not, it shall NOT change the Progress attribute, except in the case of an unexpected end of operation as described above, or due to changes to the SupportedMaps or SupportedAreas attributes, so the clients can retrieve the progress information at that time.\n> [!NOTE]\n> NOTE: if the device implements the Operational Status cluster, or a derivation of it, in case the device fails to service any locations in the SelectedAreas list before ending the operation, it SHOULD use the Operational Status cluster to indicate that the device was unable to complete the operation (see the UnableToCompleteOperation error from that cluster specification). The clients SHOULD then read the Progress attribute, and indicate which areas have been successfully serviced (marked as completed)."
    },
    {
      tag: "command",
      name: "SelectAreas",
      xref: "cluster\xA71.17.7.1",
      details: "This command is used to select a set of device areas, where the device is to operate.\nOn receipt of this command the device shall respond with a SelectAreasResponse command.",
      children: [{
        tag: "field",
        name: "NewAreas",
        xref: "cluster\xA71.17.7.1.1",
        details: "This field indicates which areas the device is to operate at.\nIf this field is empty, that indicates that the device is to operate without being constrained to any specific areas, and the operation will not allow skipping using the SkipArea Command, otherwise the field shall be a list of unique values that match the AreaID field of entries on the SupportedAreas list."
      }]
    },
    {
      tag: "command",
      name: "SelectAreasResponse",
      xref: "cluster\xA71.17.7.2",
      details: "This command is sent by the device on receipt of the SelectAreas command.",
      children: [{
        tag: "field",
        name: "Status",
        xref: "cluster\xA71.17.7.2.1",
        details: "If the Status field is set to Success or UnsupportedArea, the server may use a non-empty string for the StatusText field to provide additional information. For example, if Status is set to UnsupportedArea, the server may use StatusText to indicate which areas are unsupported.\nIf the Status field is not set to Success, or UnsupportedArea, the StatusText field shall include a vendor-defined error description which can be used to explain the error to the user. For example, if the Status field is set to InvalidInMode, the StatusText field SHOULD indicate why the request is not allowed, given the current mode of the device, which may involve other clusters."
      }]
    },
    {
      tag: "command",
      name: "SkipArea",
      xref: "cluster\xA71.17.7.3",
      details: "This command is used to skip the given area, and to attempt operating at other areas on the SupportedAreas attribute list.\nOn receipt of this command the device shall respond with a SkipAreaResponse command.",
      children: [{
        tag: "field",
        name: "SkippedArea",
        xref: "cluster\xA71.17.7.3.1",
        details: "The SkippedArea field indicates the area to be skipped.\nThe SkippedArea field shall match an entry in the SupportedAreas list."
      }]
    },
    {
      tag: "command",
      name: "SkipAreaResponse",
      xref: "cluster\xA71.17.7.4",
      details: "This command is sent by the device on receipt of the SkipArea command.",
      children: [{
        tag: "field",
        name: "Status",
        xref: "cluster\xA71.17.7.4.1",
        details: "If the Status field is set to Success or InvalidAreaList, the server may use a non-empty string for the StatusText field to provide additional information. For example, if Status is set to InvalidAreaList, the server may use StatusText to indicate why this list is invalid.\nIf the Status field is not set to Success or InvalidAreaList, the StatusText field shall include a vendor defined error description which can be used to explain the error to the user. For example, if the Status field is set to InvalidInMode, the StatusText field SHOULD indicate why the request is not allowed, given the current mode of the device, which may involve other clusters."
      }]
    },
    {
      tag: "datatype",
      name: "LandmarkInfoStruct",
      xref: "cluster\xA71.17.5.1",
      details: "The data from this structure indicates a landmark and position relative to the landmark.",
      children: [
        {
          tag: "field",
          name: "LandmarkTag",
          xref: "cluster\xA71.17.5.1.1",
          details: "This field shall indicate that the area is associated with a landmark.\nThis field shall be the ID of a landmark semantic tag, located within the Common Landmark Namespace. For example, this tag may indicate that the area refers to an area next to a table."
        },
        {
          tag: "field",
          name: "RelativePositionTag",
          xref: "cluster\xA71.17.5.1.2",
          details: "This field shall identify the position of the area relative to a landmark. This is a static description of a zone known to the server, and this field never reflects the device's own proximity or position relative to the landmark, but that of the zone.\nThis field shall be the ID of a relative position semantic tag, located within the Common Relative Position Namespace.\nIf the RelativePositionTag field is null, this field indicates proximity to the landmark. Otherwise, the RelativePositionTag field indicates the position of the area relative to the landmark indicated by the LandmarkTag field. For example, this tag, in conjunction with the LandmarkTag field, may indicate that the area refers to a zone under a table."
        }
      ]
    },
    {
      tag: "datatype",
      name: "AreaInfoStruct",
      xref: "cluster\xA71.17.5.2",
      details: "The data from this structure indicates the name and/or semantic data describing an area, as detailed below.\nThis data type includes the LocationInfo field, with the following fields: LocationName, FloorNumber, AreaType. Additional semantic data may be available in the LandmarkInfo field.\nFor an area description to be meaningful, it shall have at least one of the following:\n  - a non-empty name (LocationInfo's LocationName field)\nOR\n  - some semantic data (one or more of these: FloorNumber, AreaType or LandmarkTag) The normative text from the remainder of this section describes these constraints.\nIf the LocationInfo field is null, the LandmarkInfo field shall NOT be null.\nIf the LandmarkInfo field is null, the LocationInfo field shall NOT be null.\nIf LocationInfo is not null, and its LocationName field is an empty string, at least one of the following shall NOT be null:\n  - LocationInfo's FloorNumber field\n  - LocationInfo's AreaType field\n  - LandmarkInfo field\nIf all three of the following are null, LocationInfo's LocationName field shall NOT be an empty string:\n  - LocationInfo's FloorNumber field\n  - LocationInfo's AreaType field\n  - LandmarkInfo field",
      children: [
        {
          tag: "field",
          name: "LocationInfo",
          xref: "cluster\xA71.17.5.2.1",
          details: `This field shall indicate the name of the area, floor number and/or area type.
A few examples are provided below.
  - An area can have LocationInfo's LocationName field set to "blue room", and the AreaType field set to the ID of a "Living Room" semantic tag. Clients wishing to direct the device to operate in (or service) the living room can use this area.
  - An area can have LocationInfo set to null, the LandmarkInfo's LandmarkTag field set to the ID of the "Table" landmark semantic tag, and the RelativePositionTag field set to the ID of the "Under" position semantic tag. With such an area indication, the client can request the device to operate in (or service) the area located under the table.`
        },
        {
          tag: "field",
          name: "LandmarkInfo",
          xref: "cluster\xA71.17.5.2.2",
          details: "This field shall indicate an association with a landmark. A value of null indicates that the information is not available or known. For example, this may indicate that the area refers to a zone next to a table.\nIf this field is not null, that indicates that the area is restricted to the zone where the landmark is located, as indicated by the LandmarkTag and, if not null, by the RelativePositionTag fields, rather than to the entire room or floor where the landmark is located, if those are indicated by the LocationInfo field."
        }
      ]
    },
    {
      tag: "datatype",
      name: "MapStruct",
      xref: "cluster\xA71.17.5.3",
      details: "This is a struct representing a map.",
      children: [
        {
          tag: "field",
          name: "MapId",
          xref: "cluster\xA71.17.5.3.1",
          details: "This field shall represent the map's identifier."
        },
        {
          tag: "field",
          name: "Name",
          xref: "cluster\xA71.17.5.3.2",
          details: 'This field shall represent a human understandable map description.\nFor example: "Main Floor", or "Second Level".'
        }
      ]
    },
    {
      tag: "datatype",
      name: "AreaStruct",
      xref: "cluster\xA71.17.5.4",
      details: "This is a struct representing an area known to the server.",
      children: [
        {
          tag: "field",
          name: "AreaId",
          xref: "cluster\xA71.17.5.4.1",
          details: "This field shall represent the identifier of the area."
        },
        {
          tag: "field",
          name: "MapId",
          xref: "cluster\xA71.17.5.4.2",
          details: "This field shall indicate the map identifier which the area is associated with. A value of null indicates that the area is not associated with a map.\nIf the SupportedMaps attribute is not empty, this field shall match the MapID field of an entry from the SupportedMaps attribute's list. If the SupportedMaps attribute is empty, this field shall be null."
        },
        {
          tag: "field",
          name: "AreaInfo",
          xref: "cluster\xA71.17.5.4.3",
          details: "This field shall contain data describing the area.\nThis SHOULD be used by clients to determine the name and/or the full, or the partial, semantics of a certain area.\n> [!NOTE]\n> NOTE: If any entries on the SupportedAreas attribute's list have the AreaInfo field missing the semantic data, the client may remind the user to assign the respective data."
        }
      ]
    },
    {
      tag: "datatype",
      name: "ProgressStruct",
      xref: "cluster\xA71.17.5.5",
      details: "This is a struct indicating the progress.",
      children: [
        {
          tag: "field",
          name: "AreaId",
          xref: "cluster\xA71.17.5.5.1",
          details: "This field shall indicate the identifier of the area, and the identifier shall be an entry in the SupportedAreas attribute's list."
        },
        {
          tag: "field",
          name: "Status",
          xref: "cluster\xA71.17.5.5.2",
          details: "This field shall indicate the operational status of the device regarding the area indicated by the AreaID field."
        },
        {
          tag: "field",
          name: "TotalOperationalTime",
          xref: "cluster\xA71.17.5.5.3",
          details: "This field shall indicate the total operational time, in seconds, from when the device started to operate at the area indicated by the AreaID field, until the operation finished, due to completion or due to skipping, including any time spent while paused.\nA value of null indicates that the total operational time is unknown.\nThere may be cases where the total operational time exceeds the maximum value that can be conveyed by this attribute, and in such instances this attribute shall be populated with null.\nNull if the Status field is not set to Completed or Skipped."
        },
        {
          tag: "field",
          name: "EstimatedTime",
          xref: "cluster\xA71.17.5.5.4",
          details: "This field shall indicate the estimated time for the operation, in seconds, from when the device will start operating at the area indicated by the AreaID field, until the operation completes, excluding any time spent while not operating in the area.\nA value of null indicates that the estimated time is unknown. If the estimated time is unknown, or if it exceeds the maximum value that can be conveyed by this attribute, this attribute shall be null.\nAfter initializing the ProgressStruct instance, the server SHOULD NOT change the value of this field, except when repopulating the entire instance, to avoid excessive reporting of the Progress attribute changes."
        }
      ]
    },
    {
      tag: "datatype",
      name: "OperationalStatusEnum",
      xref: "cluster\xA71.17.5.6",
      children: [
        {
          tag: "field",
          name: "Pending",
          description: "The device has not yet started operating at the given area, or has not finished operating at that area but it is not currently operating at the area"
        },
        { tag: "field", name: "Operating", description: "The device is currently operating at the given area" },
        {
          tag: "field",
          name: "Skipped",
          description: "The device has skipped the given area, before or during operating at it, due to a SkipArea command, due an out of band command (e.g. from the vendor's application), due to a vendor specific reason, such as a time limit used by the device, or due the device ending operating unsuccessfully"
        },
        {
          tag: "field",
          name: "Completed",
          description: "The device has completed operating at the given area"
        }
      ]
    },
    {
      tag: "datatype",
      name: "SelectAreasStatus",
      xref: "cluster\xA71.17.5.6.1",
      children: [
        {
          tag: "field",
          name: "Success",
          description: "Attempting to operate in the areas identified by the entries of the NewAreas field is allowed and possible. The SelectedAreas attribute is set to the value of the NewAreas field."
        },
        {
          tag: "field",
          name: "UnsupportedArea",
          description: "The value of at least one of the entries of the NewAreas field doesn't match any entries in the SupportedAreas attribute."
        },
        {
          tag: "field",
          name: "InvalidInMode",
          description: "The received request cannot be handled due to the current mode of the device."
        },
        {
          tag: "field",
          name: "InvalidSet",
          description: "The set of values is invalid. For example, areas on different floors, that a robot knows it can't reach on its own."
        }
      ]
    },
    {
      tag: "datatype",
      name: "SkipAreaStatus",
      xref: "cluster\xA71.17.5.6.2",
      children: [
        {
          tag: "field",
          name: "Success",
          description: "Skipping the area is allowed and possible, or the device was operating at the last available area and has stopped."
        },
        { tag: "field", name: "InvalidAreaList", description: "The SelectedAreas attribute is empty." },
        {
          tag: "field",
          name: "InvalidInMode",
          description: "The received request cannot be handled due to the current mode of the device. For example, the CurrentArea attribute is null or the device is not operating."
        },
        {
          tag: "field",
          name: "InvalidSkippedArea",
          description: "The SkippedArea field doesn't match an entry in the SupportedAreas list."
        }
      ]
    }
  ]
});
//# sourceMappingURL=service-area.resource.js.map
