Skip to content

[DataModel] Initial proximity ranging cluster definition #43525

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
s-mcclain wants to merge 2 commits into
base: master
Choose a base branch
from
+12,194 −0
Open

[DataModel] Initial proximity ranging cluster definition #43525

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0bf8300
Initial Proximity Ranging cluster definition generated by Alchemy
s-mcclain Mar 9, 2026
68e4369
Update ZAP generated files with new proximity ranging cluster based o…
s-mcclain Mar 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/workflows/tests.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,6 +134,7 @@ jobs:
src/app/zap-templates/zcl/data-model/chip/groupcast-cluster.xml \
src/app/zap-templates/zcl/data-model/chip/icd-management-cluster.xml \
src/app/zap-templates/zcl/data-model/chip/meter-identification-cluster.xml \
src/app/zap-templates/zcl/data-model/chip/proximity-ranging-cluster.xml \
src/app/zap-templates/zcl/data-model/chip/push-av-stream-transport-cluster.xml \
src/app/zap-templates/zcl/data-model/chip/semantic-tag-namespace-enums.xml \
src/app/zap-templates/zcl/data-model/chip/access-control-definitions.xml \
Expand Down
1 change: 1 addition & 0 deletions docs/ids_and_codes/zap_clusters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,7 @@ Generally regenerate using one of:
| 1071 | 0x42F | RadonConcentrationMeasurement |
| 1072 | 0x430 | SoilMeasurement |
| 1073 | 0x431 | AmbientContextSensing |
| 1075 | 0x433 | ProximityRanging |
| 1105 | 0x451 | WiFiNetworkManagement |
| 1106 | 0x452 | ThreadBorderRouterManagement |
| 1107 | 0x453 | ThreadNetworkDirectory |
Expand Down
2 changes: 2 additions & 0 deletions scripts/tools/zap/tests/outputs/all-clusters-app/app-templates/gen_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@
#define MATTER_DM_RADON_CONCENTRATION_MEASUREMENT_CLUSTER_SERVER_ENDPOINT_COUNT (1)
#define MATTER_DM_SOIL_MEASUREMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_AMBIENT_CONTEXT_SENSING_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_PROXIMITY_RANGING_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_WIFI_NETWORK_MANAGEMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_BORDER_ROUTER_MANAGEMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_NETWORK_DIRECTORY_CLUSTER_SERVER_ENDPOINT_COUNT (0)
Expand Down Expand Up @@ -272,6 +273,7 @@
#define MATTER_DM_RADON_CONCENTRATION_MEASUREMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_SOIL_MEASUREMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_AMBIENT_CONTEXT_SENSING_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_PROXIMITY_RANGING_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_WIFI_NETWORK_MANAGEMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_BORDER_ROUTER_MANAGEMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_NETWORK_DIRECTORY_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
Expand Down
2 changes: 2 additions & 0 deletions scripts/tools/zap/tests/outputs/lighting-app/app-templates/gen_config.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,7 @@
#define MATTER_DM_RADON_CONCENTRATION_MEASUREMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_SOIL_MEASUREMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_AMBIENT_CONTEXT_SENSING_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_PROXIMITY_RANGING_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_WIFI_NETWORK_MANAGEMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_BORDER_ROUTER_MANAGEMENT_CLUSTER_SERVER_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_NETWORK_DIRECTORY_CLUSTER_SERVER_ENDPOINT_COUNT (0)
Expand Down Expand Up @@ -272,6 +273,7 @@
#define MATTER_DM_RADON_CONCENTRATION_MEASUREMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_SOIL_MEASUREMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_AMBIENT_CONTEXT_SENSING_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_PROXIMITY_RANGING_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_WIFI_NETWORK_MANAGEMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_BORDER_ROUTER_MANAGEMENT_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
#define MATTER_DM_THREAD_NETWORK_DIRECTORY_CLUSTER_CLIENT_ENDPOINT_COUNT (0)
Expand Down
215 changes: 215 additions & 0 deletions src/app/zap-templates/zcl/data-model/chip/proximity-ranging-cluster.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,215 @@
<?xml version="1.0"?>
<!--
Copyright (c) 2026 Project CHIP Authors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!--
XML generated by Alchemy; DO NOT EDIT.
Source: src/app_clusters/ProximityRanging.adoc
Parameters: zap /Users/seanmccs/git/connectedhomeip-spec/src/app_clusters/ProximityRanging.adoc verbose spec-root=/Users/seanmccs/git/connectedhomeip-spec attribute=in-progress sdk-root=/Users/seanmccs/git/connectedhomeip_fork
Git: 0.9-summer2026-108-ge59a2fe81-dirty
Alchemy: v1.6.10
-->
<configurator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../zcl.xsd">
<domain name=""/>
<bitmap name="RadioBandBitmap" type="bitmap16">
<cluster code="0x0433"/>
<field name="2G4" mask="0x0001"/>
<field name="3G65" mask="0x0002"/>
<field name="5G" mask="0x0004"/>
<field name="6G" mask="0x0008"/>
<field name="60G" mask="0x0010"/>
<field name="1G" mask="0x0020"/>
<field name="45G" mask="0x0040"/>
</bitmap>

