Skip to content

video/Multi-dimensional-Sensor-Data #610

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
WANGXIAOMIN-HIK wants to merge 20 commits into
base: development
Choose a base branch
from
Open

video/Multi-dimensional-Sensor-Data #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
86f0fbe
This PR implements the ONVIF Multi-dimensional Sensor Data Standard P…
WANGXIAOMIN-HIK Jul 16, 2025
6b09748
Adjust the order and format of the SensorData content chapters.
WANGXIAOMIN-HIK Jul 24, 2025
dcd726a
Modify the capability definition of SensorData
WANGXIAOMIN-HIK Jul 24, 2025
f2b6f25
Adjust the chapter number of Sensor Data Examples
WANGXIAOMIN-HIK Jul 31, 2025
1847393
Move Sensor Data Support Attributes from GetServiceCapabilities to Ge…
WANGXIAOMIN-HIK Aug 15, 2025
62a295b
Remove the definitions of SensorDataOverMQTT and SensorDataFilter, wh…
WANGXIAOMIN-HIK Aug 16, 2025
3b9b64d
**Technical Implementation:**
WANGXIAOMIN-HIK Aug 21, 2025
e1f5f41
Remove the definition of the attribute that the sensor data supports
WANGXIAOMIN-HIK Sep 4, 2025
755e60e
1. Topic Naming Convention Adjustment
WANGXIAOMIN-HIK Sep 10, 2025
db27308
Update the unit descriptions for sensor data, adding detailed informa…
WANGXIAOMIN-HIK Sep 12, 2025
1908175
Changes:
WANGXIAOMIN-HIK Sep 12, 2025
a9d6d2f
Remove the 'Type' field definition from 'SensorData'.
WANGXIAOMIN-HIK Sep 12, 2025
c487046
Remove Unit, expand Type to include RelativeHumidity, AbsoluteHumidity
WANGXIAOMIN-HIK Oct 9, 2025
c1fbd7c
Correct the error in the RelativeHumidity example, changing 348.65 to…
WANGXIAOMIN-HIK Oct 14, 2025
f04e0a7
Add unit descriptions for temperature and humidity:
WANGXIAOMIN-HIK Oct 14, 2025
a8fe23f
Change the unit of Absolute Humidity to g/m³
WANGXIAOMIN-HIK Oct 28, 2025
1fbd9be
Refactor sensor data examples, remove unnecessary nested structures, …
WANGXIAOMIN-HIK Nov 13, 2025
c986373
Add SensorDataFilter
WANGXIAOMIN-HIK Nov 17, 2025
ab6361e
Add the configuration of sensormetadata filtering, SensorDataFilter
WANGXIAOMIN-HIK Nov 18, 2025
db00987
Adjust the node position of SensorData
WANGXIAOMIN-HIK Dec 5, 2025
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
148 changes: 148 additions & 0 deletions doc/Analytics.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -663,6 +663,8 @@
<para>This section focuses on scene elements generated by object tracking algorithms and defines object handling and object shapes for them.</para>
<para>Frames where no objects have been detected can be skipped within the scene description to save bandwidth, as long as the last frame in the scene description is empty as well. . It is recommended that the device regularly sends the scene description even if it is empty. This is in order to indicate that the analytics engine is operational. The device shall send a scene description if a SynchronizationPoint is requested for the corresponding stream.</para>
<para>When the receiver of a scene description receives an empty frame, the receiver should assume that all subsequent frames are empty as well until the next non-empty frame is received. When the last received frame is non-empty, the receiver should assume that a description of the next processed frame will be transmitted.</para>


<section xml:id="_Ref208712481">
<title>Objects</title>
<para>The object node has two placeholders for appearance and behaviour information. The appearance node starts with an optional transformation node which can be used to change from a frame-centric coordinate system to an object-centric coordinate system. Next, the Shape of an object can be specified. If an object is detected in a frame, the shape information should be present in the appearance description. The analytics algorithm may add object nodes for currently not visible objects, if it is able to infer information for this object otherwise. In such cases, the shape description may be omitted.</para>
Expand Down Expand Up @@ -2489,6 +2491,93 @@
</tt:VideoAnalytics>
]]></programlisting>
</section>

