Matter camera: use AttributeList and AcceptedCommandList to gate optional attributes, subscriptions and commands

[ldeora]

Summary

The matter-switch camera subdriver currently relies mainly on cluster presence and FeatureMap when deciding which camera attributes to subscribe to, which SmartThings capability features to advertise, and which Matter commands may be sent.

That is not sufficient for Matter camera clusters because many attributes and commands are optional even when the corresponding feature is present.

A real Matter 1.5.1 camera exposed this clearly:

• CameraAvStreamManagement has the Night Vision feature and the NightVision attribute, but does not advertise NightVisionIllum.
• CameraAvSettingsUserLevelManagement supports mechanical pan/tilt/zoom/presets but does not advertise Digital PTZ or DPTZStreams.
• nevertheless the current driver subscribes to NightVisionIllum whenever nightVision is enabled and includes DPTZStreams whenever videoStreamSettings is enabled.
• videoStreamSettings.supportedFeatures currently adds perStreamViewports from the AVSM VIDEO feature alone, although per-stream viewport control is a Digital PTZ function.

The driver already subscribes to AVSM AttributeList, but the current handler only uses it for status-light detection. It does not cache the full list. It does not currently subscribe to or use AcceptedCommandList.

Environment / verification

Verified against SmartThingsCommunity/SmartThingsEdgeDrivers main at commit
60bbf2716412fdf04fd59f967bdd37be6995d664 (2026-08-12).

Real-device validation used:

• Aqara Camera Hub G350
• VID/PID: 0x115F / 0x3013
• firmware: 4.5.70 / 4005070
• reported Matter SpecificationVersion: 1.5.1
• Camera device type: 0x0142
• Camera endpoint in this device: endpoint 2

The proposed changes are generic Matter-camera changes. No Aqara VID/PID fingerprint or proprietary Aqara cluster handling is required.

Current behavior

Current camera subscriptions include optional attributes unconditionally once the SmartThings capability is present:

• camera_utils/utils.lua lines 183-240
  • NightVision and NightVisionIllum
  • DPTZStreams under videoStreamSettings

The driver subscribes to AVSM AttributeList, but not AcceptedCommandList, and does not subscribe to AV Settings AttributeList / AcceptedCommandList:

• camera_utils/utils.lua lines 298-338

The AVSM AttributeList handler currently extracts only the two status-light attributes:

• camera_handlers/attribute_handlers.lua lines 450-476

perStreamViewports is currently advertised whenever AVSM has VIDEO:

• camera_utils/device_configuration.lua lines 87-100

The capability handlers also expose commands based on capability/feature presence rather than the endpoint's actual AcceptedCommandList.

Reproduction

1. Join a Matter camera that exposes:
   • AVSM VIDEO and NIGHT_VISION;
   • NightVision;
   • no NightVisionIllum;
   • mechanical PTZ;
   • no Digital PTZ;
   • no DPTZStreams.
2. Let the camera subdriver profile and subscribe.
3. Inspect the generated SmartThings state and Matter subscription paths.

On the G350, the Matter metadata is:

CameraAvStreamManagement FeatureMap = 0x041F
  Audio
  Video
  Snapshot
  Privacy
  Speaker
  NightVision

CameraAvSettingsUserLevelManagement FeatureMap = 0x001E
  MechanicalPan
  MechanicalTilt
  MechanicalZoom
  MechanicalPresets
  NO DigitalPTZ

AVSM AttributeList:
  NightVision      present
  NightVisionIllum absent

AV Settings AttributeList:
  DPTZStreams absent

Before the test-driver fix, SmartThings nevertheless reported:

"videoStreamSettings": {
  "supportedFeatures": {
    "value": [
      "liveStreaming",
      "clipRecording",
      "perStreamViewports"
    ]
  }
}

That is inconsistent with the endpoint's advertised feature/attribute model.

Expected behavior

Once the endpoint's global metadata is known:

• only attributes actually present in AttributeList should be subscribed/read/written;
• commands absent from AcceptedCommandList should not be sent;
• perStreamViewports should be exposed only when the camera actually implements Digital PTZ / the required DPTZ model;
• absence of optional metadata should not disable otherwise supported functionality before the global lists have been received.

Suggested change

Cache the complete global lists for the camera clusters, for example:

-- conceptual helpers
camera_utils.update_attribute_list(device, cluster_id, elements)
camera_utils.update_accepted_command_list(device, cluster_id, elements)

camera_utils.attribute_supported(device, cluster_id, attribute_id)
camera_utils.command_supported(device, cluster_id, command_id)

Recommended compatibility semantics:

list not received yet -> unknown -> preserve existing behavior
list received         -> authoritative -> filter/gate against it

Subscribe to:

CameraAvStreamManagement.attributes.AttributeList
CameraAvStreamManagement.attributes.AcceptedCommandList

CameraAvSettingsUserLevelManagement.attributes.AttributeList
CameraAvSettingsUserLevelManagement.attributes.AcceptedCommandList

Then:

1. filter the camera subscription map against the cached AttributeList when known;
2. add DPTZStreams only when the Digital PTZ feature exists and the attribute is advertised;
3. add perStreamViewports only when Digital PTZ is supported;
4. gate writes to optional camera attributes against AttributeList when known;
5. gate camera commands against AcceptedCommandList when known.

Do not make an unknown list equivalent to "unsupported"; metadata reporting can arrive after profile initialization.

G350 evidence

The G350's real endpoint proves that a standards-compliant camera may implement a non-maximal combination of Matter camera options:

NightVision feature: yes
NightVision attribute: yes
NightVisionIllum: no

Mechanical PTZ: yes
Mechanical presets: yes
Digital PTZ: no
DPTZStreams: no

The test driver using AttributeList/AcceptedCommandList filtering remained operational on the G350 and removed the incorrect perStreamViewports advertisement.

The G350 advertises these AV Settings accepted commands:

0x00 MPTZSetPosition
0x01 MPTZRelativeMove
0x02 MPTZMoveToPreset
0x03 MPTZSavePreset
0x04 MPTZRemovePreset

and does not advertise the Digital PTZ commands.

Affected files

At minimum:

• src/sub_drivers/camera/camera_utils/fields.lua
• src/sub_drivers/camera/camera_utils/utils.lua
• src/sub_drivers/camera/camera_utils/device_configuration.lua
• src/sub_drivers/camera/camera_handlers/attribute_handlers.lua
• src/sub_drivers/camera/camera_handlers/capability_handlers.lua
• src/sub_drivers/camera/init.lua
• src/test/test_matter_camera.lua

Suggested regression coverage

Add a second camera fixture whose feature set mirrors the G350 rather than the current all-features test camera:

AVSM: Audio | Video | Snapshot | Privacy | Speaker | NightVision
AV Settings: MechanicalPan | MechanicalTilt | MechanicalZoom | MechanicalPresets
No DigitalPTZ
No NightVisionIllum
No DPTZStreams

Verify:

• NightVision is subscribed;
• NightVisionIllum is not subscribed once AttributeList is known;
• DPTZStreams is not subscribed;
• perStreamViewports is not advertised;
• commands absent from AcceptedCommandList are ignored;
• behavior remains permissive before the global lists arrive.

Scope

This is not an Aqara-specific request. The G350 is simply a real Matter camera that exposed assumptions in the generic optional-feature handling.