<bitmap name="RangingBandwidthBitmap" type="bitmap32">
<cluster code="0x0433"/>
<field name="1MHz" mask="0x00000001"/>
<field name="2MHz" mask="0x00000002"/>
<field name="4MHz" mask="0x00000004"/>
<field name="8MHz" mask="0x00000008"/>
<field name="16MHz" mask="0x00000010"/>
<field name="20MHz" mask="0x00000020"/>
<field name="40MHz" mask="0x00000040"/>
<field name="80MHz" mask="0x00000080"/>
<field name="160MHz" mask="0x00000100"/>
<field name="320MHz" mask="0x00000200"/>
</bitmap>

<enum name="RangingRoleEnum" type="enum8">
<cluster code="0x0433"/>
<item name="WiFiSubscriberRole" value="0x00"/>
<item name="WiFiPublisherRole" value="0x01"/>
<item name="BLEScanningRole" value="0x02"/>
<item name="BLEBeaconRole" value="0x03"/>
<item name="BLTInitiatorRole" value="0x04"/>
<item name="BLTReflectorRole" value="0x05"/>
</enum>

<enum name="RangingSecurityEnum" type="enum8">
<cluster code="0x0433"/>
<item name="SecureRanging" value="0x00"/>
<item name="OpenRanging" value="0x01"/>
</enum>

<enum name="RangingTechEnum" type="enum8">
<cluster code="0x0433"/>
<item name="BluetoothChannelSounding" value="0x00"/>
<item name="WiFiRoundTripTimeRanging" value="0x01"/>
<item name="WiFiNextGenerationRanging" value="0x02"/>
<item name="BLEBeaconRSSIRanging" value="0x03"/>
</enum>

<enum name="ResultCodeEnum" type="enum8">
<cluster code="0x0433"/>
<item name="Accepted" value="0x00"/>
<item name="RejectedInfeasibleRanging" value="0x01"/>
<item name="RejectedInfeasibleRangingTriggers" value="0x02"/>
<item name="BusySessionCapacityReached" value="0x03"/>
<item name="BusyTryAgainLater" value="0x04"/>
</enum>

<struct name="BLERangingDeviceRoleConfigStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="Role" type="RangingRoleEnum" max="0x05" apiMaturity="provisional"/>
<item fieldId="1" name="PeerBLEDeviceID" type="int64u" apiMaturity="provisional"/>
</struct>

<struct name="BLTChannelSoundingDeviceRoleConfigStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="Role" type="RangingRoleEnum" max="0x05" apiMaturity="provisional"/>
<item fieldId="1" name="PeerBLTDevIK" type="octet_string" length="16" minLength="16" apiMaturity="provisional"/>
<item fieldId="2" name="LTK" type="octet_string" optional="true" length="16" minLength="16" apiMaturity="provisional"/>
</struct>

<struct name="RDRStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="Azimuth" type="int16u" max="2047" apiMaturity="provisional"/>
<item fieldId="1" name="Elevation" type="int16s" min="-512" max="511" apiMaturity="provisional"/>
<item fieldId="2" name="AzimuthAccuracy" type="int8u" max="127" apiMaturity="provisional"/>
<item fieldId="3" name="ElevationAccuracy" type="int8u" max="127" apiMaturity="provisional"/>
<item fieldId="4" name="Reference" type="int8u" max="1" apiMaturity="provisional"/>
</struct>

<struct name="RangingCapabilitiesStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="Technology" type="RangingTechEnum" max="0x03" apiMaturity="provisional"/>
<item fieldId="1" name="FrequencyBand" type="RadioBandBitmap" max="0x007F" apiMaturity="provisional"/>
<item fieldId="2" name="PeriodicRangingSupport" type="boolean" apiMaturity="provisional"/>
</struct>