<section xml:id="sensordata">
<title>Sensor Data</title>
<para>This section defines the metadata representation for multi-dimensional sensor data, used for periodic sensor data reporting scenarios.</para>

<section>
<title>Sensor Data Description</title>
<para>Sensor data is represented through the SensorData element, which contains the following information:</para>
<itemizedlist>
<listitem>
<para>Type: Type of sensor (e.g., Temperature, RelativeHumidity, AbsoluteHumidity, etc.)</para>
</listitem>
<listitem>
<para>Value: Numerical value from the sensor. The unit of temperature is Kelvin, the unit of absolute humidity is g/m³, and the unit of relative humidity is %.</para>
</listitem>
</itemizedlist>

<para>The SensorData element is designed to be included in the MetadataStream structure,
allowing sensor data to be transmitted alongside other metadata types.</para>
</section>

<section>
<title>Temperature Sensor Metadata</title>
<para>Temperature sensor data is a common type of sensor information. The metadata for temperature sensors follows the general sensor data structure with specific conventions:</para>
<itemizedlist>
<listitem>
<para>Type: Should be set to "temperature"</para>
</listitem>
<listitem>
<para>Value: Floating point value representing the temperature in Kelvin</para>
</listitem>
</itemizedlist>

<programlisting><![CDATA[<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="temp_001">
<tt:Type>Temperature</tt:Type>
<tt:Value>298.65</tt:Value>
</tt:SensorData>]]></programlisting>
</section>

<section>
<title>Humidity Sensor Metadata</title>
<para>Humidity sensor data represents ambient humidity conditions. The metadata for humidity sensors follows the general sensor data structure with specific conventions:</para>
<itemizedlist>
<listitem>
<para>Type: Should be set to "RelativeHumidity" or "AbsoluteHumidity"</para>
</listitem>
<listitem>
<para>Value: Floating point value representing the humidity percentage, either relative or absolute, units are %RH or g/m³</para>
</listitem>
</itemizedlist>

<para>Absolute humidity is the actual mass of water vapor per unit volume of air (unit: g/m³), while relative humidity is the percentage ratio of the current water vapor content to the saturated content at the same temperature (unit: %).</para>

<programlisting><![CDATA[<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="humidity_001">
<tt:Type>AbsoluteHumidity</tt:Type>
<tt:Value>10</tt:Value>
</tt:SensorData>]]></programlisting>

<programlisting><![CDATA[<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="humidity_001">
<tt:Type>RelativeHumidity</tt:Type>
<tt:Value>65.2</tt:Value>
</tt:SensorData>]]></programlisting>

</section>

<section>
<title>Sensor Data Example</title>
<para>The following is an example of temperature and humidity sensor data in the MetadataStream:</para>



<programlisting><![CDATA[<tt:MetadataStream xmlns:tt="http://www.onvif.org/ver10/schema">
<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="temp_001">
<tt:Type>Temperature</tt:Type>
<tt:Value>298.65</tt:Value>
</tt:SensorData>
<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="humidity_001">
<tt:Type>RelativeHumidity</tt:Type>
<tt:Value>65.2</tt:Value>
</tt:SensorData>
<tt:SensorData UtcTime="2025-07-15T14:30:00Z" SensorID="humidity_001">
<tt:Type>AbsoluteHumidity</tt:Type>
<tt:Value>10</tt:Value>
</tt:SensorData>
</tt:MetadataStream>]]></programlisting>
</section>
</section>
</section>
<section xml:id="mqtt">
<title>JSON over MQTT</title>
Expand Down Expand Up @@ -2644,6 +2733,12 @@
<entry><para>ONVIF metadata from a PTZ node included in
Profile configuration</para></entry>
</row>

<row>
<entry><para>"SensorData"</para></entry>
<entry><para>Type</para></entry>
<entry><para>ONVIF metadata from sensor data sources</para></entry>
</row>
</tbody>
</tgroup>
</table>
Expand All @@ -2661,9 +2756,15 @@
<listitem>
<para>PTZConfigurationToken = The PTZ configuration token</para>
</listitem>

