diff --git a/doc/Core.xml b/doc/Core.xml index b7d619c1b..b457413cb 100644 --- a/doc/Core.xml +++ b/doc/Core.xml @@ -7479,10 +7479,8 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet - - + + @@ -7498,10 +7496,8 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet - - + + @@ -7610,7 +7606,7 @@ http://www.onvif.org/ver10/tev/topicExpression/ConcreteSet PublishFilter - Concrete Topic Expression to select specific topics to publish, see section . + Concrete TopicExpression to select specific topics to publish, see section . Example TopicExpression: "tns1:VideoAnalytics//.|tns1:RuleEngine//." @@ -7732,14 +7728,48 @@ 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 = *("/" 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". + + + SVALUE being the value of the Value attribute of a SimpleItem in the Source part + of the message. All SimpleItem values shall be listed in the SOURCE sequentially in + the same order as they are listed in the response to GetEventProperties. These + values are added to the topic to make it unique so that it can be cached by the + broker individually. See for an example. + + +
Prefix definitions - - + + @@ -7762,23 +7792,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 @@ -7813,36 +7841,36 @@ 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&/1/2/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&/1/2/MyImportanteventbroker "UtcTime": "2008-10-10T12:24:57.789Z "Source": { "VideoSource": "1", + "AnalyticsConfiguration": "2", "Rule": "MyImportantFence2" - }, + }, "Data": { "ObjectId": "19" } -} - +}