<struct name="RangingMeasurementDataStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="WiFiDevIK" type="octet_string" optional="true" length="16" minLength="16" apiMaturity="provisional"/>
<item fieldId="1" name="BLEDeviceId" type="int64u" optional="true" apiMaturity="provisional"/>
<item fieldId="2" name="BLTDevIK" type="octet_string" optional="true" apiMaturity="provisional"/>
<item fieldId="3" name="TimeOfMeasurement" type="epoch_s" optional="true" apiMaturity="provisional"/>
<item fieldId="4" name="Distance" type="int16u" isNullable="true" apiMaturity="provisional"/>
<item fieldId="5" name="Accuracy" type="int16s" optional="true" apiMaturity="provisional"/>
<item fieldId="6" name="RDR" type="RDRStruct" optional="true" apiMaturity="provisional"/>
<item fieldId="7" name="RSSI" type="int8s" isNullable="true" optional="true" min="-127" max="27" apiMaturity="provisional"/>
<item fieldId="8" name="TxPower" type="int8s" isNullable="true" optional="true" min="-20" max="27" apiMaturity="provisional"/>
</struct>

<struct name="RangingTriggerConditionStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="StartTime" type="elapsed_s" apiMaturity="provisional"/>
<item fieldId="1" name="EndTime" type="elapsed_s" optional="true" apiMaturity="provisional"/>
<item fieldId="2" name="RangingInstanceInterval" type="elapsed_s" optional="true" min="1" apiMaturity="provisional"/>
</struct>

<struct name="ReportingConditionStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="MinDistanceCondition" type="int16u" optional="true" min="1" apiMaturity="provisional"/>
<item fieldId="1" name="MaxDistanceCondition" type="int16u" optional="true" apiMaturity="provisional"/>
<item fieldId="2" name="AccuracyCondition" type="int16u" optional="true" apiMaturity="provisional"/>
</struct>

<struct name="WiFiRangingDeviceRoleConfigStruct" apiMaturity="provisional">
<cluster code="0x0433"/>
<item fieldId="0" name="Role" type="RangingRoleEnum" max="0x05" apiMaturity="provisional"/>
<item fieldId="1" name="PeerWiFiDevIK" type="octet_string" length="16" minLength="16" apiMaturity="provisional"/>
<item fieldId="2" name="PMK" type="octet_string" optional="true" length="32" minLength="32" apiMaturity="provisional"/>
</struct>

<cluster apiMaturity="provisional">
<domain>Measurement &amp; Sensing</domain>
<name>Proximity Ranging</name>
<code>0x0433</code>
<define>PROXIMITY_RANGING_CLUSTER</define>
<description>This cluster enables the configuration of proximity ranging sessions and reporting of proximity ranging data.</description>
<client init="false" tick="false">true</client>
<server init="false" tick="false">true</server>
<globalAttribute code="0xFFFD" side="either" value="1"/>
<features>
<feature bit="0" code="WFUSDPD" name="Wi-Fi USD Proximity Detection" summary="Supports proximity ranging based on Wi-Fi">
<optionalConform choice="a" more="true" min="1"/>
</feature>
<feature bit="1" code="BLTCS" name="Bluetooth Channel Sounding" summary="Supports proximity ranging based on Bluetooth Channel Sounding">
<optionalConform choice="a" more="true" min="1"/>
</feature>
<feature bit="2" code="BLERBC" name="BLE Beacon RSSI" summary="Supports proximity ranging based on BLE Beacon RSSI">
<optionalConform choice="a" more="true" min="1"/>
</feature>
<feature bit="3" code="UWBRNG" name="UWB Ranging" summary="Supports proximity ranging based on UWB ranging">
<otherwiseConform>
<provisionalConform/>
<optionalConform choice="a" more="true" min="1"/>
</otherwiseConform>
</feature>
</features>
<attribute code="0x0000" side="server" name="RangingCapabilities" define="RANGING_CAPABILITIES" type="array" entryType="RangingCapabilitiesStruct" minLength="1"/>
<attribute code="0x0001" side="server" name="WiFiDevIK" define="WI_FI_DEV_IK" type="octet_string" length="16" minLength="16" optional="true">
<optionalConform choice="a" more="true" min="1"/>
</attribute>
<attribute code="0x0002" side="server" name="BLEDeviceId" define="BLEDEVICE_ID" type="int64u" optional="true">
<optionalConform choice="a" more="true" min="1"/>
</attribute>
<attribute code="0x0003" side="server" name="BLTDevIK" define="BLTDEV_IK" type="octet_string" length="16" minLength="16" optional="true">
<optionalConform choice="a" more="true" min="1"/>
</attribute>
<attribute code="0x0004" side="server" name="SessionIDs" define="SESSION_IDS" type="array" entryType="int8u" isNullable="true" length="255"/>
<command code="0x00" source="client" name="StartRangingRequest" response="StartRangingResponse">
<description>This command allows the client to request the start of a ranging session.</description>
<arg fieldId="0" name="Technology" type="RangingTechEnum" max="0x03"/>
<arg fieldId="1" name="WiFiRangingDeviceRoleConfig" type="WiFiRangingDeviceRoleConfigStruct" optional="true"/>
<arg fieldId="2" name="BLERangingDeviceRoleConfig" type="BLERangingDeviceRoleConfigStruct" optional="true"/>
<arg fieldId="3" name="BLTChannelSoundingDeviceRoleConfig" type="BLTChannelSoundingDeviceRoleConfigStruct" optional="true"/>
<arg fieldId="4" name="FrequencyBand" type="RadioBandBitmap" optional="true" max="0x007F"/>
<arg fieldId="5" name="Bandwidth" type="RangingBandwidthBitmap" optional="true" max="0x000003FF"/>
<arg fieldId="6" name="SecurityMode" type="RangingSecurityEnum" max="0x01"/>
<arg fieldId="7" name="Trigger" type="RangingTriggerConditionStruct"/>
<arg fieldId="8" name="ReportingCondition" type="ReportingConditionStruct" optional="true"/>
</command>