<listitem>
<para>Type = The type of sensor (e.g., "Temperature", "RelativeHumidity", "AbsoluteHumidity")</para>
</listitem>
</itemizedlist></para>
</section>



<section xml:id="example">
<title>Example</title>

Expand Down Expand Up @@ -2843,6 +2944,53 @@ xmlns:acme="http://www.acme.com/schema"&gt;
}]
}</programlisting>
</section>

<section xml:id="sensor_example">
<title>Sensor Data Examples</title>

<para>Temperature data will be published under this topic. For devices with multiple temperature sensors, each sensor will publish data with a unique SensorID in the payload:</para>

<programlisting>MyDevice/onvif-mj/SensorData/Temperature</programlisting>

<para>Shown below is how the sample temperature sensor data is formatted in JSON:</para>

<programlisting>{
"SensorData": {
"@UtcTime": "2025-07-15T14:30:00Z",
"@SensorID": "temp_001",
"Value": 298.65
}
}</programlisting>

<para>Relative Humidity data will be published under this topic. For devices with multiple humidity sensors, each sensor will publish data with a unique SensorID in the payload:</para>

<programlisting>MyDevice/onvif-mj/SensorData/RelativeHumidity</programlisting>

<para>Shown below is how the sample humidity sensor data is formatted in JSON:</para>

<programlisting>{
"SensorData": {
"@UtcTime": "2025-07-15T14:30:00Z",
"@SensorID": "humidity_001",
"Value": 65.2
}
}</programlisting>

<para>Absolute Humidity data will be published under this topic. For devices with multiple humidity sensors, each sensor will publish data with a unique SensorID in the payload:</para>

<programlisting>MyDevice/onvif-mj/SensorData/AbsoluteHumidity</programlisting>

<para>Shown below is how the sample humidity sensor data is formatted in JSON:</para>

<programlisting>{
"SensorData": {
"@UtcTime": "2025-07-15T14:30:00Z",
"@SensorID": "humidity_001",
"Value": 10
}
}</programlisting>

</section>
</section>
</chapter>
<chapter>
Expand Down
149 changes: 149 additions & 0 deletions doc/Core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6720,6 +6720,109 @@ Event description:
</tt:MessageDescription>
]]></programlisting>
</section>
<section>
<title>Sensor Data Event Topics</title>
<para>ONVIF defines the following topics related to sensor data:</para>
<itemizedlist>
<listitem>
<para>tns1:Device/Sensor/Temperature/High - Temperature too high event</para>
</listitem>
<listitem>
<para>tns1:Device/Sensor/Temperature/Low - Temperature too low event</para>
</listitem>
<listitem>
<para>tns1:Device/Sensor/RelativeHumidity/High - Relative Humidity too high event</para>
</listitem>
<listitem>
<para>tns1:Device/Sensor/RelativeHumidity/Low - Relative Humidity too low event</para>
</listitem>
<listitem>
<para>tns1:Device/Sensor/AbsoluteHumidity/High - Absolute Humidity too high event</para>
</listitem>
<listitem>
<para>tns1:Device/Sensor/AbsoluteHumidity/Low - Absolute Humidity too low event</para>
</listitem>
</itemizedlist>

<para>The following event should be generated with true value when a temperature sensor detects a value exceeding the configured high threshold (Temperature unit: Kelvin).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/Temperature/High
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

<para>The following event should be generated with true value when a temperature sensor detects a value below the configured low threshold (Temperature unit: Kelvin).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/Temperature/Low
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

<para>The following event should be generated with true value when a relative humidity sensor detects a value exceeding the configured high threshold (relative humidity unit: %).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/RelativeHumidity/High
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

<para>The following event should be generated with true value when a relative humidity sensor detects a value below the configured low threshold (relative humidity unit: %).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/RelativeHumidity/Low
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

<para>The following event should be generated with true value when a absolute humidity sensor detects a value exceeding the configured high threshold (absolute humidity unit: g/m³).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/AbsoluteHumidity/High
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

