diff --git a/doc/Core.xml b/doc/Core.xml index 0853733c0..b3cfd646e 100644 --- a/doc/Core.xml +++ b/doc/Core.xml @@ -7468,10 +7468,8 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet - - + + @@ -7487,10 +7485,8 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet - - + + @@ -7721,14 +7717,51 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet
Topic Structure - Topics are published according to the following structure: - <TopicPrefix>/<PayloadPrefix>/<LocalTopic>[/&<Source>[/<Key>]] - ONVIF topics are are only locally unique within the device so they must be prefixed with a TopicPrefix to become globally unique. The TopicPrefix is configurable through the AddEventBroker command. The TopicPrefix shall not be empty. The PayloadPrefix signals what kind of data that is published. The following prefixes are defined. - + Topics are published according to the following structure, expressed as ABNF rules + according to RFC 5234. Note that special characters like, '#' and '+' shall be omitted + from the topic. For an example, see section . + Topic = TopicPrefix "/" PayloadPrefix "/" LocalTopic [ "&" Source ] + Source = *("/" SNAME "=" SVALUE) + with + + TopicPrefix - uniquely identifies the producer and is configurable through the + AddEventBroker command in the Event service. It shall not be empty. + + + PayloadPrefix - signals in what format the data is published. See below for + possible values. + + + LocalTopic is the same as the ONVIF topic, but because MQTT does not support + namespaces, the namespace prefix for ONVIF topics shall be dropped, so that for + example, "tns1:Device/HardwareFailure/StorageFailure" becomes + "Device/HardwareFailure/StorageFailure". This means that the default topic namespace + is ONVIF, i.e. "http://www.onvif.org/ver10/topics". If an event uses another topic + namespace this should be signalled using the syntax: + "tns:{namespace-alias}/<topic>". Vendor specific extensions should choose a + suitable namespace alias to avoid name clashes. As an example, consider the ONVIF + topic "tns1:Device/HardwareFailure/acme:LensFailure" where + tns1="http://www.onvif.org/ver10/topics" and acme="http://www.acme.com/topics". This + should be translated to the MQTT topic + "Device/HardwareFailure/tns:acme/LensFailure". + + + SNAME being the value of the Name attribute of a SimpleItem in the Source part + of the message. All SimpleItem vame/value pairs shall be listed in the SOURCE + sequentially. These are added to the topic to make it unique so that they can be + cached by the broker individually. + + + SVALUE being the value of the Value attribute of the corresponding + SimpleItem. + + +
Prefix definitions - - + + @@ -7751,23 +7784,21 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet
- The LocalTopic is the same as the ONVIF topic, but because MQTT does not support namespaces, the namespace prefix for ONVIF topics shall be dropped, so that for example, “tns1:Device/HardwareFailure/StorageFailure” becomes “Device/HardwareFailure/StorageFailure”. This means that the default topic namespace is ONVIF, i.e. “​http://www.onvif.org/ver10/topics”. If an event uses another topic namespace this should be signalled using the syntax: "tns:{namespace-alias}/<topic>". Vendor specific extensions should choose a suitable namespace alias to avoid name clashes. As an example, consider the ONVIF topic "tns1:Device/HardwareFailure/acme:LensFailure" where tns1="​http://www.onvif.org/ver10/topics" and acme="​http://www.acme.com/topics". This should be translated to the MQTT topic "Device/HardwareFailure/tns:acme/LensFailure". - The Source and Key are taken from the payload, preceded by a '&' character. For property events, they are added to the topic to make it unique so that they can be cached by the broker individually. For each SimpleItem name/value pair in the Source/Key a ‘/’ character plus the value shall be appended to the topic. The values shall be added in the same order as they are listed in the response to GetEventProperties. Note that special characters like, ‘/’, ‘#’ and ‘+’ shall be omitted from the topic. For an example, see section .
JSON Event Payload This section describes how an ONVIF event is mapped to the JSON data format when published using the "onvif-ej" payload definition. Mapping definition from XML to JSON according to RFC 5234: - MESSAGE ::= "{" TIMEINFO "," SOURCE ["," DATA ] "}" - TIMEINFO ::= DQUOTE "UtcTime" DQUOTE ":" TIMESTAMP - SOURCE ::= DQUOTE "Source" DQUOTE ":" "{" *(ITEM) "}" - DATA ::= DQUOTE "Data" DQUOTE ":" "{" *(ITEM) "}" - ITEM ::= SIMPLEITEM / ELEMENTITEM - SIMPLEITEM ::= DQUOTE SNAME DQUOTE ":" DQUOTE SVALUE DQUOTE - ELEMENTITEM ::= DQUOTE ENAME DQUOTE ": {" [ TYPE *("," TYPE)] "}" - TYPE ::= ATTRIBUTE / SIMPLETYPE / COMPLEXTYPE - ATTRIBUTE ::= DQUOTE ANAME DQUOTE ": " DQUOTE AVALUE DQUOTE - SIMPLETYPE ::= DQUOTE NAME DQUOTE ": " DQUOTE VALUE DQUOTE - COMPLEXTYPE ::= DQUOTE NAME DQUOTE ": {" [TYPE *("," TYPE)] "}" + MESSAGE = "{" TIMEINFO "," SOURCE ["," DATA ] "}" + TIMEINFO = DQUOTE "UtcTime" DQUOTE ":" TIMESTAMP + SOURCE = DQUOTE "Source" DQUOTE ":" "{" *(ITEM) "}" + DATA = DQUOTE "Data" DQUOTE ":" "{" *(ITEM) "}" + ITEM = SIMPLEITEM / ELEMENTITEM + SIMPLEITEM = DQUOTE SNAME DQUOTE ":" DQUOTE SVALUE DQUOTE + ELEMENTITEM = DQUOTE ENAME DQUOTE ": {" [ TYPE *("," TYPE)] "}" + TYPE = ATTRIBUTE / SIMPLETYPE / COMPLEXTYPE + ATTRIBUTE = DQUOTE ANAME DQUOTE ": " DQUOTE AVALUE DQUOTE + SIMPLETYPE = DQUOTE NAME DQUOTE ": " DQUOTE VALUE DQUOTE + COMPLEXTYPE = DQUOTE NAME DQUOTE ": {" [TYPE *("," TYPE)] "}" with @@ -7802,36 +7833,40 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet The output shall be generated according above described rules.
Example - The XML example response from PullMessages listed in Section contains two messages which are mapped to the following corresponding MQTT topics and JSON payload: - Topic: - MyDevice/onvif-ej/RuleEngine/LineDetector/Crossed/&1/2/MyImportantFence1 -Payload: -{ + The XML example response from PullMessages listed in Section contains two messages which are mapped to the following + corresponding MQTT topics and JSON payload. In these examples TopicPrefix has been set + to "MyDevice". + Topic for the first message: + MyDevice/onvif-ej/RuleEngine/LineDetector/Crossed&/VideoSource=1/ +AnalyticsConfiguration=2/Rule=MyImportantFence1 + Payload for the first message: + { "UtcTime": "2008-10-10T12:24:57.321Z", "Source": { "VideoSource": "1", "AnalyticsConfiguration": "2", "Rule": "MyImportantFence1" - }, + }, "Data": { "ObjectId": "15" } -} - -Topic: - MyDevice/onvif-ej/RuleEngine/LineDetector/Crossed/&1/2/MyImportantFence2Payload: -Payload: -{ +} + Topic for the second message: + MyDevice/onvif-ej/RuleEngine/LineDetector/Crossed&/VideoSource=1/ +AnalyticsConfiguration=2/Rule=MyImportantFence2 + Payload for the second message: + { "UtcTime": "2008-10-10T12:24:57.789Z "Source": { "VideoSource": "1", + "AnalyticsConfiguration": "2", "Rule": "MyImportantFence2" - }, + }, "Data": { "ObjectId": "19" } -} - +}