<command code="0x01" source="server" name="StartRangingResponse">
<description>Upon receipt of a StartRangingRequest command, the server SHALL send a StartRangingResponse command indicating whether the request has been accepted or rejected.</description>
<arg fieldId="0" name="ResultCode" type="ResultCodeEnum" max="0x04"/>
<arg fieldId="1" name="SessionID" type="int8u" isNullable="true"/>
</command>

<command code="0x02" source="client" name="StopRangingRequest">
<description>Upon receipt of a StopRangingRequest command that contains a SessionID that matches an active ranging session, the server SHALL terminate the corresponding ranging session.</description>
<arg fieldId="0" name="SessionID" type="int8u"/>
</command>

<command code="0x03" source="server" name="RangingResult">
<description>The RangingResult command is used by the initiator to report ranging measurement data.</description>
<arg fieldId="0" name="SessionID" type="int8u"/>
<arg fieldId="1" name="RangingResultData" type="RangingMeasurementDataStruct"/>
</command>

</cluster>
</configurator>
1 change: 1 addition & 0 deletions src/app/zap-templates/zcl/zcl-with-test-extensions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@
"mode-base-cluster.xml",
"mode-select-cluster.xml",
"mode-select-extensions.xml",
"proximity-ranging-cluster.xml",
"push-av-stream-transport-cluster.xml",
"semantic-tag-namespace-enums.xml",
"network-commissioning-cluster.xml",
Expand Down
1 change: 1 addition & 0 deletions src/app/zap-templates/zcl/zcl.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@
"messages-cluster.xml",
"mode-base-cluster.xml",
"mode-select-cluster.xml",
"proximity-ranging-cluster.xml",
"push-av-stream-transport-cluster.xml",
"semantic-tag-namespace-enums.xml",
"network-commissioning-cluster.xml",
Expand Down
2 changes: 2 additions & 0 deletions src/app/zap_cluster_list.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
"MESSAGES_CLUSTER": [],
"MODE_SELECT_CLUSTER": [],
"NETWORK_COMMISSIONING_CLUSTER": [],
"PROXIMITY_RANGING_CLUSTER": [],
"PUSH_AV_STREAM_TRANSPORT_CLUSTER": [],
"SAMPLE_MEI_CLUSTER": [],
"NITROGEN_DIOXIDE_CONCENTRATION_MEASUREMENT_CLUSTER": [],
Expand Down Expand Up @@ -266,6 +267,7 @@
"NITROGEN_DIOXIDE_CONCENTRATION_MEASUREMENT_CLUSTER": [
"concentration-measurement-server"
],
"PROXIMITY_RANGING_CLUSTER": [],
"PUSH_AV_STREAM_TRANSPORT_CLUSTER": ["push-av-stream-transport-server"],
"SAMPLE_MEI_CLUSTER": ["sample-mei-server"],
"OCCUPANCY_SENSING_CLUSTER": ["occupancy-sensor-server"],
Expand Down
Loading
Loading