<para>The following event should be generated with true value when a absolute humidity sensor detects a value below the configured low threshold (absolute humidity unit: g/m³).</para>

<programlisting><![CDATA[Topic: tns1:Device/Sensor/AbsoluteHumidity/Low
Event description:
<tt:MessageDescription IsProperty="false">
<tt:Source>
<tt:SimpleItemDescription Name="SensorID" Type="xs:string"/>
</tt:Source>
<tt:Data>
<tt:SimpleItemDescription Name="Value" Type="xs:float"/>
</tt:Data>
</tt:MessageDescription>]]></programlisting>

</section>
</section>
</chapter>
<chapter>
Expand Down Expand Up @@ -8168,6 +8271,7 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet
<para>The output shall be generated according above described rules.</para>
<section xml:id="_Ref19678957">
<title>Example</title>

<para>The XML example response from PullMessages listed in Section <xref
linkend="ev_PullMessageResp"/> contains two messages which are mapped to the following
corresponding MQTT topics and JSON payload. In these examples TopicPrefix has been set
Expand Down Expand Up @@ -8223,6 +8327,51 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet
}
}
}</programlisting>

<para>The following examples show sensor event messages published via MQTT. In these examples TopicPrefix has been set to "MyDevice".</para>

<para>Topic for temperature high event:</para>
<programlisting>MyDevice/onvif-ej/Device/Sensor/Temperature/High</programlisting>

<para>Temperature high event payload (Temperature unit: Kelvin):</para>
<programlisting>{
"UtcTime": "2025-07-15T14:30:00Z",
"Source": {
"SensorID": "temp_001"
},
"Data": {
"Value": 298.65
}
}</programlisting>

<para>Topic for relative humidity high event:</para>
<programlisting>MyDevice/onvif-ej/Device/Sensor/RelativeHumidity/High</programlisting>

<para>Relative Humidity high event payload (Unit: %)</para>
<programlisting>{
"UtcTime": "2025-07-15T14:30:00Z",
"Source": {
"SensorID": "humidity_001"
},
"Data": {
"Value": 65.2
}
}</programlisting>

<para>Topic for absolute humidity high event:</para>
<programlisting>MyDevice/onvif-ej/Device/Sensor/AbsoluteHumidity/High</programlisting>

<para>Absolute Humidity high event payload (Unit: g/m³)</para>
<programlisting>{
"UtcTime": "2025-07-15T14:30:00Z",
"Source": {
"SensorID": "humidity_001"
},
"Data": {
"Value": 10
}
}</programlisting>

</section>
</section>
<section>
Expand Down
2 changes: 1 addition & 1 deletion wsdl/ver10/events/wsdl/event.wsdl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -387,7 +387,7 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
<xs:annotation>
<xs:documentation>Concrete Topic Expression to select specific metadata topics to publish.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:element>
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
Expand Down
11 changes: 11 additions & 0 deletions wsdl/ver10/schema/metadatastream.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,7 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
<xs:element name="PTZ" type="tt:PTZStream"/>
<xs:element name="Event" type="tt:EventStream"/>
<xs:element name="Extension" type="tt:MetadataStreamExtension"/>
<xs:element name="SensorData" type="tt:SensorData" minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/> <!-- reserved for ONVIF -->
</xs:choice>
</xs:sequence>
Expand All @@ -437,6 +438,16 @@ IN NO EVENT WILL THE CORPORATION OR ITS MEMBERS OR THEIR AFFILIATES BE LIABLE FO
</xs:sequence>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:complexType name="SensorData">
<xs:sequence>
<xs:element name="Type" type="xs:string" minOccurs="1" maxOccurs="1"/>
<xs:element name="Value" type="xs:float" minOccurs="1" maxOccurs="1"/>
<xs:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
<xs:attribute name="UtcTime" type="xs:dateTime" use="required"/>
<xs:attribute name="SensorID" type="xs:string" use="required"/>
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:complexType name="AudioAnalyticsStream">
<xs:sequence>
<xs:element name="AudioDescriptor" type="tt:AudioDescriptor" minOccurs="0" maxOccurs="unbounded"/>
Expand Down
Loading