From 52a109d863fafff98922fcec8fdb3d7536619e14 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 11:26:00 -0600 Subject: [PATCH 01/12] 0.0.4 --- inbox/fis.xml | 411 +++++++++----------------------------------------- 1 file changed, 74 insertions(+), 337 deletions(-) diff --git a/inbox/fis.xml b/inbox/fis.xml index 1b8706ec..74f776ee 100644 --- a/inbox/fis.xml +++ b/inbox/fis.xml @@ -19,7 +19,6 @@ XEP-0234 XEP-0059 XEP-0265 - XEP-0055 XEP-0135 @@ -32,16 +31,22 @@ j.lagrange@jabber.org j.lagrange@gajim.org + + Lance + Stout + lancestout@gmail.com + - 0.0.2 - 2012-10-14 + 0.0.4 + 2013-01-26 jl - Second draft + Third draft

XMPP extensions provide ways of transferring files between peers (such as &xep0234; and &xep0096;). However, file transfer is currently limited to needing that the transfer be initiated by the hosting entity. The &xep0234; extension, provides for a way to request files, but it requires the requesting entity to have information about the file being requested, so that it can be uniquely identified.

This document defines an extension which allows the request of information of files being offered by a hosting entity so they can later be requested in a file transfer; If the requesting entity is interested in the file.

+

&xep0135; is a previous extention that attempted to solve the same problem as this one, but unfortunetly it didn't generate much interest and it got deprecated. This extention aims be a modern replacement for XEP-0135.

IRC users have been able to bypass the limitations of the protocol by using bots that provide information of files and initiate transfer on command. A major downside of this method is that not every user is capable of sharing its files. The aim of this document is to provide a similar functionality while making it easier for users to offer and request information about files.

Microsoft's MSN proprietary IM client, used to provide similar functionality using "Sharing Folders", but this was replaced by Windows Live SkyDrive

@@ -49,56 +54,37 @@
  1. Enable a requesting entity to traverse the shared directory of an offering entity (REQUIRED)
  2. Enable a requesting entity to get detailed information about files. (REQUIRED)
    3. -
  3. Enable a requesting entity to search files hosted by an offering entity.(OPTIONAL)
    4. -
  4. Allow the use of MUCs to share information about files among the users.(OPTIONAL)
    5. -
-

This protocol assumes the existence of a shared directory (either virtual or physical). The hosting entity must not advertise empty directories. The hosting entity is responsible of maintaining the structure of that directory (such as not allowing two files with the same name and preventing cycles within directories). The hosting entity is in no way required to present the same shared directory to different requesters.

+

This protocol assumes the existence of one or more shared directories (either virtual or physical). The hosting entity must not advertise empty directories. The hosting entity is responsible of maintaining the structure of those directories (such as not allowing two files with the same name and preventing cycles within directories). The hosting entity is in no way required to present the same shared directories to different requesters. In fact, the reason multiple share directories are allowed, is to make it easier for implementers to manage permissions of who can see what files.

 -

If a requesting entity wishes to traverse the shared folder of an offering entity. It can do so by querying the root directory as it is shown in the following example:

+

If a requesting entity wishes to know what files are being shared by an offering entity, it can do so by sending the following query:

- - - - - + ]]> -

If the offering entity has files to share, it MUST respond with the root-level files of its shared folder. Files and directories at the root level MUST not be the child of any "directory" tag. In order to save bandwidth, the offering entity MAY omit all the children of the file tag except the "name" which is required and MUST always be present. -

-

The file tag has the same attributes as defined in &xep0096;. The "name" attribute is required and must be included in every response. The "size" attribute is only required when responding with detailed information about a file.

- +

If the offering entity wishes to share files with the requesting entity, it may respond with a list of shared folders. It MUST not include any files in this response.

+ - - - - 1969-07-21T02:56:15Z - This is a test. If this were a real file... - test.txt - 1022 - 552da749930852c69ae5d2141d3766b1 - - - test2.txt - - - - + + + + + ]]> @@ -109,14 +95,46 @@ from='romeo@montague.net/home' to='juliet@capulet.com/chamber' id='1234'> - - - - - + ]]> +

Requesting the list of files and directories within a directory.

+ + + + +]]> + +

When replying with a list of files, the offering entity can choose to either reply with verbose information on the file using the file attributes defined by &xep0254; or it may reply only with the 'name' attribute, which is required and MUST be included in every response.

+

It is RECOMENDED, when the list files to be sent is small, that a verbose response be made (in order to avoid going back and forth requesting information), and that a non-verbose reponse be made otherwise. This recomendation is made to save bandwidth.

+ + + + + test.txt + 1969-07-21T02:56:15Z + This is a test. If this were a real file... + + 1022 + 552da749930852c69ae5d2141d3766b1 + + + test2.txt + + + + +]]> +

If the requesting entity wants to get detailed information about a file. It can do so by providing its full path.

- - - - test2.txt - - - + ]]> -

When replying with detailed information about a file, the offering entity must always include the "name" and "size".

- - - - test2.txt - 1000 - - - - -]]> - - - - - - - - - -]]> - - - - - - - - test3.png - - - test4.png - - - - - + + + test2.txt + 1000 + + ]]> - -

Sometimes the list of files is too big to be efficiently traversed or there are too many peers offering files. This extensions allows simple file search to ease the discovery of files.

-

The requesting entity can request the fields on which a search can be performed.

- - - - - - -]]> - -

The offering entity replies with its search fields. The fields in the following example are required, and they MUST be supported.

- - - - - - - - - - - - -]]> - -

Different files have different metadata and all of them may not be completly covered by the fields mentioned before. Of course, any field that doesn't fit could be included in "desc", however this can make search difficult as it is not clearly defined what to look for.

-

Fields can be extended using dataforms, as it is defined in &xep0055;

- - - - - - - - - - - - jabber:iq:search - - - - - - - - - - -]]> - - - - - - - - jabber:iq:search - - - image - - - - - -]]> - - - - - - - - jabber:iq:search - - - pics/test3.png - - - pics/test4.png - - - - - -]]> - -

If a requesting entity wishes to search for a particular keyword in the files name, it only needs to send the keyword within the 'name' tag and it MUST not be a full path.

-

The requester may also use the 'desc' to match keywords.

- - - - - test - - - -]]> - - - - - - - test.txt - - - test2.txt - - - pics/test3.png - - - pics/test4.png - - - - -]]> - -

When simple keyword matching is not enough to efficiently search files, regular expressions (as defined in &xep0004;) can be used

- - - - - - - jabber:iq:search - - - - *.png - - - - - - -]]> - - - - - - - pics/test3.png - - - pics/test4.png - - - - -]]> - - - - -

For the most part, discovering files in a MUC is exactly the same as what has been described in this document. However there are some considerations to have present.

-

First, it is RECOMMENDED that a participant in a MUC should have a single shared folder associated with the entire room, as opposed to advertise different files to different participants of the room. This is to reduce the complexity of the client software. Also, due to volatile nature of the participants in a room, keeping track of permissions is more trouble than what it is worth.

-

Second, a participant may discover files of all the participants in the room by sending the request to the room itself. It is RECOMMENDED that the search capabilities of this protocol be used for this.

If a considerable amount of files are being shared by the offering entity, it may be the case that the offering entity response might be too be for the server to handle; As there might be a limitation on the size of the stanzas in the current stream. In order to solve this, extensions have been devised and their implementation are hereby recommended along with the implementation of this extension.

-

&xep0059; defines a way of limiting the results of a request. There are some considerations to use &xep0059; along with this extension.

-

First, in &xep0059; it is defined that the requesting entity is the one that sets the limit of the number of items that can be replied. So it is up to the requesting entity to choose a sensible number.

-

Second, since this protocol defines a way of handling the directory tree structure by allowing files tags to be children of a directory tags, it becomes difficult to define items for &xep0059;. Therefore, when responding to a request using &xep0059;, the offering entity MUST NOT send directory tags with files as their children, file tags must be sent separately with their path (starting at the root shared folder) in their name attribute.

- - - - - - - test.txt - - - - - test2.txt - - - - - pics/test3.png - - - - - pics/test4.png - - - - - - - - -]]> - +

&xep0059; defines a way of limiting the results of a request. There are some considerations to use result sets along with this extension.

+

First, it is defined that the requesting entity is the one that sets the limit of the number of items that can be replied. So it is up to the requesting entity to choose a sensible number.

+

Second, since this protocol defines a way of handling the directory tree structure by allowing file tags to be children of a directory tags, it becomes difficult to define items for Result Set Management. Therefore, when responding to a request, the offering entity MUST NOT send directory tags with files as their children.

-

One obvious way to overcome the limitations of sending large stanzas in-band, is to transfer that information out of band. &xep0065; could be used for that purpose. It is hereby RECOMMENDED its implementation when the offering entity has a massive amount of files that would not be practical to advertise in-band.

-

It is further recommended that when using XEP-0065, the entire directory structure, along with all the files in the shared folder and subfolders, be exchanged in one single reply. Also, all the files attributes should be included. This is to avoid wasting bandwidth initiating out of band streams going back and forth.

+

One obvious way to overcome the limitations of sending large stanzas in-band, is to transfer that information out of band. &xep0265; could be used for that purpose. It is hereby RECOMMENDED its implementation when the offering entity has a massive amount of files that would not be practical to advertise in-band.

+

It is further recommended that when using XEP-0265, the entire directory structure, along with all the files in the shared folder and subfolders, be exchanged in one single reply. Also, all the files attributes should be included. This is to avoid wasting bandwidth initiating out of band streams going back and forth.

- - -

As it was previously discussed, when requesting detailed information about a file, only the "name" and "size" attributes required, but it is strongly RECOMMENDED that the hash attribute be included, in order to reduce the chances of sending the wrong file. When requesting the file to be transferred using &xep0234;, the information that must be provided has to identify the file uniquely. It is then RECOMMENDED that when requesting a file, the full path of the file in the shared folder be included in the "name" attribute.

+ + +

As it was previously discussed, when requesting detailed information about a file, only the "name" attribute is required, but it is strongly RECOMMENDED that the hash attribute be included, in order to reduce the chances of sending the wrong file. When requesting the file to be transferred using &xep0234;, the information that must be provided has to identify the file uniquely. It is then RECOMMENDED that when requesting a file, the full path of the file in the shared folder be included in the "name" attribute.

 + +

For the most part, discovering files in a MUC is exactly the same as what has been described in this document. However, it is RECOMMENDED that a participant in a MUC should have a single shared folder associated with the entire room, as opposed to advertise different files to different participants of the room. This is to reduce the complexity of the client software. Also, due to volatile nature of the participants in a room, keeping track of permissions is more trouble than what it is worth.

+

A denial of service is possible by repeatedly requesting files. Implementers are advised to take this into consideration and include queues and limits into their implementations.

From a097a6609f93b0721a8eeb83e9d9e7ddff7f9033 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:44:45 -0600 Subject: [PATCH 02/12] accepted for publication --- inbox/dtls-fingerprint.xml => xep-0320.xml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename inbox/dtls-fingerprint.xml => xep-0320.xml (100%) diff --git a/inbox/dtls-fingerprint.xml b/xep-0320.xml similarity index 100% rename from inbox/dtls-fingerprint.xml rename to xep-0320.xml From 995b5ec33b71fea173dbf682753cd5ac78186744 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:45:15 -0600 Subject: [PATCH 03/12] accepted for publication --- inbox/roster-management.xml => xep-0321.xml | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename inbox/roster-management.xml => xep-0321.xml (100%) diff --git a/inbox/roster-management.xml b/xep-0321.xml similarity index 100% rename from inbox/roster-management.xml rename to xep-0321.xml From 19fac71a6b04714ab2fe8e55da289076999cb7ff Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:45:45 -0600 Subject: [PATCH 04/12] accepted for publication --- inbox/exi.xml => xep-0322.xml | 394 +++++++++++++++++++++++++--------- 1 file changed, 297 insertions(+), 97 deletions(-) rename inbox/exi.xml => xep-0322.xml (65%) diff --git a/inbox/exi.xml b/xep-0322.xml similarity index 65% rename from inbox/exi.xml rename to xep-0322.xml index 38cb5c99..4bb5d667 100644 --- a/inbox/exi.xml +++ b/xep-0322.xml @@ -1,4 +1,5 @@ + %ents; @@ -6,7 +7,7 @@
- Using Efficient XML Interchange (EXI) Format in XMPP + Efficient XML Interchange (EXI) Format This specification describes how EXI compression can be used in XMPP networks. This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). @@ -37,6 +38,32 @@ peter.waher@jabber.org http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + 0.0.4 + 2013-03-19 + pwa + +

Added support for uploading EXI-compressed schema files.

+ + + + 0.0.3 + 2013-03-15 + pwa + +

Added definition: EXI body.

+

Added note regarding preserverance of namespace prefixes.

+

Corrected the language.

+ + + + 0.0.2 + 2013-03-13 + pwa + +

Added support for session-wide buffers and string tables.

+ + 0.0.1 2013-03-12 @@ -54,7 +81,7 @@ communicate efficiently. The strong support in EXI for generating efficient stubcodes is also vital to build efficient code in constrained devices.

- Activating EXI compression requires a handshake to take place prior, where the server and client agrees on a set of parameters. Some of these parameters may increase compression ratio, + Activating EXI compression requires a handshake to take place prior, where the server and client agree on a set of parameters. Some of these parameters may increase the compression ratio, at the cost of processing power and readability. These parameters include:

    @@ -71,10 +98,10 @@
  • Value partition capacity.

- These parameters will be discussed deeper in the following sections. There are also default values users can use to commence evaluating EXI compression. + These parameters will be discussed in greater depth in the following sections. There are also default values that can be used to commence evaluating EXI compression.

- The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if there exist schemas + The single most important property to agree on however, is the set of schemas to use during EXI compression. EXI compresses XML much more efficiently if schemas exist describing the format of the expected XML. Since the server is not supposed to know all possible XML schemas, a mechanism is provided in this document whereby schemas can be interchanged, so that the server can adapt its compression to the needs of the client.

@@ -96,12 +123,12 @@ ]]>

- Support for EXI compression is detected by the existance of the exi compression method in the features stanza. + Support for EXI compression is detected by the existence of the exi compression method in the features stanza.

- If the client attempts to activate EXI stream at this point, before negotiation of EXI properties have been performed, the server must respond with a + If the client attempts to activate an EXI stream at this point, before the negotiation of EXI properties has been performed, the server must respond with a setup-failed response.

@@ -143,27 +170,27 @@ MD5 hash. The MD5 hash provides a way to detect small changes in the file, even if the byte size and namespace are the same.

- Schema files that the server does not have, based on namespace, byte size and MD5 hash, are marked with the missingSchema element instead of the + Schema files that the server does not have (based on namespace, byte size and MD5 hash) are marked with the missingSchema element instead of the normal schema element.

- The client can, at this point, choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server. - The XMPP session will continue to work in its current state. -

+ At this point the client can choose to abort the EXI enablement sequence, if it cannot accommodate itself with the proposed parameter settings provided by the server. + The XMPP session will continue to work in its current state. Aborting does not require taking further action from the client. +

- If the server lacks information about a schema file, this is specified in the response through the missingSchema elements. The client can at this point - either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course, - uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If not possible to upload the - schema files, consideration should be taken to install the schema files manually at the server.) -

+ If the server lacks information about a schema file, it is specified in the response through the missingSchema elements. At this point, the client can + either choose to accept that these schema files are not available, making compression less efficient, or choose to upload the missing schema files to the server. Of course, + uploading schema files would require the device to have sufficient buffers and memory to store and upload the schema files in the first place. (If it is not possible to upload the + schema files, consideration should be given to installing the schema files manually at the server.) +

To upload a schema file, the client simply sends the schema file using an uploadSchema element, as follows:

+ PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4NCjx4czpzY2hlbWENCiAgICB4 bWxuczp4cz0naHR0cDovL3d3dy53My5vcmcvMjAwMS9YTUxTY2hlbWEnDQogICAgdGFyZ2V0TmFt ZXNwYWNlPSd1cm46eG1wcDpzbjpwcm92aXNpb25pbmcnDQogICAgeG1sbnM9J3Vybjp4bXBwOnNu @@ -175,11 +202,11 @@ ]]>

- The schema itself is sent using base64 encoding to the server. This, to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The - server then computes the target namespace, byte size and MD5 Hash from this schema file sent. + The schema itself is sent using base64 encoding to the server. This is to make sure a binary exact copy is transferred, maintaining encoding, processing instructions, etc. The + server then computes the target namespace, byte size and MD5 Hash from the sent schema file.

- If the client desires, it can test the EXI setup again. This is however optional, but can be used to test that uploading the schema files, and any new property values + If the client desires, it can test the EXI setup again. This is optional, but can be used to test that uploading the schema files, and any new property values are accepted by the server.

@@ -190,7 +217,7 @@ ]]>

- And the server should now respond: + And the server should then respond:

+ +

+ The uploadSchema command has an optional attribute called contentType that can be used to send different types of documents + to the server. This is not a MIME content type, but an enumeration with the following options: +

+ + + + + + + + + + + + + + + + + +
ValueDescription
TextThe schema is sent as plain text. If no encoding is provided in the XML header of the schema file, UTF-8 encoding is assumed. This is the default value.
ExiBodyThe schema file is sent as an EXI compressed file, but only the body is sent. *
ExiDocumentThe schema file is sent as an EXI compressed file. The entire file, including Exi header is provided. *
+

+ (*) These options assume the following set of default EXI options are used. It is assumed the XMPP server has more capabilities than the client, so the following + set of options must be supported by the XMPP server. The schema files can be precompressed and stored as binary files on the client for easier transmission. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionDefault value
Version1
alignmentbit-packed
compressionfalse
strictfalse
fragmentfalse
preserveall false
selfContainedfalse
schemaIdNo schema
datatypeRepresentationMapNo map
blockSize1000000 (one million)
valueMaxLengthunbounded
valuePartitionCapacityunbounded
+

+ Since EXI compression does not perserve the extact binary representation of the schema file (for instance it doesn't preserve white space), the server + cannot correctly compute byte size and an MD5 hash for the file. Therefore, the client needs to provide this information in the uploadSchema + command using the bytes and md5Hash attributes. They are mandatory in case EXI compressed schema files are uploaded to the + server. Also note that the byte length and MD5 Hash should be computed on the original XML Schema file, not the compressed or decompressed version. +

+

As an alternative to uploading a schema file to the server, the client can ask the server to download a schema file by itself. This is done using the downloadSchema @@ -219,7 +334,7 @@ from the downloaded schema.

- When the schema has been downloaded, a successful download response is returned, as follows: + When the schema has been downloaded, the following successful download response is returned:

]]>

- If the URL could not be resolved, a response as follows is returned: + If the URL could not be resolved, the following response is returned:

]]>

- If a timeout occurred during the download attempt, a response as follows is returned: + If a timeout occurred during the download attempt, the following response is returned:

]]>

- If the url points to something that is not a schema, a response as follows is returned: + If the url points to something that is not a schema, the following response is returned:

]]>

- If some other error occurs, unforseen by this specification, the server can simply respond with a generic error message, as follows: + If an error occurs that is unforeseen by this specification, the server can simply respond with a generic error message, as follows:

Note: Downloading a schema, might download a version which does not correspond to the desired version - of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client. + of the schema. It's more important in this case so the client checks that the server actually has the version of the schema required by the client.

- +

When EXI option negotiation has been completed, the client can tell the server that it is ready to start compression. It does this using the normal compress stanza, as follows: @@ -287,15 +402,16 @@ ]]>

- The server now having necessary knowledge on how the EXI engine should be configured for the current session, responds: + The server now has the necessary knowledge on how the EXI engine should be configured for the current session and it responds as follows:

- + ]]>

When the client receives acknowledgement that the compression method has been accepted, it restarts the stream, as explained in - XEP 0138. + XEP 0138, except that it must not resend the <stream> + start element sequence. Similarly, the client must not send a </stream> element when closing the session. Closing the connection is sufficient.

@@ -340,7 +456,64 @@

The valuePartitionCapacity option specifies the maximum number of value content items in the string table at any given time. The default value "unbounded" is assumed when the "valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions Optimized for Frequent use of String Literals specifies the behavior of the string table when this capacity is reached.

+

+ The sessionWideBuffers controls buffer and string table life time. If set to true, all buffers, string tables, etc. will be maintained during the entire session. + This may improve performance during time since strings can be omitted in the compressed binary stream, but it might also in some cases degrade performance since more options are + available in the tables, requiring more bits to encode strings. The default value is false, meaning that buffers, string tables, etc., are cleared between each stanza. (This option + is EXI/XMPP specific.) +

+ +

+ The transmission of EXI-compressed stanzas takes the form of a sequence of EXI bodies. In order for the recipient to be able to correctly interpret these incoming + EXI bodies, the sender is required to flush any pending bits at the end of the last End Document (ED) event for each stanza and then send any pending bytes available + in the output buffer. Since this makes sure each EXI body starts at an even byte boundary, it permits the recipient to decompress the body into an XML stanza. +

+

+ Therefore, each stanza sent on the stream, must be compressed separately, reusing the same options as used by the stream. + (Options are not sent on the stream, only the generated EXI bodies). +

+

+ Compression of the stanza must be done in document mode, not fragment mode, including the Start Document (SD) and End Document (ED) events. + If there are unwritten bits pending after the last End Document (ED) event (after the end of the stanza), Zero-bits are written until a byte boundary is created. + The receptor must ignore bits in the last byte after the last End Document event has been received. +

+

+ During setup of the EXI compression engine, the client can choose if buffers are to be reused between stanzas, or cleared between each stanza. This is done + using the EXI over XMPP specific option sessionWideBuffers, which is false by default, meaning buffers and string tables are cleared between + each stanza. +

+

+ There may be cases where maintaining buffers and string tables throughout the session is preferrable. Since strings are already available in the buffers, + they don't need to be output in the stream the first time they appear in a stanza. However, the number of strings in tables increase, and so does the number of bits required to + encode them. Depending on what type of communication is performed, this option might give better results one way or another. If the same type of message is always + sent, maintaining string buffers may be more efficient. But if the client sends many many different types of messages, clearing buffers may be more efficient. +

+

+ Note that the stream of EXI bodies is indefinite. It only stops when the session is closed, i.e. when the socket connection is dropped. Therefore, the buffers can grow + indefinitely unless control is maintained on what types of messages are sent, their contents (specifically string values), and to whom they are sent (JIDs being strings). + All string tables and buffers must be cleared when a connection is lost. +

+

+ Note also that if you want the option to enter a session in the middle of the flow to listen to the communication, you need to clear tables and buffers between each + stanza, or you will not be able to decode the binary stream appropriately. +

+ + +

+ Normally, prefixes are not preserved during EXI compression and decompression. If the communicating parties (sending client, XMPP server(s) and receiving clients) + interpret incoming stanzas and content according to namespace, this should be sufficient. However, some implementations do not check namespaces, but prefix names used. + In such cases, all communicating parties are required to enable the preserve prefixes option during negotionating. +

+

+ Note: It is not sufficient that one party enable this option. Both sender and received are required to enable this option, or prefix names will be + lost in the transmission. +

+

+ Note also, that preserving prefix names result in less efficient compression. Therefore, all clients implementing EXI compression should strive to parse incoming + XML based on namespace, not prefix name. +

+

To successfully implement a network with clients having limited memory, such as sensor networks, care should be taken to make sure necessary schema files are @@ -369,27 +542,27 @@ download one.

- Uloading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema + Uploading a schema has the advantage, that the client knows exactly the version that the server requires. It has the disadvantage, that the client needs to store the schema and send a possible large schema to the server. If EXI is used because the device has limited memory, uploading a schema might not be an option.

- Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay respect + Downloading a schema has the advantage, that size of schema does not matter. The disadvantage is that asynchronous errors might occur, so the client needs to pay attention to the responses returned by the server when downloading schemas. Also, downloading a schema, might download a version which does not correspond to the desired version - of the schema. So, it's more important in this case, the client checks that the server actually has the version of the schema required by the client. + of the schema. So, it's more important in this case that the client checks that the server actually has the version of the schema required by the client. +

+ + +

+ If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward + binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress + packets sent through it. +

+

+ Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server + some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression + settings are most common.

- -

- If two XMPP clients communicate with each other through an XMPP server, and both clients use EXI compression, the server must only forward - binary packets if both EXI compressed channels have exactly the same setup. If any parameter is different, the server MUST always recompress - packets sent through it. -

-

- Since the server always needs to decompress incoming EXI compressed packets to decode headers, omitting the compression part might save the server - some processing power, but not all. Note that, in some networks it might be common using similar compression settings, while in others different compression - settings are most common. -

-

@@ -417,7 +590,7 @@ - + @@ -452,36 +625,36 @@ The alignment option is used to control the alignment of event codes and content items. - The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value - assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment - and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options - document, respectively. When the value of compression option is set to true, alignment of the EXI Body is - governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment" - element MUST NOT appear in an EXI options document when the "compression" element is present. + The value is one of bit-packed, byte-alignment or pre-compression, of which bit-packed is the default value + assumed when the "alignment" element is absent in the EXI Options document. The option values byte-alignment + and pre-compression are effected when "byte" and "pre-compress" elements are present in the EXI Options + document, respectively. When the value of compression option is set to true, alignment of the EXI Body is + governed by the rules specified in 9. EXI Compression instead of the alignment option value. The "alignment" + element MUST NOT appear in an EXI options document when the "compression" element is present. The compression option is a Boolean used to increase compactness using additional - computational resources. The default value "false" is assumed when the "compression" element is absent in - the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes - and associated content are compressed according to 9. EXI Compression regardless of the alignment option - value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the - "alignment" element is present. + computational resources. The default value "false" is assumed when the "compression" element is absent in + the EXI Options document whereas its presence denotes the value "true". When set to true, the event codes + and associated content are compressed according to 9. EXI Compression regardless of the alignment option + value. As mentioned above, the "compression" element MUST NOT appear in an EXI options document when the + "alignment" element is present. The strict option is a Boolean used to increase compactness by using a strict - interpretation of the schemas and omitting preservation of certain items, such as comments, processing - instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is - absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those - productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and - schema-informed element and type grammars are restricted to only permit items declared in the schemas. - A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions - consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document - when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same - options document. + interpretation of the schemas and omitting preservation of certain items, such as comments, processing + instructions and namespace prefixes. The default value "false" is assumed when the "strict" element is + absent in the EXI Options document whereas its presence denotes the value "true". When set to true, those + productions that have NS, CM, PI, ER, and SC terminal symbols are omitted from the EXI grammars, and + schema-informed element and type grammars are restricted to only permit items declared in the schemas. + A note in section 8.5.4.4.2 Adding Productions when Strict is True describes some additional restrictions + consequential of the use of this option. The "strict" element MUST NOT appear in an EXI options document + when one of "dtd", "prefixes", "comments", "pis" or "selfContained" element is present in the same + options document. @@ -492,7 +665,7 @@ Processing instructions are preserved. Must not be used together with the strict - option. + option. @@ -508,41 +681,50 @@ Lexical form of element and attribute values can be preserved in value content items. - Can be used together with the strict option. + Can be used together with the strict option. The selfContained option is a Boolean used to enable the use of self-contained elements - in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body, - allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI - options document when one of "compression", "pre-compression" or "strict" elements are present in the - same options document. The default value "false" is assumed when the "selfContained" element is absent - from the EXI Options document whereas its presence denotes the value "true". + in the EXI stream. Self-contained elements may be read independently from the rest of the EXI body, + allowing them to be indexed for random access. The "selfContained" element MUST NOT appear in an EXI + options document when one of "compression", "pre-compression" or "strict" elements are present in the + same options document. The default value "false" is assumed when the "selfContained" element is absent + from the EXI Options document whereas its presence denotes the value "true". The blockSize option specifies the block size used for EXI compression. When the - "blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used. - The default blockSize is intentionally large but can be reduced for processing large documents on - devices with limited memory. + "blockSize" element is absent in the EXI Options document, the default blocksize of 1,000,000 is used. + The default blockSize is intentionally large but can be reduced for processing large documents on + devices with limited memory. The valueMaxLength option specifies the maximum length of value content items to be - considered for addition to the string table. The default value "unbounded" is assumed when the - "valueMaxLength" element is absent in the EXI Options document. + considered for addition to the string table. The default value "unbounded" is assumed when the + "valueMaxLength" element is absent in the EXI Options document. The valuePartitionCapacity option specifies the maximum number of value content - items in the string table at any given time. The default value "unbounded" is assumed when the - "valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions - Optimized for Frequent use of String Literals specifies the behavior of the string table when this - capacity is reached. + items in the string table at any given time. The default value "unbounded" is assumed when the + "valuePartitionCapacity" element is absent in the EXI Options document. Section 7.3.3 Partitions + Optimized for Frequent use of String Literals specifies the behavior of the string table when this + capacity is reached. + + + + + If set to true, all buffers, string tables, etc. will be maintained during the + entire session. This may improve performance during time since strings can be omitted in the + compressed binary stream, but it might also in some cases degrade performance since more options + are available in the tables, requiring more bits to encode strings. The default value is false, + meaning that buffers, string tables, etc., are cleared between each stanza. @@ -558,32 +740,50 @@ The alignment option value bit-packed indicates that the event codes and associated - content are packed in bits without any padding in-between. + content are packed in bits without any padding in-between. The alignment option value byte-alignment indicates that the event codes and - associated content are aligned on byte boundaries. While byte-alignment generally results in EXI - streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a - help in some use cases that involve frequent copying of large arrays of scalar data directly out - of the stream. It can also make it possible to work with data in-place and can make it easier to - debug encoded data by allowing items on aligned boundaries to be easily located in the stream. + associated content are aligned on byte boundaries. While byte-alignment generally results in EXI + streams of larger sizes compared with their bit-packed equivalents, byte-alignment may provide a + help in some use cases that involve frequent copying of large arrays of scalar data directly out + of the stream. It can also make it possible to work with data in-place and can make it easier to + debug encoded data by allowing items on aligned boundaries to be easily located in the stream. The alignment option value pre-compression indicates that all steps involved - in compression (see section 9. EXI Compression) are to be done with the exception of the final - step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a - duplicate compression step when compression capability is built into the transport protocol. In - this case, pre-compression just prepares the stream for later compression. + in compression (see section 9. EXI Compression) are to be done with the exception of the final + step of applying the DEFLATE algorithm. The primary use case of pre-compression is to avoid a + duplicate compression step when compression capability is built into the transport protocol. In + this case, pre-compression just prepares the stream for later compression. - + + + + + + + + + + + + + + + + + + + @@ -632,7 +832,7 @@ ]]> - -

Thanks to Joachim Lindborg for all valuable feedback.

- - + +

Thanks to Joachim Lindborg, Yusuke Doi, Takuki Kamiya, Tina Beckman, Karin Forsell, Jeff Freund and Rumen Kyusakov for all valuable feedback.

+ + \ No newline at end of file From cb90b3f54a116536a1da6ffe861916521bb231ce Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:46:29 -0600 Subject: [PATCH 05/12] accepted for publication --- inbox/sensor-data.xml | 1257 ------------------------------------ xep-0323.xml | 1430 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1430 insertions(+), 1257 deletions(-) delete mode 100644 inbox/sensor-data.xml create mode 100644 xep-0323.xml diff --git a/inbox/sensor-data.xml b/inbox/sensor-data.xml deleted file mode 100644 index c6bf402a..00000000 --- a/inbox/sensor-data.xml +++ /dev/null @@ -1,1257 +0,0 @@ - -EXI Efficient XML Interchange (EXI) Format <http://www.w3.org/TR/exi/>." > - - - %ents; -]> - - -
- Sensor Data Interchange over XMPP - This specification provides the common framework for sensor data interchange over XMPP networks. - - This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - xxxx - ProtoXEP - Standards Track - Standards - Council - - XMPP Core - XEP-0001 - Etc. - - - - NOT_YET_ASSIGNED - - Peter - Waher - peter.waher@clayster.com - peter.waher@jabber.org - http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ - - - 0.0.1 - 2013-03-07 - pwa - -

First draft.

- - -
- -

This XEP provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. It includes a hardware abstraction model, removing any - technical detail implemented in underlying technologies.

- -

Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). - Therefore, simplicity of utmost importance. Furthermore, sensor networks can become huge, easily with millions of devices in peer-to-peer networks.

- -

Sensor networks contains many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XEPDescription
XEP-0000-ExiDefines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered - in all sensor network implementations where memory and packet size is an issue.
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittantly available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
xep-0000-SN-ProvisioningDefines how provisioning, the management of access privileges, etc., can be efficiently and easilly implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
xep-0000-SN-SensorDataThis specification. Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. - It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs.
- - -

The following table lists common terms and corresponding descriptions.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TermDescription
ActuatorDevice containing at least one configurable property or output that can and should be controlled by some other entity or device.
Computed ValueA value that is computed instead of measured.
ConcentratorDevice managing a set of devices which it publishes on the XMPP network.
FieldOne item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timepoint, Localization information, etc.
Field NameName of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
Historical ValueA value stored in memory from a previous time point.
Identification ValueA value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
Localization informationOptional information for a field, allowing the sensor to control how the information should be presented to human viewers.
MeterA device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
Momentary ValueA momentary value represents a value measured at the time of the readout.
NodeGraphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, etc., are often depicted as nodes and links between sensors (frienships) are depicted as edges. - In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible.
Peak ValueA maximum or minimum value during a given period.
PrecisionIn physics, precision determins the number of digits of precision. In sensor networks however, this definition is not easilly applicable. Instead, precision - determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and - delivering field information in sensor networks should always retain the number of decimals in a message.
SensorDevice measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc.
SNSensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
Status ValueA value displaying status information about something.
TimepointTimepoint of value, when the value was sampled or recorded.
Value StatusStatus of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
UnitPhysical unit of value. Example: MWh, l/s, etc.
ValueA field value. Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
Value TypeWhat type of value is represented by the field. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
WSNWireless Sensor Network, a sensor network including wireless devices.
- - -

- The most common use case in sensor network application, is meter readout. It's performed using a request and response mechanism, as is shown in the following diagram. -

-

- -

-

- The readout request is started by the client sending a req request to the device. Here, the client selects a sequence number seqnr. - It should be unique among requests made by the client. The device will use this sequence numbers in all messages sent back to the client. -

-

- The request also contains a set of readout types that very roughly determine what the client wants to read. What the client actually will return will be determined by - a lot of other factors, such as make and model of device, any provisioning rules provided, etc. This parameter just gives a hint on what kind of data is desired. It is implicit in the request - by the context what kind of data is requested. Examples of readout types are: Momentary values, peak values, historical values, computed values, status values, identification values, etc. -

-

- If reading historical values, the client can also specify an optional time range using the from and to parameter values, giving the device a hint on - how much data to return. -

-

- If the client wants the readout to be performed at a given point in time, the client can define this using the optional parameter when. -

-

- There's an optional parameter ids that the client can provide. If omitted, the request includes all sensors or devices managed by the current JID. - But, if the JID is controlled by a system, device or concentrator managing various devices, the ids parameter restricts the readout to specific individuals. -

-

- Note: The device is not required to follow the hints given by the client. These are suggestions the client can use to minimize its effort to perform the readout. - The client MUST make sure the response is filtered according to original requirements by the client after the readout response have been received. -

-

- If the device accepts the client request, it sends an accepted response back to the client. The client also has to determine if the readout is commenced directly, - or if it is to be queued for later processing. Note that the request can be queued for several reasons. The device can be busy, and queues it until it is ready to process the request. - It can also queue the request if the client has requested it to be executed at a given time. If the request is queued, the device informs the client of this using the queued - attribute. Note however, that the device will process the request when it can. There's no guarantee that the device will be able to process the request exactly when the client requests it. -

-

- If the request was queued, the device will send a message informing the client when the readout is begun. This is done using a started message, using the same - seqnr used in the original request. -

-

- During the readout, the device sends partial results back to the client using the same seqnr as used in the request, using a fields message. - These messages will contain a sequence of fields read out of the device. The client is required to filter this list according to original specifications, as the client is not required - to do this filtering for the client. -

-

- When readout is complete, the device will send a done message to the client with the same seqnr as in the original request. Since the sender - of messages in the device at the time of sending might not be aware of if there are more messages to send or not, the device can send this message separately as is shown in the - diagram. If the device however, knows the last message containings fields is the last, it can set a done attribute in the message, to skip this last message. -

-

- Note: There is no guarantee that the device will send a corresponding started and fields element, even through the request was - accepted. The device might loose power during the process and forget the request. The client should always be aware devices may not respond in time, and take appropriate action - accordingly (for instance, implementing a retry mechanism). -

-

- If a failure occurs while performing the readout, a failure message is sent, instead of a corresponding fields message, as is shown in the following diagram. - Apart from notifying the client that a failure to perform the readout, or part thereof, has occurred, it also provides a list of errors that the device encountered while trying. Note that - multiple fields and failure messages can be sent back to the client during the readout. -

-

- -

-

- The device can also reject a readout request. Reasons for rejecting a request may be missing privileges defined by provisioning rules, etc. It's not part of this XEP - to define such rules. A separate XEP (xep-0000-SN-Provisioning) defines an architecture for how such provisioning can be easilly implemented. -

-

- A rejection response is shown in the following diagram. -

-

- -

- -

- The client who wishes to receive momentary values from the sensor, initiates the request using the req request sent to the device. -

- - - - ]]> - - -

- When the device has received and accepted the request, it responds as follows: -

- - - - - ]]> - - -

- When readout is complete, the response is sent as follows: -

- - - - - - - - - - - ]]> - - - - -

- If instead a readout could not be performed, the communication sequence might look as follows: -

- - - - - - - - - - - - - Timeout. - - ]]> - - - -

- If for some reason, the device rejects the readout request, the communication sequence might look as follows: -

- - - - - - - - - ]]> - - - -

- The following example shows a communication sequence when a client reads out all available information from a sensor at a given point in time: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ... - - - - - - - - - - ]]> - - - -

- The following example shows how a client reads a subset of multiple sensors behind a device with a single JID. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - -

- The req element can take field sub elements, with which the client can specify which fields it is interested in. - If not provided, the client is assumed to return all matching fields, regardless of field name. However, the field elements in the - request object can be used as a hint which fields should be returned. -

-

- Note: the device is not required to adhere to the field limits expressed by these field elements. They are considered - a hint the device can use to limit bandwidth. -

-

- The following example shows how a client can read specific fields in a device. -

- - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - - -

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:sn" in response to &xep0030; information requests.

- - - -]]> - - - - - ... - - ... - -]]> - -

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined - in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

- - - -

- As noticed, a concious effort has been made to not shorten element and attribute names. This is to make sure, XML is maintained readable. Packet size is not deemed to be - affected negatively by this for two reasons: -

-
    -
  • For sensors with limited memory, or where package size is important, &exi; is supposed to be used. EXI compresses strings as normalized index values, making the string appear only once in the packet. Therefore, shortening string length doesn't affect packet size much.
    • -
  • If limited memory or package size is not a consideration, readability and ease of implementation is preferred to short messages.
    • -
- - -

- This protocol has avoided the use of enumerations for data types such as units, field names, etc, and instead use strings. The reasons for this are: -

-
    -
  • Enumerations would unneccesarily restrict the use of the protocol to field names and units listed in the protocol.
    • -
  • It would be very difficult to try to create a complete set of field names and units that would suit all applications.
    • -
  • Leaving these values as strings would let developers the liberty to use units as they desire.
    • -
  • If EXI is used for compression, the use of strings will only increase payload slightly, with only one copy of each distrinct value used.
    • -
  • If EXI is not used, this does not affect packet size.
    • -
-

- However, some things need to be taken into account: -

-
    -
  • Since free strings are used, XML validation cannot be used to secure correct names are used.
    • -
  • xep-0000-SN-Interoperability lists recommendations on how field names and units should be used in order to achieve maximum interoperability in SN.
    • -
  • Consumers of sensor data need to include unit conversion algorithms.
    • -
- - -

- Since some applications require real-time feedback (or as real-time as possible), and readout might in certain cases take a long time, the device has the option - to send multiple fields messages during readout. The client is responsible for collecting all such messages until either a done message - is sent, or a corresponding done attribute is available in one of the messages received. Only the device knows how many (if any) messages are sent in - response to a readout request. -

- - -

- There are different types of values that can be reported from a device. The following table lists the various types: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ElementDescription
numeric - Represents a numerical value. Numerical values contain, apart from a numerical number, also an implicit precision (number of decimals) and an - optional unit. All parties in the communication chain should retain the number of decimals used, since this contain information that is important - in the interpretation of a value. For example, 10 °C is different from 10.0 °C, and very different from 10.00 °C. If a sensor delivers the value - 10 °C you can assume it probably lies between 9.5 °C and 10.5 °C. But if a sensor delivers 10.00 °C, it is probably very exact (if calibrated correctly). -
stringRepresents a string value. It contains an arbitrary string value.
booleanRepresents a boolean value that can be either true or false.
dateTimeRepresents a date and optional time value. The value must be encoded using the xs:dateTime data type. This includes date, an optional time and optional time zone information. - If time zone is not available, it is supposed to be undefined.
timeSpanRepresents a time span value. This can be either a time of day value, if nonnegative and less than 24 hours, or a duration value.
enumRepresents an enumeration value. What differs this value from a string value, is that it apart from the enumeration value (which is a string value), - also contains a datatype, which consumers can use to interpret its value. This specification does not assume knowledge of any particular enumeration - data types.
- - -

- There are different types of fields, apart from types of values a field can have. These types are conceptual types, similar to categories. They are not exclusive, - and can be combined. -

-

- If requesting multiple field types in a request, the device must interpret this as a union of the corresponding field types and return at least all field values - that contain at least one of the requested field types. Example: If requesting momentary values and historical values, devices must return both its momentary values - and its historical values. -

-

- But, when a device reports a field having multiple field types, the client should interpret this as the intersection of the corresponding field types, i.e. the corresponding - field has all corresponding field types. Example: A field marked as both a status value and as a historical value is in fact a historical status value. -

-

- The following table lists the different field types specified in this document: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Field TypeDescription
computedA value that is computed instead of measured.
historical*A value stored in memory from a previous time point. The suffix is used to determine period, as shown below.
historicalSecondA value stored at a second shift (milliseconds = 0).
historicalMinuteA value stored at a minute shift (seconds=milliseconds=0). Are also second values.
historicalHourA value stored at a hour shift (minutes=seconds=milliseconds=0). Are also minute and second values.
historicalDayA value stored at a day shift (hours=minutes=seconds=milliseconds=0). Are also hour, minute and second values.
historicalWeekA value stored at a week shift (Monday, hours=minutes=seconds=milliseconds=0). Are also day, hour, minute and second values.
historicalMonthA value stored at a month shift (day=1, hours=minutes=seconds=milliseconds=0). Are also day, hour, minute and second values.
historicalQuarterA value stored at a quarter year shift (Month=Jan, Apr, Jul, Oct, day=1, hours=minutes=seconds=milliseconds=0). Are also month, day, hour, minute and second values.
historicalYearA value stored at a year shift (Month=Jan, day=1, hours=minutes=seconds=milliseconds=0). Are also quarter, month, day, hour, minute and second values.
historicalOtherIf period if historical value is not important in the request or by the device.
identityA value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
momentaryA momentary value represents a value measured at the time of the readout.
peakA maximum or minimum value during a given period.
statusA value displaying status information about something.
-

- There are two field type attributes that can be used in requests to simplify readout: -

- - - - - - - - - - - - - -
Field TypeDescription
allReads all types of fields. It is the same as explicitly setting all field type attributes to true.
historicalIf period of historical values is not important, this attribute can be set to include all types of historical values.
-

- Note: The reason for including different time periods for historical values, is that these periods are common in metering - applications. However, the client is not restricted to these in any way. The client can always just ask for historical values, and do - filtering as necessary to read out the interval desired. -

-

- Also, clients are not required to include logic to parse and figure out what historical values are actually desired by the client. If too - complicated for the device to handle, it is free to report all historical values. However, the device should limit the historical values - to any interval requested, and should try to limit itself to the field types requested. Information in the request element are seen as hints - that the device can use to optimize any communication required by the operation. -

- - -

- In metering applications where quality of service is important, a field must always be accompanied with a corresponding status flag. Devices should - set these accordingly. If no status flag is set on a field, the client can assume automaticReadout is true. -

-

- Note that status flags are not exclusive. Many of then can logically be combined. Some also imply an order of importance. This should be kept in mind - when trying to overwrite existing values with read values: An estimate should not overwrite a readout, a readout not a signed value, and a signed value - not an invoiced value, etc. -

-

- Available status flags, in order of importance: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Status FlagDescription
missingValue is missing
automaticEstimateAn estimate of the value has been done automatically. Considered more reliable than a missing value (duh!).
manualEstimateThe value has manually been estimated. Considered more reliable than an automatic estimate.
manualReadoutValue has been manually read. Considered more reliable than a manual estimate.
automaticReadoutValue has been automatically read. Considered more reliable than a manually read value.
timeOffsetThe time was offset more than alowed and corrected during the measurement period.
warningA warning was logged during the measurement period.
errorAn error was logged during the measurement period.
signedThe value has been signed by an operator. Considered more reliable than an automatically read value. Note that the signed status flag can be used to overwrite - existing values of higher importance. Example signed+invoiced can be considered more reliable than only invoiced, etc.
invoicedThe value has been invoiced by an operator. Considered more reliable than a signed value.
endOfSeriesThe value has been marked as an end point in a series. This can be used for instance to mark the change of tenant in an apartment.
powerFailureThe device recorded a power failure during the measurement period.
invoiceConfirmedThe value has been invoiced by an operator and confirmed by the recipient. Considered more reliable than an invoiced value.
- - -

- This document does not go into detail on how devices are ordered behind a JID. Some of the examples have assumed a single device lies behind a JID, others - that multiple devices exist behind a JID. Also, no order or structure of devices have been assumed. -

-

- But it can be mentioned that it is assumed that if a client requests a readout of a supernode, it implies the readout of all its subnodes. Therefore, the - client cannot expect readout to be limited to the devices listed explicitly in a request, as nodes implicitly implied, as descendant nodes of the selected nodes, - can also be included. -

-

- More information about how multiple devices behind a JID can be handled, is described in the XEP xep-0000-SN-Concentrators. -

- - - - -

- All time points and dateTime values use the XML data type xs:dateTime to specify values. These values invlude a date, an optional time and an optional time zone. -

-

- Note: If time zone is not available, it is supposed to be undefined. -

-

- If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timepoints from different time zones will be impossible. -

- - -

- This specification allows for localization of field names in meter data readout. This is performed by assigning each localizable string a String ID - which should be uniqe within a given Language Module. A Language Module can be any string, including URI's or namespace names. - The XEP xep-0000-SN-Interoperability details how such localizations can be made in an interoperable way. -

-

- Note: Localization of strings are for human consumption only. Machines should use the unlocalized strings in program logic. -

-

- The following example shows how a device can report localized field information, that can be presented to end users without systems being preprogrammed - to recognize the device. Language modules can be aggregated by operators after installation, or installed as a pluggable module after the main installation, - if localization is desired. -

- - - - - - - - - - - - - - - - - - - - - ]]> - -

- The above example defines a language module called Watchamacallit. In this language module it defines four strings, with IDs 1-4. A system might store these as follows, - where the system replaces all %N% with a conceptual n:th parameter. (It's up to the system to define these strings, any syntax and how to handle input and output.). In - this example, we will assume %0% means any previous output, and %1% any seed value provided. (See below). -

- - - - - - - - - - - - - - - - - - - - - -
IDString
1Temperature
2%0%, Min
3%0%, Max
4%0%, Mean
-

- So, when the client reads the field name Temperature, Min, it knows its the composition of the string Temperature, and - the string %0%, Min, where it will replace %0% with the output of the previous step, in this case Temperature. - These strings can later be localized to different languages by operators of the system, and values presented when reading the device, can be done in a language - different from the one used by the sensor. -

-

- Note: The XEP xep-0000-SN-Interoperability details how such localizations can be made in an interoperable way. -

-

- The stringIds attribute merits some further explanation. The value of this attribute must match the following regular expression: -

- - ^\d+([|]\w+([.]\w+)*([|][^,]*)?)?(,\d+([|]\w+([.]\w+)*([|][^,]*)?)?)*$ - -

- This basically means, it's of the format: ID_1[|[Module_1][|Seed_1]][...[ID_n[|[Module_n][|Seed_n]]]] -

-

- Where brackets [] mean the contents inside is optional, ID_i is an integer representing the string ID in a language module. Module_i - is optional and allows for specifying a module for ID_i, if different from the module defined in the module attribute. Seed_i - allows for seeding the generation of the localized string with a value. This might come in handy when generating strings like Input 5, where you don't want to - create localized strongs for every input there is. -

-

- Why such a complicated syntax? The reason is the following: Most localized strings, are simple numbers, without the need of specifying modules and seeds. This makes - it very efficient to stora as an attribute instead of having to create subelements for every localized field. It's an exception to the rule, to need multiple steps - or seeds in the generation of localized strings. Therefore, attributes is an efficient means to specify localization. However, in the general case, a single string ID - is not sufficient and multiple steps are required, some seeded. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
stringIdsNew PartsResult
11="Temperature"Temperature
1,22="%0%, Max"Temperature, Max
1,1|MathModule1 in module "MathModule"="sum(%0%)"sum(Temperature)
3||A13="Input %1%"Input A1
4||A1,24="Entrance %1%"Entrance A1, Max
4||A1,5||35="%0%, Floor %1%"Entrance A1, Floor 3
- - - -

- This document has not touched upon security in sensor networks. There are mainly three concerns that implementors of sensor networks need to consider: -

-
    -
  • - Communication should be restricted to friends as long as possible. Approved frienships provide a mechanism of limiting sensor information to authorized and authenticated users. - However, there are cases where multicast messages may want to go outside of recognized friendships. More information about such use cases, see the - XEP xep-0000-SN-Multicast. -
    • -
  • - Sensors may have very limited user interfaces. Even though installation of sensor networks is beyond the scope of this document, a simple installation scheme may include a - single LED on the sensor that lights up for a time after receiving a friendship request. If a user presses a button on the device while the LED is lit, the friendship request - is acknowledged, and communication is authorized. -
    • -
  • - More advanced access rights, privileges, automatic friendship recognition, etc., may be managed by a third party. How to implement more advanced provisioning and detailed - access rights to sensor information is detailed in the XEP xep-0000-SN-Provisioning. -
    • -
- - -

This document requires no interaction with &IANA;.

- - -

REQUIRED.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - -

Thanks to Joachim Lindborg for all valuable feedback.

- - diff --git a/xep-0323.xml b/xep-0323.xml new file mode 100644 index 00000000..1287730c --- /dev/null +++ b/xep-0323.xml @@ -0,0 +1,1430 @@ + + + %ents; +]> + + +
+ Sensor Networks - Sensor Data + This specification provides the common framework for sensor data interchange over XMPP networks. + + This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0030 + + + + NOT_YET_ASSIGNED + + Peter + Waher + peter.waher@clayster.com + peter.waher@jabber.org + http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + + 0.0.5 + 2013-04-01 + pwa + +

Added resource information of original called to their corresponding JIDs.

+

Changed the return type of a rejected message.

+

Made images inline.

+

Converted the glossary into a definition list.

+ + + + 0.0.4 + 2013-03-18 + pwa + +

Added information about how to read sensors from large subsystems.

+

Added support for client/device provisioning tokens.

+ + + + 0.0.3 + 2013-03-11 + pwa + +

Changed time point to timestamp everywhere.

+

Corrected some errors in the text.

+

Made the accepted response optional.

+ + + + 0.0.2 + 2013-03-09 + pwa + +

Corrected some errors in XML examples.

+

English corrected.

+

Added errors elements to the rejected element.

+

Added cancel command with corresponding cancelled response.

+ + + + 0.0.1 + 2013-03-07 + pwa + +

First draft.

+ + +
+ +

+ This XEP provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. It includes a hardware abstraction model, removing any + technical detail implemented in underlying technologies. +

+

+ Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). + Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily with millions of devices in peer-to-peer networks. +

+

+ Sensor networks contains many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
XEPDescription
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled, based on &xep0004;
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
exiDefines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered + in all sensor network implementations where memory and packet size is an issue.
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
sensor-network-provisioningDefines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
sensor-dataThis specification. Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. + It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs.
+ + +

The following table lists common terms and corresponding descriptions.

+
+ +
Actuator
+
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
+ + +
Computed Value
+
A value that is computed instead of measured.
+ + +
Concentrator
+
Device managing a set of devices which it publishes on the XMPP network.
+ + +
Field
+
One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. + Fields should be unique within the triple (Node ID, Field Name, Timestamp).
+ + +
Field Name
+
Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
+ + +
Field Type
+
What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
+ + +
Historical Value
+
A value stored in memory from a previous timestamp.
+ + +
Identification Value
+
A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
+ + +
Localization information
+
Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.
+ + +
Meter
+
A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
+ + +
Momentary Value
+
A momentary value represents a value measured at the time of the read-out.
+ + +
Node
+
Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gatewats, etc., are often depicted as nodes and links between sensors (friendships) + are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). + Each Node has a Node ID.
+ + +
Node ID
+
An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted + ID scheme.
+ + +
Parameter
+
Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters + on nodes/devices. Fields are not parameters, and parameters are not fields.
+ + +
Peak Value
+
A maximum or minimum value during a given period.
+ + +
Precision
+
In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision + determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and + delivering field information in sensor networks should always retain the number of decimals in a message.
+ + +
Sensor
+
Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. + Sensor values are reported as fields during read-out. Each sensor has a unique Node ID.
+ + +
SN
+
Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
+ + +
Status Value
+
A value displaying status information about something.
+ + +
Timestamp
+
Timestamp of value, when the value was sampled or recorded.
+ + +
Token
+
+ A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate + access rights with the provisioning server. +
+ + +
Unit
+
Physical unit of value. Example: MWh, l/s, etc.
+ + +
Value
+
A field value.
+ + +
Value Status
+
Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
+ + +
Value Type
+
Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
+ + +
WSN
+
Wireless Sensor Network, a sensor network including wireless devices.
+ + +
XMPP Client
+
Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.
+ +
+ + +

+ The most common use case for a sensor network application is meter read-out. It's performed using a request and response mechanism, as is shown in the following diagram. +

+

+ +

+

+ The read-out request is started by the client sending a req request to the device. Here, the client selects a sequence number seqnr. + It should be unique among requests made by the client. The device will use this sequence numbers in all messages sent back to the client. +

+

+ The request also contains a set of field types that very roughly determine what the client wants to read. What the client actually will return will be determined by + a lot of other factors, such as make and model of device, any provisioning rules provided, etc. This parameter just gives a hint on what kind of data is desired. It is implicit in the request + by the context what kind of data is requested. Examples of field types are: Momentary values, peak values, historical values, computed values, status values, identification values, etc. +

+

+ If reading historical values, the client can also specify an optional time range using the from and to parameter values, giving the device a hint on + how much data to return. +

+

+ If the client wants the read-out to be performed at a given point in time, the client can define this using the optional parameter when. +

+

+ There's an optional parameter ids that the client can provide, listing a set of Node IDs. If omitted, the request includes all sensors or devices + managed by the current JID. But, if the JID is controlled by a system, device or concentrator managing various devices, the ids parameter restricts the read-out to + specific individuals. +

+

+ Note: The device is not required to follow the hints given by the client. These are suggestions the client can use to minimize its effort to perform the read-out. + The client MUST make sure the response is filtered according to original requirements by the client after the read-out response has been received. +

+

+ If the device accepts the client request, it sends an accepted response back to the client. The device also has to determine if the read-out is commenced directly, + or if it is to be queued for later processing. Note that the request can be queued for several reasons. The device can be busy, and queues it until it is ready to process the request. + It can also queue the request if the client has requested it to be executed at a given time. If the request is queued, the device informs the client of this using the queued + attribute. Note however, that the device will process the request when it can. There's no guarantee that the device will be able to process the request exactly when the client requests it. +

+

+ Note: The accepted message can be omitted if the device already has the response and is ready to send it. If the client receives field data or a + done message before receiving an accepted message, the client can assume the device accepted the request and omitted sending an accepted + element. +

+

+ If the request was queued, the device will send a message informing the client when the read-out is begun. This is done using a started message, using the same + seqnr used in the original request. +

+

+ Note: Sending a started element should be omitted by the device if the request is not queued on the device. If the queued attribute + is omitted in the response, or has the value false, the client must not assume the device will send a started element. +

+

+ During the read-out, the device sends partial results back to the client using the same seqnr as used in the request, using a fields message. + These messages will contain a sequence of fields read out of the device. The client is required to filter this list according to original specifications, as the device is not required + to do this filtering for the client. +

+

+ When read-out is complete, the device will send a done message to the client with the same seqnr as in the original request. Since the sender + of messages in the device at the time of sending might not be aware of if there are more messages to send or not, the device can send this message separately as is shown in the + diagram. If the device however, knows the last message containing fields is the last, it can set a done attribute in the message, to skip this last message. +

+

+ Note: There is no guarantee that the device will send a corresponding started and fields element, even though the request was + accepted. The device might lose power during the process and forget the request. The client should always be aware of that devices may not respond in time, and take appropriate action + accordingly (for instance, implementing a retry mechanism). +

+

+ If a failure occurs while performing the read-out, a failure message is sent, instead of a corresponding fields message, as is shown in the following diagram. + Apart from notifying the client that a failure to perform the read-out, or part thereof, has occurred, it also provides a list of errors that the device encountered while trying. Note that + multiple fields and failure messages can be sent back to the client during the read-out. +

+

+ +

+

+ The device can also reject a read-out request. Reasons for rejecting a request may be missing privileges defined by provisioning rules, etc. It's not part of this XEP + to define such rules. A separate XEP (sensor-network-provisioning) defines an architecture for how such provisioning can be easily implemented. +

+

+ A rejection response is shown in the following diagram. +

+

+ +

+

+ If a read-out has been queued, the client can cancel the queued read-out request sending a cancel command to the device. If a reading has begin and the client + sends a cancel command to the device, the device can choose if the read-out should be cancelled or completed. +

+

+ Note: Remember that the seqnr value used in this command is unique only to the client making the request. The device can receive requests + from multiple clients, and must make sure it differs between seqnr values from different clients. Different clients are assumed to have different values + in the corresponding from attributes. +

+

+ +

+ +

+ The client that wishes to receive momentary values from the sensor initiates the request using the req request sent to the device. +

+ + + + ]]> + + +

+ When the device has received and accepted the request, it responds as follows: +

+ + + + + ]]> + + +

+ When read-out is complete, the response is sent as follows: +

+ + + + + + + + + + + ]]> + + + + +

+ If instead a read-out could not be performed, the communication sequence might look as follows: +

+ + + + + + + + + + + + + Timeout. + + ]]> + + + +

+ If for some reason, the device rejects the read-out request, the communication sequence might look as follows: +

+ + + + + + + + + Access denied. + + ]]> + +

+ Note that the type of the returning IQ stanza is error. +

+ + +

+ The following example shows a communication sequence when a client reads out all available information from a sensor at a given point in time: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + + + + + + + + ]]> + + + +

+ The following example shows how a client reads a subset of multiple sensors behind a device with a single JID. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ The req element can take field sub elements, with which the client can specify which fields it is interested in. + If not provided, the client is assumed to return all matching fields, regardless of field name. However, the field elements in the + request object can be used as a hint which fields should be returned. +

+

+ Note: the device is not required to adhere to the field limits expressed by these field elements. They are considered + a hint the device can use to limit bandwidth. +

+

+ The following example shows how a client can read specific fields in a device. +

+ + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ The following example shows how the client cancels a scheduled read-out: +

+ + + + + + + + + + + + + + + + ]]> + + + + +

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:sn" in response to &xep0030; information requests.

+ + + +]]> + + + + + ... + + ... + +]]> + +

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined + in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

+ + + +

+ As noticed, a conscious effort has been made not to shorten element and attribute names. This is to make sure, XML is maintained readable. Packet size is not deemed to be + affected negatively by this for two reasons: +

+
    +
  • For sensors with limited memory, or where package size is important, EXI + Efficient XML Interchange (EXI) Format <http://www.w3.org/TR/exi/>. is supposed to be used. + EXI compresses strings as normalized index values, making the string appear only once in the packet. Therefore, shortening string length doesn't affect packet + size much. Element and attribute names in known namespaces are furthermore only encoded by index in schema, not by name.
    • +
  • If limited memory or package size is not a consideration, readability and ease of implementation is preferred to short messages.
    • +
+ + +

+ This protocol has avoided the use of enumerations for data types such as units, field names, etc., and instead use strings. The reasons for this are: +

+
    +
  • Enumerations would unnecessarily restrict the use of the protocol to field names and units listed in the protocol.
    • +
  • It would be very difficult to try to create a complete set of field names and units that would suit all applications.
    • +
  • Leaving these values as strings would let developers the liberty to use units as they desire.
    • +
  • If EXI is used for compression, the use of strings will only increase payload slightly, with only one copy of each distinct value used.
    • +
  • If EXI is not used, this does not affect packet size.
    • +
+

+ However, some things need to be taken into account: +

+
    +
  • Since free strings are used, XML validation cannot be used to secure correct names are used.
    • +
  • xep-0000-SN-Interoperability lists recommendations on how field names and units should be used in order to achieve maximum interoperability in SN.
    • +
  • Consumers of sensor data need to include unit conversion algorithms.
    • +
+ + +

+ Since some applications require real-time feedback (or as real-time as possible), and read-out might in certain cases take a long time, the device has the option + to send multiple fields messages during read-out. The client is responsible for collecting all such messages until either a done message + is sent, or a corresponding done attribute is available in one of the messages received. Only the device knows how many (if any) messages are sent in + response to a read-out request. +

+ + +

+ There are different types of values that can be reported from a device. The following table lists the various types: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ElementDescription
numeric + Represents a numerical value. Numerical values contain, apart from a numerical number, also an implicit precision (number of decimals) and an + optional unit. All parties in the communication chain should retain the number of decimals used, since this contains information that is important + in the interpretation of a value. For example, 10 °C is different from 10.0 °C, and very different from 10.00 °C. If a sensor delivers the value + 10 °C you can assume it probably lies between 9.5 °C and 10.5 °C. But if a sensor delivers 10.00 °C, it is probably very exact (if calibrated correctly). +
stringRepresents a string value. It contains an arbitrary string value.
booleanRepresents a boolean value that can be either true or false.
dateTimeRepresents a date and optional time value. The value must be encoded using the xs:dateTime data type. This includes date, an optional time and optional time zone information. + If time zone is not available, it is supposed to be undefined.
timeSpanRepresents a time span value. This can be either a time of day value, if nonnegative and less than 24 hours, or a duration value.
enumRepresents an enumeration value. What differs this value from a string value, is that it apart from the enumeration value (which is a string value), + also contains a data type, which consumers can use to interpret its value. This specification does not assume knowledge of any particular enumeration + data types.
+ + +

+ There are different types of fields, apart from types of values a field can have. These types are conceptual types, similar to categories. They are not exclusive, + and can be combined. +

+

+ If requesting multiple field types in a request, the device must interpret this as a union of the corresponding field types and return at least all field values + that contain at least one of the requested field types. Example: If requesting momentary values and historical values, devices must return both its momentary values + and its historical values. +

+

+ But, when a device reports a field having multiple field types, the client should interpret this as the intersection of the corresponding field types, i.e. the corresponding + field has all corresponding field types. Example: A field marked as both a status value and as a historical value is in fact a historical status value. +

+

+ The following table lists the different field types specified in this document: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Field TypeDescription
computedA value that is computed instead of measured.
historical*A value stored in memory from a previous timestamp. The suffix is used to determine period, as shown below.
historicalSecondA value stored at a second shift (milliseconds = 0).
historicalMinuteA value stored at a minute shift (seconds=milliseconds=0). Are also second values.
historicalHourA value stored at a hour shift (minutes=seconds=milliseconds=0). Are also minute and second values.
historicalDayA value stored at a day shift (hours=minutes=seconds=milliseconds=0). Are also hour, minute and second values.
historicalWeekA value stored at a week shift (Monday, hours=minutes=seconds=milliseconds=0). Are also day, hour, minute and second values.
historicalMonthA value stored at a month shift (day=1, hours=minutes=seconds=milliseconds=0). Are also day, hour, minute and second values.
historicalQuarterA value stored at a quarter year shift (Month=Jan, Apr, Jul, Oct, day=1, hours=minutes=seconds=milliseconds=0). Are also month, day, hour, minute and second values.
historicalYearA value stored at a year shift (Month=Jan, day=1, hours=minutes=seconds=milliseconds=0). Are also quarter, month, day, hour, minute and second values.
historicalOtherIf period if historical value is not important in the request or by the device.
identityA value that can be used for identification. (Serial numbers, meter IDs, locations, names, addresses, etc.)
momentaryA momentary value represents a value measured at the time of the read-out. Examples: Energy, Volume, Power, Flow, Temperature, Pressure, etc.
peakA maximum or minimum value during a given period. Examples "Temperature, Max", "Temperature, Min", etc.
statusA value displaying status information about something. Examples: Health, Battery life time, Runtime, Expected life time, Signal strength, Signal quality, etc.
+

+ There are two field type attributes that can be used in requests to simplify read-out: +

+ + + + + + + + + + + + + +
Field TypeDescription
allReads all types of fields. It is the same as explicitly setting all field type attributes to true.
historicalIf period of historical values is not important, this attribute can be set to include all types of historical values.
+

+ Note: The reason for including different time periods for historical values is that these periods are common in metering + applications. However, the client is not restricted to these in any way. The client can always just ask for historical values, and do + filtering as necessary to read out the interval desired. +

+

+ Also, devices are not required to include logic to parse and figure out what historical values are actually desired by the client. If too + complicated for the device to handle, it is free to report all historical values. However, the device should limit the historical values + to any interval requested, and should try to limit itself to the field types requested. Information in the request element are seen as hints + that the device can use to optimize any communication required by the operation. +

+ + +

+ In metering applications where quality of service is important, a field must always be accompanied with a corresponding status flag. Devices should + set these accordingly. If no status flag is set on a field, the client can assume automaticReadout is true. +

+

+ Note that status flags are not exclusive. Many of them can logically be combined. Some also imply an order of importance. This should be kept in mind + when trying to overwrite existing values with read values: An estimate should not overwrite a read-out, a read-out not a signed value, and a signed value + not an invoiced value, etc. +

+

+ Available status flags, in order of importance: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Status FlagDescription
missingValue is missing
automaticEstimateAn estimate of the value has been done automatically. Considered more reliable than a missing value (duh!).
manualEstimateThe value has manually been estimated. Considered more reliable than an automatic estimate.
manualReadoutValue has been manually read. Considered more reliable than a manual estimate.
automaticReadoutValue has been automatically read. Considered more reliable than a manually read value.
timeOffsetThe time was offset more than allowed and corrected during the measurement period.
warningA warning was logged during the measurement period.
errorAn error was logged during the measurement period.
signedThe value has been signed by an operator. Considered more reliable than an automatically read value. Note that the signed status flag can be used to overwrite + existing values of higher importance. Example signed + invoiced can be considered more reliable than only invoiced, etc.
invoicedThe value has been invoiced by an operator. Considered more reliable than a signed value.
endOfSeriesThe value has been marked as an end point in a series. This can be used for instance to mark the change of tenant in an apartment.
powerFailureThe device recorded a power failure during the measurement period.
invoiceConfirmedThe value has been invoiced by an operator and confirmed by the recipient. Considered more reliable than an invoiced value.
+ + +

+ This document does not go into detail on how devices are ordered behind a JID. Some of the examples have assumed a single device lies behind a JID, others + that multiple devices exist behind a JID. Also, no order or structure of devices has been assumed. +

+

+ But it can be mentioned that it is assumed that if a client requests a read-out of a supernode, it implies the read-out of all its subnodes. Therefore, the + client cannot expect read-out to be limited to the devices listed explicitly in a request, as nodes implicitly implied, as descendant nodes of the selected nodes, + can also be included. +

+

+ More information about how multiple devices behind a JID can be handled, is described in the XEP xep-0000-SN-Concentrators. +

+ + +

+ All examples in this document have been simplified examples where a few devices containing a few fields have been read. However, in many cases large subsystems with + very many sensors containing many fields have to be read, as is documented in xep-0000-SN-Concentrators.html + + xep-0000-SN-Concentrators.html + . In such cases, a node may have to be specified using two or perhaps + even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to + a specific kind of node, and the common nodeId. For more information about this, see xep-0000-SN-Concentrators.html. +

+

+ Note: For cases where the nodeId is sufficient to uniquelly identify the node, it is sufficient to provide this attribute in the request. + If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested. +

+ + + + +

+ All timestamps and dateTime values use the XML data type xs:dateTime to specify values. These values include a date, an optional time and an optional time zone. +

+

+ Note: If time zone is not available, it is supposed to be undefined. The client reading the sensor that reports fields without time zone information + should assume the sensor has the same time zone as the client, if not explicitly configured otherwise on the client side. +

+

+ If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible. +

+ + +

+ This specification allows for localization of field names in meter data read-out. This is performed by assigning each localizable string a String ID + which should be unique within a given Language Module. A Language Module can be any string, including URI's or namespace names. + The XEP xep-0000-SN-Interoperability details how such localizations can be made in an interoperable way. +

+

+ Note: Localization of strings are for human consumption only. Machines should use the unlocalized strings in program logic. +

+

+ The following example shows how a device can report localized field information that can be presented to end users without systems being preprogrammed + to recognize the device. Language modules can be aggregated by operators after installation, or installed as a pluggable module after the main installation, + if localization is desired. +

+ + + + + + + + + + + + + + + + + + + + + ]]> + +

+ The above example defines a language module called Watchamacallit. In this language module it defines four strings, with IDs 1-4. A system might store these as follows, + where the system replaces all %N% with a conceptual n:th parameter. (It's up to the system to define these strings, any syntax and how to handle input and output.). In + this example, we will assume %0% means any previous output, and %1% any seed value provided. (See below). +

+ + + + + + + + + + + + + + + + + + + + + +
IDString
1Temperature
2%0%, Min
3%0%, Max
4%0%, Mean
+

+ So, when the client reads the field name Temperature, Min, it knows that the field name is the composition of the string Temperature, and + the string %0%, Min, where it will replace %0% with the output of the previous step, in this case Temperature. + These strings can later be localized to different languages by operators of the system, and values presented when reading the device, can be done in a language + different from the one used by the sensor. +

+

+ Note: The XEP xep-0000-SN-Interoperability details how such localizations can be made in an interoperable way. +

+

+ The stringIds attribute merits some further explanation. The value of this attribute must match the following regular expression: +

+ + ^\d+([|]\w+([.]\w+)*([|][^,]*)?)?(,\d+([|]\w+([.]\w+)*([|][^,]*)?)?)*$ + +

+ This basically means, it's of the format: ID_1[|[Module_1][|Seed_1]][...[ID_n[|[Module_n][|Seed_n]]]] +

+

+ Where brackets [] mean the contents inside is optional, ID_i is an integer representing the string ID in a language module. Module_i + is optional and allows for specifying a module for ID_i, if different from the module defined in the module attribute. Seed_i + allows for seeding the generation of the localized string with a value. This might come in handy when generating strings like Input 5, where you don't want to + create localized strings for every input there is. +

+

+ Why such a complicated syntax? The reason is the following: Most localized strings are simple numbers, without the need of specifying modules and seeds. This makes + it very efficient to store it as an attribute instead of having to create subelements for every localized field. It's an exception to the rule, to need multiple steps + or seeds in the generation of localized strings. Therefore, attributes is an efficient means to specify localization. However, in the general case, a single string ID + is not sufficient and multiple steps are required, some seeded. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
stringIdsNew PartsResult
11="Temperature"Temperature
1,22="%0%, Max"Temperature, Max
1,1|MathModule1 in module "MathModule"="sum(%0%)"sum(Temperature)
3||A13="Input %1%"Input A1
4||A1,24="Entrance %1%"Entrance A1, Max
4||A1,5||35="%0%, Floor %1%"Entrance A1, Floor 3
+ + + +

+ This document has not touched upon security in sensor networks. There are mainly three concerns that implementers of sensor networks need to consider: +

+
    +
  • + Communication should be restricted to friends as long as possible. Approved friendships provide a mechanism of limiting sensor information to authorized and authenticated users. + However, there are cases where multicast messages may want to go outside of recognized friendships. More information about such use cases, see the + XEP xep-0000-SN-Multicast. +
    • +
  • + Sensors may have very limited user interfaces. Even though installation of sensor networks is beyond the scope of this document, a simple installation scheme may include a + single LED on the sensor that lights up for a time after receiving a friendship request. If a user presses a button on the device while the LED is lit, the friendship request + is acknowledged, and communication is authorized. +
    • +
  • + More advanced access rights, privileges, automatic friendship recognition, etc., may be managed by a third party. How to implement more advanced provisioning and detailed + access rights to sensor information is detailed in the XEP sensor-network-provisioning. In short, a device, service or user can get a + deviceToken, serviceToken and userToken respectivelly from a provisioning server. The service or device then uses these tokens + in all readout requests and the device being read out can in turn use these tokens to validate access rights with the provisioning server. +
    • +
+ + +

This document requires no interaction with &IANA;.

+ + +

REQUIRED.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + +

Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman, Kevin Smith and Tobias Markmann for all valuable feedback.

+ + \ No newline at end of file From dccead28949fd6c45c9cd0a8529120743632e27e Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:46:58 -0600 Subject: [PATCH 06/12] accepted for publication --- inbox/sensor-network-provisioning.xml | 1383 -------------------- xep-0324.xml | 1672 +++++++++++++++++++++++++ 2 files changed, 1672 insertions(+), 1383 deletions(-) delete mode 100644 inbox/sensor-network-provisioning.xml create mode 100644 xep-0324.xml diff --git a/inbox/sensor-network-provisioning.xml b/inbox/sensor-network-provisioning.xml deleted file mode 100644 index 023cdfb6..00000000 --- a/inbox/sensor-network-provisioning.xml +++ /dev/null @@ -1,1383 +0,0 @@ - - -%ents; -]> - - -
- XEP - Sensor Networks - Provisioning - This specification describes an architecture for efficient provisioning of services, access rights and user privileges in sensor networks. - - This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - - xxxx - ProtoXEP - Standards Track - Standards - Council - - XMPP Core - XEP-0001 - XEP-0030 - xep-0000-SN-SensorData - - - - NOT_YET_ASSIGNED - - Peter - Waher - peter.waher@clayster.com - peter.waher@jabber.org - http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ - - - 0.0.3 - 2013-03-18 - pwa - -

Added information about how to read sensors from large subsystems.

-

Added friend recommendation message.

-

Added client/device/service tokens.

- - - - 0.0.2 - 2013-03-12 - pwa - -

Added use cases for service access rights and corresponding user privileges.

- - - - 0.0.1 - 2013-03-11 - pwa - -

First draft.

- - -
- -

- This XEP provides the underlying architecture, basic operations and data structures for provisioning of services, access rights and user privileges in sensor networks. -

-

- Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). - Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily containing millions of devices in peer-to-peer networks. -

-

- An added complexity in the provisioning case is that sensors often have very limited user interface options. Therefore, this document explains how provisioning can be done - efficiently using a trusted third party with more power and options when it comes to user interface design and storage. -

-

- This XEP relies heavily on xep-0000-SN-SensorData xep-0000-SN-SensorData. - Sensor networks contain many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
XEPDescription
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
XEP-0000-Exi - Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered - in all sensor network implementations where memory and packet size is an issue. -
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
xep-0000-SN-ProvisioningThis specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
xep-0000-SN-SensorData - Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. - It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs. -
- - -

The following table lists common terms and corresponding descriptions.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TermDescription
ActuatorDevice containing at least one configurable property or output that can and should be controlled by some other entity or device.
Computed ValueA value that is computed instead of measured.
ConcentratorDevice managing a set of devices which it publishes on the XMPP network.
Field - One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. - Fields should be unique within the triple (Node ID, Field Name, Timestamp). -
Field NameName of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
Field TypeWhat type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
Historical ValueA value stored in memory from a previous timestamp.
Identification ValueA value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
Localization informationOptional information for a field, allowing the sensor to control how the information should be presented to human viewers.
MeterA device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
Momentary ValueA momentary value represents a value measured at the time of the read-out.
Node - Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gateways, etc., are often depicted as nodes and links between sensors (friendships) - are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). - Each Node has a Node ID. -
Node ID - An ID uniquely identifying a node within its corresponding context. If a globally unique ID is desired, an architecture should be used using a universally accepted - ID scheme. -
Parameter - Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters - on nodes/devices. Fields are not parameters, and parameters are not fields. -
Peak ValueA maximum or minimum value during a given period.
Precision - In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision - determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and - delivering field information in sensor networks should always retain the number of decimals in a message. -
Sensor - Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. - Sensor values are reported as fields during read-out. Each sensor has a unique Node ID. -
SNSensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
Status ValueA value displaying status information about something.
TimestampTimestamp of value, when the value was sampled or recorded.
Token - A client, device or user can get a token from a provisioning server. These tokens can be included in requests to other entities in the network, so these entities can validate - access rights with the provisioning server. -
UnitPhysical unit of value. Example: MWh, l/s, etc.
ValueA field value.
Value StatusStatus of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
Value TypeCan be numeric, string, boolean, Date & Time, Time Span or Enumeration.
WSNWireless Sensor Network, a sensor network including wireless devices.
XMPP ClientApplication connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.
- - -

- The most basic use case in sensor networks is to read out sensor data from a sensor. However, since protecting end-user integrity and system security is vital, access - rights and user privileges have to be imposed on the network. -

-

- To store access rights in all sensors might be very impractical. Not only does it consume memory, it's difficult to maintain track of the current system status, make sure - all devices have the latest configuration, distribute changes to the configuration, etc. -

-

- Furthermore, most sensors and small devices have very limited possibility to provide a rich user interface. Perhaps all it can do is to provide a small LED and a button, - useful perhaps for installing the sensor in the network, but not much more. -

-

- As an added complexity, the sensor network operator might not even have access to the XMPP Servers used, and provisioning needs to lie outside of the XMPP Server domains. -

-

- To solve this problem in an efficient manner, an architecture using distributed trusted third parties is proposed. Such third parties would: -

-
    -
  • Provide a rich user interface and configurable options to end user or back end systems.
    • -
  • Control friendships (who can communicate with whom).
    • -
  • Control content available for different friends (what can be read by whom).
    • -
  • Control operations accessible by different friends (what can be controlled/configured by whom).
    • -
  • Provide additional interoperability services to nodes in the network (for instance, unit conversion).
    • -
- -

- Trust is delegated to a provisioning server by a device, simply by befriending the provisioning server and asking it questions and complying with - its answers. -

-

- As an illustrative example, following is a short description of how such a trust relationship can be created in a scenario where the sensor only - has a single LED and a single button. -

-
    -
  • Somebody is installing the sensor, giving it a connection to an XMPP server and a JID, reachable from the provisioning server.
    • -
  • The provisioning server is told to create a friendship request to the new sensor.
    • -
  • The sensor flashes its LED for a given time (for example: 30 seconds).
    • -
  • Viewing the LED, the person installing the sensor presses the button.
    • -
  • Receiving the button press within the given time period, accepts the friendship request. Optionally, the device can give user feedback using the LED.
    • -
  • The device performs a service discovery of the new friend, having been a manually added friend.
    • -
  • If the new friend supports this provisioning extension, further responsibilities are delegated to this device.
    • -
  • As the last step the device asks the provisioning server for a token. This device token is later used in calls to other devices and can be used to check access rights.
    • -
-

- The following diagram shows the general case: -

-

- -

-

- The successful case can also be illustrated in a sequence diagram, as follows: -

-

- -

-

- The following example shows how a device can request a device token from the provisioning server: -

- - - - - - - - ]]> - -

- The provisioning server must not return tokens that contain white space characters. -

-

- Note: In many cases, an address to a provisioning server might be preprogrammed during production of the - device. In these cases, parts of the above procedure may not neccessary. All the client needs to do, if the provisioning server is not available - in the roster of the device, is to send a subscription request to the provisioning server, to alert the server of the existence of the device, - and possibly request a device token. -

-

- The following use cases will assume such a trust relationship has been created between the corresponding device and the provisioning server. -

- - -

- The following diagram displays how a friendship request from an external party can be handled, delegating the responsibility to a trusted third party: -

-

- -

-

- The communication between the XMPP Device and the Provisioning Server could be as follows: -

- - - - - - - - ]]> - -

- Note: The provisioning server implicitly understands which two JIDs that are to be checked: The first one is the sender of the message, the second one - is the JID available in the jid attribute in the request. -

-

- Note 2: Any resource information in the JID must be ignored by the provisioning server. -

- - -

- The following diagram displays a friendship request from an external party being rejected as a result of the trusted third party negating the friendship: -

-

- -

-

- The communication between the XMPP Device and the Provisioning Server could be as follows: -

- - - - - - - - ]]> - - - -

- If the provisioning server decides that two friends in the network should no longer be friends and communicate with each other, it simply sends a message to - at least one of the friends as follows: -

-

- -

-

- The provisioning server should only send such messages to clients that have previously asked the provisioning server if friendship requests should be accepted or not. -

-

- Note: The device should only honor such messages, if the sender is the trusted third party. Such messages received from other entities not trusted should - be silently ignored. -

- - - - - ]]> - - - -

- The provisioning server can, apart from accepting new friendships and rejecting old friendships, also recommend new friendships. In this case, the provisioning server - simply sends a message to one or both of the soon to be friends, as follows: -

-

- -

- - - - ]]> - -

- Note that the receptor can still ask the provisioning server if it can form a friendship with the suggested friend, using the isFriend command. -

- - -

- An important use case for provisioning in sensor networks is who gets to read out sensor data from which sensors. This use case details how communication with a - provisioning server can help the device determine if a client has sufficient access rights to read the values of the device. -

-

- -

-

- Note: This use case is an extension of the use case 'Read-out rejected' in the XEP xep-0000-SN-SensorData. -

-

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: -

- - - - - - - - - - - - - - - - Access denied. - - ]]> - -

- Note that the provisioning server responds with a canReadResponse element, with the same content as the canRead element in the request. -

- - -

- In case the device handles multiple nodes that can be read, the provisioning server has the possibility to grant read-out, but to limit the nodes that can be read out. - The provisioning server does this by returning the list of nodes that can be read. -

-

- -

-

- Note: This use case is an extension of the use case 'Read-out of multiple devices' in the XEP xep-0000-SN-SensorData. -

-

- Note 2: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed - to be read. If no nodes in the request are allowed to be read, the provisioning server must respond with a result='false', so the device can reject the read-out request. -

-

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: -

- - - - - - - - - - - - - - - - - - - - - - - - - ]]> - -

- Note that the provisioning server responds with a canReadResponse element, similar to the canRead element in the request, except - only the nodes allowed to be read are read. The device must only permit read-out of nodes listed in the response from the provisioning server. Other nodes available - in the request should be ignored. -

- - -

- In case the provisioning server wants to limit the fields a device can send to a client, the provisioning server has the possibility to grant read-out, but - list a set of fields the device is allowed to send to the corresponding client. -

-

- -

-

- Note: If the server responds, but without specifying a list of field names, the device can assume that all fields available in the original request are allowed - to be sent. If no fields in the request are allowed to be sent, the provisioning server must respond with a result='false', so the device can reject the read-out request. -

-

- The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: -

- - - - - - - - - - - - - - - - - - - - ]]> - -

- Note that the provisioning server responds with a canReadResponse element, similar to the canRead element in the request, except only - the fields allowed to be sent are listed. The client must only send fields having field names in this list. -

-

- Also note, that the provisioning server can return both lists of allowed nodes and allowed field names in the response. In this case, the device must only send allowed fields - from allowed nodes, and ignore all other fields and/or nodes. -

- - -

- When the provisioning server updates access rights and user privileges in the system, it will send a clearCache command to corresponding devices. - If a device was offline during the change, the provisioning server must send the clearCache message when the device comes online again. To acknowledge - the receipt of the command, the client responds with a clearCacheResponse element. This response message does not contain any information on what was - done by the client. It simply acknowledges the receipt of the command, to make sure the provisioning server does not resend the clear cache command again. -

-

- Note: The clearCache command does not include information on what has been changed, so the device needs to clear the entire cache. This - to avoid complexities in making sure updates made to the provisioning rules works in all cases, and to minimize complexity in the implementation of the protocol on the sensor side. - It is also not deemed to decrease network performance, since changing provisioning rules for a device is an exceptional event and therefore does not affect performance during - normal operation. -

- - - - - - - - - ]]> - - - -

- A service requesting provisioning assistance, needs to retrieve a service token from the provisioning server. The following example shows how this can be done. -

- - - - - - - - ]]> - - - -

- Provisioning in sensor networks also requires control of user access to different services in the network. This use case shows how service access rights are controlled using - a trusted provisioning server. -

-

- -

-

- First, the user connects to the service in some way. This can be done using XMPP, HTTP, HTTPS or some other means. The service need to extract some form of identifying - credentials from the user, and provide that to the provisioning server. The provisioning server determines if the client has access rights to the service based on these - credentials, and also provides the service with a userToken that the service can use in further communication with the provisioning server regarding - the user and its privileges. -

-

- The following table lists some different types of credentials that the service can extract from the client: -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
TypeProtocolsDescription
JIDXMPPAllows provisioning to be done on the JID the user has.
IP AddressHTTP, HTTPSAllows provisioning to be done on IP address or IP-ranges for instance.
Host NameHTTP, HTTPS with DNSIf the service has access to the client host name, for instance in an intra network, this can be used for provisioning.
X.509 CertificateHTTPSIf the client provides a client certificate, such a certificate can be used to provide provisioning.
X.509 Certificate ThumbprintHTTPSThe client can also choose to validate the certificate itself and only send the certificate thumbprint to the provisioning server. Even though this - provides somewhat lesser security than providing the entire certificate, it might be an option to distribute certificate validation checks across the network - to lower the work load on the provisioning server.
User NameHTTP, HTTPS, XMPPIf authenticated HTTP(S) access is implemented, the service can provide the user name as credentials. XMPP based clients can use - information in the roster to provide user name information to the provisioning server.
GeolocationHTML5 over HTTP(S), XMPPIf the geographic location (longitude & latitude) of the user client is known, it can be used. HTML 5 provides mechanism whereby the location - of the client can be fetched. &xep0080; provides a mechanism whereby client location can be obtained over XMPP.
SSO TokenIntranetIf a single sign on token is available, such a token could be provided as credentials.
ProtocolAnyConnection protocol used to connect to the service.
-

- The provisioning server receives these credentials, and decides if the user should have access to the service or not, based on rules configured in the provisioning service. - If the user is granted access, a userToken is generated and returned to the service. This token -

-

- Now, the service can determine if this access grant is sufficient or not. It can require the user to login into the service first. If so, the service should provide the provisioning - server with the user name used during login, when logged in. -

- - - - - - - - - - - - - - - - - - - - - - ]]> - - - -

- When a user has been given access to a service, and properly been identified, the service can ask the provisioning service for detailed user privileges to control - different aspects of the service. This can be done using the hasPrivilege command. Here, the service sends its serviceToken and - the userToken earlier received when being granted access to the service. Furthermore a privilegeId has to be provided. -

-

- A Privilege ID is a string composed of one or a sequence of parts, delimited by period characters. The Privilege IDs form a tree of privileges, - using an invisible, but common, root privilege. -

-

- The following table suggests some examples of Privilge IDs, with suggestive descriptions. (Only used as an example.) -

- - - - - - - - - - - - - - - - - -
Privilege IDDescription
Databases.Energy.SelectGives the user the rights to select data from the Energy database.
Databases.Energy.InsertGives the user the rights to insert data into the Energy database.
Databases.Energy.DeleteGives the user the rights to delete data from the Energy database.
-

- Note: Note that privilege IDs are local to the service. Different services are allowed to use similar or same Privilege IDs, in different contexts and - with different meanings. The provisioning server must separate Privilege IDs from different services. -

-

- The client must always provide full Privilege IDs to the provisioning server. The provisioning server however, can grant partial privilege IDs, pointing to parent - privilege nodes to a user or a role object, granting a user a specific role. If granting a parent privilege ID to a user or role, this is interpreted as - giving the corresponding user or role the privileges of the entire sub-tree defined by the parent privilege ID. -

-

- If additional control over privileges is desired, negative privileges can be assigned to the user or role. Granted or explicitly rejected privileges are specified in a - sequential list of full or partial privilege IDs. This list is then processed sequentially to determine if a privilege is granted or not. -

-

- Example: Consider the privileges above. Give a user or its corresponding role the following privileges in a sequential list: -

-
    -
  • Exclude: Databases.Energy.Delete
    • -
  • Include: Databases.Energy
    • -
-

- This would give the user rights to select and insert data, but not to delete data from the Energy database. -

-

- Note: Care should be taken when constructing Privilege IDs, so they do not include variable data that potentially can create an infinite amount of - privilege IDs. For example: Do not include user names, sensor IDs, etc., in privilege IDs, as the number of such entities cannot be estimated or is scalable beforehand. -

-

- The following diagram shows an example of how a service asks permission from a provisioning server before an action is taken: -

-

- -

- - - - - - - - - - - - ]]> - - - -

- To improve performance, services can download the entire set of user privileges, and perform privilege checks internally. The following diagram displays - how the above two use cases could be handled in such a case: -

-

- -

-

- Note: When downloading privileges using this command, a sequential list of full or partial privilege IDs will be returned together with the - corresponding include or exclude flags. The above mentioned algorithm of determining user privileges must be implemented by the service, if this method is - to be used. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - - -

- The isFriendResponse element returned by the provisioning server contains an attribute secondaryTrustAllowed that is by default - set to false. If the provisioning server has no problem with allowing multiple trust to be delegated by devices in the network, it can choose to set this - attribute to true in the response. If true, the device knows it has the right to add its own friends, or to add secondary trust relationships. -

-

- The following diagram continues with the example given above, of how a sensor with a limited user interface, can allow to manually add new friends, including new - trust relationships using a single LED and a button. -

-

- -

- - -

- When multiple trust is used, the entity (client, user, service, etc.) has one token from each provisioning server. However, when sending a token to a third party, - the sender does not know what provisioning server(s) the third party uses to check access rights and user privileges. Therefore, the client must send all tokens, separated - by a space. -

-

- When a provisioning server receives a request containing multiple tokens, the most forgiving response must be returned. -

- - - - - - - - - - - - - - - - ]]> - - - - -

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:sn:provisioning" in response to &xep0030; information requests.

- - - -]]> - - - - - ... - - ... - -]]> - -

- In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined - in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead. -

- - - -

- To minimize network traffic, and optimize response time, devices should cache access rights and user privileges provided by the provisioning server. If memory is limited, - items in the cache should be ordered by last access, and items with the oldest last access timestamp should be removed first. A safety valve can optionally be implemented as well, - removing unused cache items after a certain age, even if memory is available. -

-

- The device can assume that access rights and user privileges on the provisioning server do not change over time, unless the provisioning server says so. -

-

- The provisioning server on the other hand, must keep track of when a device is online and offline, and clear the cache of the device if changes are made that affects the device. - If the device was offline when those changes occurred, the provisioning server must send the clear cache command as soon as the device comes online again. -

-

- When creating a new trust relationship, the device should always clear its cache, if it contains information from before. -

-

- To minimize stress of the provisioning server during synchronous sensor start up, for instance after a power failure, all clients should aim to persist its cache if possible. Clients - not persisting its cache may produce too much stress on the provisioning server on start-up, practically removing it from the network. -

- - -

- When working with multiple provisioning servers, there are some things that should be considered: -

-
    -
  • - When a device requests information from the provisioning servers, this can be done in a parallel fashion. Even though the provisioning servers - were added in a sequential fashion, there is no order or priority between the servers. -
    • -
  • - When receiving different responses from different servers, with regards to access rights, privileges, relationships, etc., - the union of rights, or the most forgiving or most accepting response should be used. If one of the servers grant a privilege, the privilege is assumed - to exist. If one of the servers grant a friendship request, the friendship request should be granted, etc. Most probably, different servers will manage - different subsets of entities on the network, and when they receive questions about unrecognized devices, they will simply deny access. -
    • -
  • - If a provisioning server requires total control of the network, it should not allow secondary trust relationships. However, if such a server enters a network - and there exist previous provisioning servers (i.e. they accept secondary trust relationships), more trust relationships are assumed to be acceptable. -
    • -
  • - Even though examples in this document only list a secondary trust relationship, there is no such limit. There may exist many different trust relationships in a network - or for a given device. -
    • -
- - -

- One important design consideration when implementing a provisioning server is how to handle new services, users and privileges. One option might be to automatically - ignore anything not recognized. Another option might be to dynamically add new services, user names and privileges to internal data sources, making it easier to manage - new types of services dynamically. However, adding such items automatically might also make such data sources grow beyond control. -

- - -

- All examples in this document have been simplified examples where a few devices containing a few fields have been read. However, in many cases large subsystems with - very many sensors containing many fields have to be read, as is documented in xep-0000-SN-Concentrators.html - xep-0000-SN-Concentrators.html. In such cases, a node may have to be specified using two or perhaps - even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to - a specific kind of node, and the common nodeId. For more information about this, see xep-0000-SN-Concentrators.html. -

-

- Note: For cases where the nodeId is sufficient to uniquely identify the node, it is sufficient to provide this attribute in the request. - If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested. -

- - -

- A small note regarding the use of different tokens. A service can get a Service Token, a device a Device Token and a user - a User Token. When delegating these tokens to third parties, a service sends its Service Token. But, if the service does this - within the context of a user action, the service sends both its Service Token and the users User Token. The same with a device. - If a device delegates its token to a third party, it sends its Device Token. But if the device performs the action in the context of a user action, - the device sends both its Device Token as well as its User Token. -

- - - -

- Delegating trust to a third party may create a weak link in the overall security of a sensor network. Therefore, it's vitally important that the following be adhered to: -

-
    -
  • - Trust should only be delegated in a secure way. Once delegated, it should be able to lock this trust so it cannot be changed without reverting the device to - factory default settings. Such a locked delegation mode can be likened with a production mode, where vital configuration parameters should not be able to be changed. -
    • -
  • - If allowing installation using a LED, as above, make sure the LED does not light up for a long time, limiting the window of access where the sensor can be linked to a - provisioning server. -
    • -
  • - Provisioning servers should be monitored during operation, since it provides a vital link in the operation of the network. -
    • -
  • - Multiple provisioning servers could be allowed, for redundancy or for scalability. This specification does not limit the number of provisioning servers used in a network, - not used by a device. Examples use only one provisioning server for simplicity. -
    • -
  • - Generally, take care what kind of provisioning servers you allow in a network. -
    • -
- - -

This document requires no interaction with &IANA;.

- - -

REQUIRED.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -]]> - - - -

Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.

- - \ No newline at end of file diff --git a/xep-0324.xml b/xep-0324.xml new file mode 100644 index 00000000..e1d0746d --- /dev/null +++ b/xep-0324.xml @@ -0,0 +1,1672 @@ + + +%ents; +]> + + +
+ Sensor Networks - Provisioning + This specification describes an architecture for efficient provisioning of services, access rights and user privileges in sensor networks. + + This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0030 + sensor-data + + + + NOT_YET_ASSIGNED + + Peter + Waher + peter.waher@clayster.com + peter.waher@jabber.org + http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + + 0.0.5 + 2013-04-04 + pwa + +

Added control use cases.

+

Grouped use cases.

+ + + + 0.0.4 + 2013-04-01 + pwa + +

Added altitude credentials.

+

Added resource information of original called to their corresponding JIDs.

+

Changed the return type of a rejected message.

+

Made images inline.

+

Converted the glossary into a definition list.

+ + + + 0.0.3 + 2013-03-18 + pwa + +

Added information about how to read sensors from large subsystems.

+

Added friend recommendation message.

+

Added client/device/service tokens.

+ + + + 0.0.2 + 2013-03-12 + pwa + +

Added use cases for service access rights and corresponding user privileges.

+ + + + 0.0.1 + 2013-03-11 + pwa + +

First draft.

+ + +
+ +

+ This XEP provides the underlying architecture, basic operations and data structures for provisioning of services, access rights and user privileges in sensor networks. +

+

+ Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). + Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily containing millions of devices in peer-to-peer networks. +

+

+ An added complexity in the provisioning case is that sensors often have very limited user interface options. Therefore, this document explains how provisioning can be done + efficiently using a trusted third party with more power and options when it comes to user interface design and storage. +

+

+ This XEP relies heavily on sensor-data sensor-data. + Sensor networks contain many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
XEPDescription
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled, based on &xep0004;
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
exi + Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered + in all sensor network implementations where memory and packet size is an issue. +
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
sensor-network-provisioningThis specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
sensor-data + Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. + It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs. +
+ + +

The following table lists common terms and corresponding descriptions.

+
+ +
Actuator
+
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
+ + +
Computed Value
+
A value that is computed instead of measured.
+ + +
Concentrator
+
Device managing a set of devices which it publishes on the XMPP network.
+ + +
Field
+
+ One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. + Fields should be unique within the triple (Node ID, Field Name, Timestamp). +
+ + +
Field Name
+
Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
+ + +
Field Type
+
What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
+ + +
Historical Value
+
A value stored in memory from a previous timestamp.
+ + +
Identification Value
+
A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
+ + +
Localization information
+
Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.
+ + +
Meter
+
A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
+ + +
Momentary Value
+
A momentary value represents a value measured at the time of the read-out.
+ + +
Node
+
+ Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gatewats, etc., are often depicted as nodes and links between sensors (friendships) + are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). + Each Node has a Node ID. +
+ + +
Node ID
+
+ An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted + ID scheme. +
+ + +
Parameter
+
+ Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters + on nodes/devices. Fields are not parameters, and parameters are not fields. +
+ + +
Peak Value
+
A maximum or minimum value during a given period.
+ + +
Precision
+
+ In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision + determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and + delivering field information in sensor networks should always retain the number of decimals in a message. +
+ + +
Sensor
+
+ Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. + Sensor values are reported as fields during read-out. Each sensor has a unique Node ID. +
+ + +
SN
+
Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
+ + +
Status Value
+
A value displaying status information about something.
+ + +
Timestamp
+
Timestamp of value, when the value was sampled or recorded.
+ + +
Token
+
+ A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate + access rights with the provisioning server. +
+ + +
Unit
+
Physical unit of value. Example: MWh, l/s, etc.
+ + +
Value
+
A field value.
+ + +
Value Status
+
Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
+ + +
Value Type
+
Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
+ + +
WSN
+
Wireless Sensor Network, a sensor network including wireless devices.
+ + +
XMPP Client
+
Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.
+ +
+ + +

+ The most basic use case in sensor networks is to read out sensor data from a sensor. However, since protecting end-user integrity and system security is vital, access + rights and user privileges have to be imposed on the network. +

+

+ To store access rights in all sensors might be very impractical. Not only does it consume memory, it's difficult to maintain track of the current system status, make sure + all devices have the latest configuration, distribute changes to the configuration, etc. +

+

+ Furthermore, most sensors and small devices have very limited possibility to provide a rich user interface. Perhaps all it can do is to provide a small LED and a button, + useful perhaps for installing the sensor in the network, but not much more. +

+

+ As an added complexity, the sensor network operator might not even have access to the XMPP Servers used, and provisioning needs to lie outside of the XMPP Server domains. +

+

+ To solve this problem in an efficient manner, an architecture using distributed trusted third parties is proposed. Such third parties would: +

+
    +
  • Provide a rich user interface and configurable options to end user or back end systems.
    • +
  • Control friendships (who can communicate with whom).
    • +
  • Control content available for different friends (what can be read by whom).
    • +
  • Control operations accessible by different friends (what can be controlled/configured by whom).
    • +
  • Provide additional interoperability services to nodes in the network (for instance, unit conversion).
    • +
+ + +

+ Trust is delegated to a provisioning server by a device, simply by befriending the provisioning server and asking it questions and complying with + its answers. +

+

+ As an illustrative example, following is a short description of how such a trust relationship can be created in a scenario where the sensor only + has a single LED and a single button. +

+
    +
  • Somebody is installing the sensor, giving it a connection to an XMPP server and a JID, reachable from the provisioning server.
    • +
  • The provisioning server is told to create a friendship request to the new sensor.
    • +
  • The sensor flashes its LED for a given time (for example: 30 seconds).
    • +
  • Viewing the LED, the person installing the sensor presses the button.
    • +
  • Receiving the button press within the given time period, accepts the friendship request. Optionally, the device can give user feedback using the LED.
    • +
  • The device performs a service discovery of the new friend, having been a manually added friend.
    • +
  • If the new friend supports this provisioning extension, further responsibilities are delegated to this device.
    • +
  • As the last step the device asks the provisioning server for a token. This device token is later used in calls to other devices and can be used to check access rights.
    • +
+

+ The following diagram shows the general case: +

+

+ +

+

+ The successful case can also be illustrated in a sequence diagram, as follows: +

+

+ +

+

+ The following example shows how a device can request a device token from the provisioning server: +

+ + + + + + + + ]]> + +

+ The provisioning server must not return tokens that contain white space characters. +

+

+ Note: In many cases, an address to a provisioning server might be preprogrammed during production of the + device. In these cases, parts of the above procedure may not neccessary. All the client needs to do, if the provisioning server is not available + in the roster of the device, is to send a subscription request to the provisioning server, to alert the server of the existence of the device, + and possibly request a device token. +

+

+ The following use cases will assume such a trust relationship has been created between the corresponding device and the provisioning server. +

+ + +

+ The isFriendResponse element returned by the provisioning server contains an attribute secondaryTrustAllowed that is by default + set to false. If the provisioning server has no problem with allowing multiple trust to be delegated by devices in the network, it can choose to set this + attribute to true in the response. If true, the device knows it has the right to add its own friends, or to add secondary trust relationships. +

+

+ The following diagram continues with the example given above, of how a sensor with a limited user interface, can allow to manually add new friends, including new + trust relationships using a single LED and a button. +

+

+ +

+ + +

+ When multiple trust is used, the entity (client, user, service, etc.) has one token from each provisioning server. However, when sending a token to a third party, + the sender does not know what provisioning server(s) the third party uses to check access rights and user privileges. Therefore, the client must send all tokens, separated + by a space. +

+

+ When a provisioning server receives a request containing multiple tokens, the most forgiving response must be returned. +

+ + + + + + + + + + + + + + + + ]]> + + + + + +

+ The following diagram displays how a friendship request from an external party can be handled, delegating the responsibility to a trusted third party: +

+

+ +

+

+ The communication between the XMPP Device and the Provisioning Server could be as follows: +

+ + + + + + + + ]]> + +

+ Note: The provisioning server implicitly understands which two JIDs that are to be checked: The first one is the sender of the message, the second one + is the JID available in the jid attribute in the request. +

+

+ Note 2: Any resource information in the JID must be ignored by the provisioning server. +

+ + +

+ The following diagram displays a friendship request from an external party being rejected as a result of the trusted third party negating the friendship: +

+

+ +

+

+ The communication between the XMPP Device and the Provisioning Server could be as follows: +

+ + + + + + + + ]]> + + + +

+ If the provisioning server decides that two friends in the network should no longer be friends and communicate with each other, it simply sends a message to + at least one of the friends as follows: +

+

+ +

+

+ The provisioning server should only send such messages to clients that have previously asked the provisioning server if friendship requests should be accepted or not. +

+

+ Note: The device should only honor such messages, if the sender is the trusted third party. Such messages received from other entities not trusted should + be silently ignored. +

+ + + + + ]]> + + + +

+ The provisioning server can, apart from accepting new friendships and rejecting old friendships, also recommend new friendships. In this case, the provisioning server + simply sends a message to one or both of the soon to be friends, as follows: +

+

+ +

+ + + + ]]> + +

+ Note that the receptor can still ask the provisioning server if it can form a friendship with the suggested friend, using the isFriend command. +

+ + + + +

+ An important use case for provisioning in sensor networks is who gets to read out sensor data from which sensors. This use case details how communication with a + provisioning server can help the device determine if a client has sufficient access rights to read the values of the device. +

+

+ +

+

+ Note: This use case is an extension of the use case 'Read-out rejected' in the XEP sensor-data. +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + Access denied. + + ]]> + +

+ Note that the provisioning server responds with a canReadResponse element, with the same content as the canRead element in the request. +

+ + +

+ In case the device handles multiple nodes that can be read, the provisioning server has the possibility to grant read-out, but to limit the nodes that can be read out. + The provisioning server does this by returning the list of nodes that can be read. +

+

+ +

+

+ Note: This use case is an extension of the use case 'Read-out of multiple devices' in the XEP sensor-data. +

+

+ Note 2: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed + to be read. If no nodes in the request are allowed to be read, the provisioning server must respond with a result='false', so the device can reject the read-out request. +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the provisioning server responds with a canReadResponse element, similar to the canRead element in the request, except + only the nodes allowed to be read are read. The device must only permit read-out of nodes listed in the response from the provisioning server. Other nodes available + in the request should be ignored. +

+ + +

+ In case the provisioning server wants to limit the fields a device can send to a client, the provisioning server has the possibility to grant read-out, but + list a set of fields the device is allowed to send to the corresponding client. +

+

+ +

+

+ Note: If the server responds, but without specifying a list of field names, the device can assume that all fields available in the original request are allowed + to be sent. If no fields in the request are allowed to be sent, the provisioning server must respond with a result='false', so the device can reject the read-out request. +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the provisioning server responds with a canReadResponse element, similar to the canRead element in the request, except only + the fields allowed to be sent are listed. The client must only send fields having field names in this list. +

+

+ Also note, that the provisioning server can return both lists of allowed nodes and allowed field names in the response. In this case, the device must only send allowed fields + from allowed nodes, and ignore all other fields and/or nodes. +

+ + + + +

+ An important use case for provisioning in sensor networks is who gets to control devices, and what they can control. This use case details how communication with a + provisioning server can help the device determine if a client has sufficient access rights to perform control actions on the device. +

+

+ + +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ In case the device handles multiple nodes that can be read, the provisioning server has the possibility to grant control access, but to limit the nodes that can be controlled. + The provisioning server does this by returning the list of nodes that can be controlled. +

+

+ + +

+

+ Note: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed + to be controlled. If no nodes in the request are allowed to be controlled, the provisioning server must respond with a result='false', so the device can reject the read-out request. + The same is true for parameters: If the provisioning server does not specify parameters in the response, the caller can assume all parameters are allowed. +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the provisioning server responds with a canControlResponse element, similar to the canControl element in the request, except + only the nodes allowed to be controlled are included. The device must only permit control of nodes listed in the response from the provisioning server. Other nodes available + in the request should be ignored. +

+

+ Also note, that the restricted set of nodes and/or parameters returned from the provisioning server must be returned to the original caller, so it can + act on the information that only a partial control action was allowed and taken. +

+ + +

+ In case the provisioning server wants to limit the control parameters a client can control in a device, the provisioning server has the possibility to grant + control access, but list a set of parameters the client is allowed to control in the corresponding device. +

+

+ + +

+

+ Note: If the server responds, but without specifying a list of nodes, the device can assume that all nodes available in the original request are allowed + to be controlled. If no nodes in the request are allowed to be controlled, the provisioning server must respond with a result='false', so the device can reject the read-out request. + The same is true for parameters: If the provisioning server does not specify parameters in the response, the caller can assume all parameters are allowed. +

+

+ The following example shows the communication first between the client and the device, then the device and the provisioning server, and last between the device and the client: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the provisioning server responds with a canControlResponse element, similar to the canControl element in the request, except only + the parameters allowed to be sent are listed. The device must only control parameters included in this list. +

+

+ Also note, that the provisioning server can return both lists of allowed nodes and allowed parameter names in the response back to the client, so it can + act on the information that only a partial control action was allowed and taken. +

+ + + + +

+ When the provisioning server updates access rights and user privileges in the system, it will send a clearCache command to corresponding devices. + If a device was offline during the change, the provisioning server must send the clearCache message when the device comes online again. To acknowledge + the receipt of the command, the client responds with a clearCacheResponse element. This response message does not contain any information on what was + done by the client. It simply acknowledges the receipt of the command, to make sure the provisioning server does not resend the clear cache command again. +

+

+ Note: The clearCache command does not include information on what has been changed, so the device needs to clear the entire cache. This + to avoid complexities in making sure updates made to the provisioning rules works in all cases, and to minimize complexity in the implementation of the protocol on the sensor side. + It is also not deemed to decrease network performance, since changing provisioning rules for a device is an exceptional event and therefore does not affect performance during + normal operation. +

+ + + + + + + + + ]]> + + + + + +

+ A service requesting provisioning assistance, needs to retrieve a service token from the provisioning server. The following example shows how this can be done. +

+ + + + + + + + ]]> + + + +

+ Provisioning in sensor networks also requires control of user access to different services in the network. This use case shows how service access rights are controlled using + a trusted provisioning server. +

+

+ +

+

+ First, the user connects to the service in some way. This can be done using XMPP, HTTP, HTTPS or some other means. The service need to extract some form of identifying + credentials from the user, and provide that to the provisioning server. The provisioning server determines if the client has access rights to the service based on these + credentials, and also provides the service with a userToken that the service can use in further communication with the provisioning server regarding + the user and its privileges. +

+

+ The following table lists some different types of credentials that the service can extract from the client: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypeProtocolsDescription
JIDXMPPAllows provisioning to be done on the JID the user has.
IP AddressHTTP, HTTPSAllows provisioning to be done on IP address or IP-ranges for instance.
Host NameHTTP, HTTPS with DNSIf the service has access to the client host name, for instance in an intra network, this can be used for provisioning.
X.509 CertificateHTTPSIf the client provides a client certificate, such a certificate can be used to provide provisioning.
X.509 Certificate ThumbprintHTTPS + The client can also choose to validate the certificate itself and only send the certificate thumbprint to the provisioning server. Even though this + provides somewhat lesser security than providing the entire certificate, it might be an option to distribute certificate validation checks across the network + to lower the work load on the provisioning server. +
User NameHTTP, HTTPS, XMPP + If authenticated HTTP(S) access is implemented, the service can provide the user name as credentials. XMPP based clients can use + information in the roster to provide user name information to the provisioning server. +
GeolocationHTML5 over HTTP(S), XMPP + If the geographic location (longitude, latitude and possibly altitude) of the user client is known, it can be used. HTML 5 provides mechanism whereby the location + of the client can be fetched. &xep0080; provides a mechanism whereby client location can be obtained over XMPP. +
SSO TokenIntranetIf a single sign on token is available, such a token could be provided as credentials.
ProtocolAnyConnection protocol used to connect to the service.
+

+ The provisioning server receives these credentials, and decides if the user should have access to the service or not, based on rules configured in the provisioning service. + If the user is granted access, a userToken is generated and returned to the service. This token +

+

+ Now, the service can determine if this access grant is sufficient or not. It can require the user to login into the service first. If so, the service should provide the provisioning + server with the user name used during login, when logged in. +

+ + + + + + + + + + + + + + + + + + + + + + ]]> + + + + + +

+ When a user has been given access to a service, and properly been identified, the service can ask the provisioning service for detailed user privileges to control + different aspects of the service. This can be done using the hasPrivilege command. Here, the service sends its serviceToken and + the userToken earlier received when being granted access to the service. Furthermore a privilegeId has to be provided. +

+

+ A Privilege ID is a string composed of one or a sequence of parts, delimited by period characters. The Privilege IDs form a tree of privileges, + using an invisible, but common, root privilege. +

+

+ The following table suggests some examples of Privilge IDs, with suggestive descriptions. (Only used as an example.) +

+ + + + + + + + + + + + + + + + + +
Privilege IDDescription
Databases.Energy.SelectGives the user the rights to select data from the Energy database.
Databases.Energy.InsertGives the user the rights to insert data into the Energy database.
Databases.Energy.DeleteGives the user the rights to delete data from the Energy database.
+

+ Note: Note that privilege IDs are local to the service. Different services are allowed to use similar or same Privilege IDs, in different contexts and + with different meanings. The provisioning server must separate Privilege IDs from different services. +

+

+ The client must always provide full Privilege IDs to the provisioning server. The provisioning server however, can grant partial privilege IDs, pointing to parent + privilege nodes to a user or a role object, granting a user a specific role. If granting a parent privilege ID to a user or role, this is interpreted as + giving the corresponding user or role the privileges of the entire sub-tree defined by the parent privilege ID. +

+

+ If additional control over privileges is desired, negative privileges can be assigned to the user or role. Granted or explicitly rejected privileges are specified in a + sequential list of full or partial privilege IDs. This list is then processed sequentially to determine if a privilege is granted or not. +

+

+ Example: Consider the privileges above. Give a user or its corresponding role the following privileges in a sequential list: +

+
    +
  • Exclude: Databases.Energy.Delete
    • +
  • Include: Databases.Energy
    • +
+

+ This would give the user rights to select and insert data, but not to delete data from the Energy database. +

+

+ Note: Care should be taken when constructing Privilege IDs, so they do not include variable data that potentially can create an infinite amount of + privilege IDs. For example: Do not include user names, sensor IDs, etc., in privilege IDs, as the number of such entities cannot be estimated or is scalable beforehand. +

+

+ The following diagram shows an example of how a service asks permission from a provisioning server before an action is taken: +

+

+ +

+ + + + + + + + + + + + ]]> + + + +

+ To improve performance, services can download the entire set of user privileges, and perform privilege checks internally. The following diagram displays + how the above two use cases could be handled in such a case: +

+

+ +

+

+ Note: When downloading privileges using this command, a sequential list of full or partial privilege IDs will be returned together with the + corresponding include or exclude flags. The above mentioned algorithm of determining user privileges must be implemented by the service, if this method is + to be used. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + + + +

If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:sn:provisioning" in response to &xep0030; information requests.

+ + + +]]> + + + + + ... + + ... + +]]> + +

+ In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined + in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead. +

+ + + +

+ To minimize network traffic, and optimize response time, devices should cache access rights and user privileges provided by the provisioning server. If memory is limited, + items in the cache should be ordered by last access, and items with the oldest last access timestamp should be removed first. A safety valve can optionally be implemented as well, + removing unused cache items after a certain age, even if memory is available. +

+

+ The device can assume that access rights and user privileges on the provisioning server do not change over time, unless the provisioning server says so. +

+

+ The provisioning server on the other hand, must keep track of when a device is online and offline, and clear the cache of the device if changes are made that affects the device. + If the device was offline when those changes occurred, the provisioning server must send the clear cache command as soon as the device comes online again. +

+

+ When creating a new trust relationship, the device should always clear its cache, if it contains information from before. +

+

+ To minimize stress of the provisioning server during synchronous sensor start up, for instance after a power failure, all clients should aim to persist its cache if possible. Clients + not persisting its cache may produce too much stress on the provisioning server on start-up, practically removing it from the network. +

+ + +

+ When working with multiple provisioning servers, there are some things that should be considered: +

+
    +
  • + When a device requests information from the provisioning servers, this can be done in a parallel fashion. Even though the provisioning servers + were added in a sequential fashion, there is no order or priority between the servers. +
    • +
  • + When receiving different responses from different servers, with regards to access rights, privileges, relationships, etc., + the union of rights, or the most forgiving or most accepting response should be used. If one of the servers grant a privilege, the privilege is assumed + to exist. If one of the servers grant a friendship request, the friendship request should be granted, etc. Most probably, different servers will manage + different subsets of entities on the network, and when they receive questions about unrecognized devices, they will simply deny access. +
    • +
  • + If a provisioning server requires total control of the network, it should not allow secondary trust relationships. However, if such a server enters a network + and there exist previous provisioning servers (i.e. they accept secondary trust relationships), more trust relationships are assumed to be acceptable. +
    • +
  • + Even though examples in this document only list a secondary trust relationship, there is no such limit. There may exist many different trust relationships in a network + or for a given device. +
    • +
+ + +

+ One important design consideration when implementing a provisioning server is how to handle new services, users and privileges. One option might be to automatically + ignore anything not recognized. Another option might be to dynamically add new services, user names and privileges to internal data sources, making it easier to manage + new types of services dynamically. However, adding such items automatically might also make such data sources grow beyond control. +

+ + +

+ All examples in this document have been simplified examples where a few devices containing a few fields have been read. However, in many cases large subsystems with + very many sensors containing many fields have to be read, as is documented in xep-0000-SN-Concentrators.html + xep-0000-SN-Concentrators.html. In such cases, a node may have to be specified using two or perhaps + even three ID's: a sourceId identifying the data source controlling the device, a possible cacheType narrowing down the search to + a specific kind of node, and the common nodeId. For more information about this, see xep-0000-SN-Concentrators.html. +

+

+ Note: For cases where the nodeId is sufficient to uniquely identify the node, it is sufficient to provide this attribute in the request. + If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested. +

+ + +

+ A small note regarding the use of different tokens. A service can get a Service Token, a device a Device Token and a user + a User Token. When delegating these tokens to third parties, a service sends its Service Token. But, if the service does this + within the context of a user action, the service sends both its Service Token and the users User Token. The same with a device. + If a device delegates its token to a third party, it sends its Device Token. But if the device performs the action in the context of a user action, + the device sends both its Device Token as well as its User Token. +

+ + + +

+ Delegating trust to a third party may create a weak link in the overall security of a sensor network. Therefore, it's vitally important that the following be adhered to: +

+
    +
  • + Trust should only be delegated in a secure way. Once delegated, it should be able to lock this trust so it cannot be changed without reverting the device to + factory default settings. Such a locked delegation mode can be likened with a production mode, where vital configuration parameters should not be able to be changed. +
    • +
  • + If allowing installation using a LED, as above, make sure the LED does not light up for a long time, limiting the window of access where the sensor can be linked to a + provisioning server. +
    • +
  • + Provisioning servers should be monitored during operation, since it provides a vital link in the operation of the network. +
    • +
  • + Multiple provisioning servers could be allowed, for redundancy or for scalability. This specification does not limit the number of provisioning servers used in a network, + not used by a device. Examples use only one provisioning server for simplicity. +
    • +
  • + Generally, take care what kind of provisioning servers you allow in a network. +
    • +
+ + +

This document requires no interaction with &IANA;.

+ + +

REQUIRED.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + +

Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.

+ + \ No newline at end of file From 3f92d3d8dc7b9548abcc581193044fb3076a7472 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:49:57 -0600 Subject: [PATCH 07/12] protoxep --- inbox/rayo.xml | 4306 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 4306 insertions(+) create mode 100644 inbox/rayo.xml diff --git a/inbox/rayo.xml b/inbox/rayo.xml new file mode 100644 index 00000000..fb9812c1 --- /dev/null +++ b/inbox/rayo.xml @@ -0,0 +1,4306 @@ + + +%ents; +]> + + +
+ Rayo + This specification defines an XMPP protocol extension for the third-party control of telephone calls and other similar media sessions. The protocol includes support for session management/signaling, as well as advanced media resources such as speech recognizers, speech synthesizers and audio/video recorders. The protocol serves a different purpose from that of first-party protocols such as Jingle or SIP, and is compatible with those protocols. + + This XMPP Extension Protocol is copyright (c) 2013 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + + + + NOT_YET_ASSIGNED + + Ben + Langfeld + ben@langfeld.me + ben@langfeld.me + http://langfeld.me + + + Jose + de Castro + jdecastro@voxeo.com + jdecastro@voxeo.com + http://voxeolabs.com + + + 0.0.1 + 2013-04-05 + bl +

First draft.

 + +
+ +

Rayo is a protocol to allow third-party remote control over media sessions, audio/video mixers and a variety of advanced media resources such as speech recognizers, speech synthesizers and audio/video recorders. These capabilities can be combined to create a wide variety of applications such as menu-based phone systems, in-game conferencing and anonymous dating services. Unlike Jingle or even SIP, a Rayo client is not concerned with being a party to either the session negotiation or the media stream itself.

+ +
    +
  • A Rayo server takes on the role of negotiating a media session between itself and some other endpoint, or between two external endpoints, by way of an implementation-specific means, be that Jingle, SIP, the public-switched telephone network, or anything else. The server may even bridge multiple networks.
    • +
  • The server then presents the Rayo protocol as an interface to a Rayo client, allowing it to monitor and/or exercise third-party control over particular the established media sessions.
    • +
  • The client has the option to accept/reject/answer inbound session requests, request the creation of outbound sessions and monitor their progress, execute media operations such as speech synthesis, speech recognition & recording, and to end sessions.
    • +
+ +

The relationship between the calling parties, the Rayo server and the Rayo client looks something like this:

+ + [caller] ----SIP---- [rayo server] ( -----Jingle---- [callee] ) optional + | + | + rayo client + + +

This document defines the core Rayo protocol, and contains provisions for its extension by further specifications.

+ + +

In order to understand the nature of a Rayo interaction, here we show a simple example of a control session.

+ + + + + +]]> + +

In this example, a call from 'tel:+13058881212' has reached the Rayo server 'shakespeare.lit' by calling 'tel:+18003211212', and been assigned an ID '9f00061'. The server has determined that 'juliet@capulet.lit' is a valid candidate for delegating control of the call, and so has directed an offer event to her 'balcony' resource.

+ +

The client then decides that it is able to handle the incoming call, and so accepts it from the server, thus gaining exclusive control and indicating to the calling party that the call will be processed and that it should ring.

+ + + + +]]> + + +]]> + +

Following confirmation from the server that the attempt to gain control of the call was successful, the client proceeds to answer the call, opening up the media stream between the caller and the server.

+ + + + +]]> + + +]]> + +

Once the client has confirmation that the call has been answered, it triggers the start of a media output component in order to play a message to the caller using a Text-to-speech (TTS) engine.

+ + + + + + + + +]]> + + + + +]]> + +

After confirmation that the output component was successfully created, the client then awaits notification of its completion.

+ + + + + + +]]> + +

The client then decides it has no further operations to perform on the call, and that the call should end. It instructs the server to hang up the call gracefully.

+ + + + +]]> + + +]]> + + + + + + +]]> + + +

The protocol defined herein is designed to provide the following features:

+
    +
  1. Call Control: Incoming calls are "offered" to clients at which point they can be answered, rejected, redirected to another destination, etc. Outbound calls may also be made and monitored. Every attempt is made to be shield the Rayo client from the low level telephony protocol (e.g. SIP, Jingle, PSTN, etc).
    2. +
  2. Audio File Playback: A compatible Rayo server will fetch a file from a a specified URL and play the containing audio to the caller.
    3. +
  3. Speech Synthesis / TTS: In cases where dynamic data must be spoken, a Speech Synthesis engine may be used to play computer generated speech to the caller.
    4. +
  4. Touch-tone Events / DTMF: Rayo surfaces real-time event when the caller presses keys on their touch-tone keypad.
    5. +
  5. Speech Recognition: Enables the phone application to take spoken queues allowing for sophisticated voice-driven menus and directory services.
    6. +
  6. Call Recording: Can be used to capture the caller's voice (e.g. Voicemail) or both sides of the call for auditing and compliance purposes.
    7. +
  7. Mixing: Typically referred to as an audio "conference"; calls can be joined together so that the participants can hear each other in real-time.
    8. +
+ +

Many third-party call control protocols have preceeded Rayo (see Asterisk's AGI/AMI, FreeSWITCH's eventsocket, Microsoft's TAPI, Java's JTAPI, Novell/AT&T's TSAPI, CSTA, etc). None of these protocols is ideal, and all have one or more of the following drawbacks:

+
    +
  • Totally ground-up wire protocol requiring implementation all the way down to the socket.
    • +
  • Platform/vendor/hardware specific - each system implements its own proprietary protocol (in many cases, without a formal published specification) which does not allow easily porting an application from one back-end to another.
    • +
  • Synchronous interface - Operations on calls or other entities are often blocking, and one must serialise all control messages.
    • +
  • Inconsistent - evolved, rather than designed.
    • +
  • Lacking in scalability - client/server sometimes tied one-to-one, servers rarely clustered, advanced message routing not possible.
    • +
  • Poor security - lack of wire-level encryption, lack of or sub-standard authentication mechanisms, lack of or limited authorization mechanisms, lack of or poor sandboxing between multiple tenants on one system.
    • +
  • Inextensible - The specification of extensions to the core protocol is either impossible or very difficult.
    • +
+ +

Rayo has been designed with these failings in mind, and intends to address many concerns not addressed by these earlier attempts. The following considerations were made:

+
    +
  • Simple client library implementation - XMPP client libraries exist in all modern languages, and many are of a high standard of quality and maturity.
    • +
  • Cross-platform standard - The protocol must not expose any platform specifics and all elements should be candidates for implementation on any suitable platform. Addiditionally, the protocol must be ratified as a standard following a community discussion.
    • +
  • Asynchronous interface - The protocol should present an asynchronous interface for the purposes of performance and flexibility in performing parallel operations.
    • +
  • Consistent - The protocol must provide a considered, unobtrusive, logically and philisophically consistent interface.
    • +
  • Federated - The protocol must support communication between client and server entities on separately owned, operated and addressed networks.
    • +
  • Flexible routing - The protocol must lend itself to routing across wide networks such as the internet, and to potential complex routing such as proxying or redirection. Additionally, the client and server should each be aware of the presence of the other and be able to use such information to make routing decisions.
    • +
  • Extensible - The protocol must provide for the possibility of extra functionality being added by future specifications or an individual implementation.
    • +
  • Secure - The protocol should include appropriate measures for authentication and authorization of participants, as well as preventing third-parties from intercepting control messages.
    • +
+ +

Many of the features in the above list are available to Rayo at no specification or implementation cost, since they are core to XMPP itself and thus Rayo inherits these 'for free'.

+ +

Additionally, the protocol is required to abstract away the complexity of the back-end negotiation, especially the details of the transport protocols such as SIP or Jingle, but to map conceptually to such protocols.

+ + + +
+ +
Third-party call control (3PCC)
+
The observation and/or control of a live media session by an entity which is not a direct party to the session.
+ + +
Command
+
Commands instruct the receiving entity to perform some atomic action. Commands may be executed against a given call, component or mixer and can be considered completed as soon as they receive a response. Some commands create components, and return a reference to the component in their response.
+ + +
Component
+
Components extend the Rayo protocol by providing additional media and call control functionality. Components are created by an appropriate command, which returns a reference to the component. Components are executed asynchronously, and have a lifecycle attached to them, with the ability to trigger events or have commands issued to it. Once a component is stopped or comes to an end naturally, it will issue a special <complete/> event, indicating that it has ceased executing and deliver any required data.
+ + +
Potential controlling party (PCP)
+
An XMPP entity to which an offer to control an incoming call may be sent.
+ + +
Definitive controlling party (DCP)
+
The XMPP entity which gains a lock on control of a session, either by requesting the session's creation, or being the first respondent to an offer.
+ + +
Security Zone
+
A security zone is the conceptual border around a call which defines which parties may interact with the call's media or signaling. A security zone MUST contain the rayo server's internal implementation, the media server to which the call is joined, the DCP, and any JID whose bare form is the same as the DCP. A server MAY relax this definition further, for example to consider all JIDs at the same domain to be in the same security zone.
+ +
+ + + + In examples, the following JIDs are used: +
    +
  • juliet@capulet.lit/balcony, romeo@montague.lit/orchard - Potential controlling parties
    • +
  • shakespeare.lit - The root domain of the Rayo service
    • +
+ + + +

A complete Rayo deployment has several elements and interacting entities which must be understood.

+ + + +

A Rayo server is an entity which is capable of receiving and intiating calls and being party to their media stream, while exposing a Rayo interface to a client in order to permit control over its calls. The Rayo server may handle calls in any way supported by the implementation, such as SIP, Jingle, etc, and should expose a full XMPP domain at the root level of the service deployment (eg shakespeare.lit).

+

The Rayo server is responsible for keeping track of valid clients, routing calls to the correct potential controlling parties, performing authorization measures on received stanzas, etc.

+

For the purposes of this specification, complex server-side deployments such as clusters, proxies, gateways, protocol translators, etc are not considered. Further details of such concepts may be found in their (present or future) relevant specifications.

+ + +

A Rayo client is an entity which implements the Rayo protocol for the purpose of asserting control over calls made available by a Rayo server. The method by which such control measures are determined is outside the scope of this document, but may be the result of human interaction or some automated decision-making process.

+

A Rayo client is responsible for indicating its availability to a Rayo server and responding to offer messages appropriately.

+ + +

A Rayo call is a short-lived XMPP entity within the scope of the deployment's root domain, perhaps at a sub-domain, with the purpose of representing a single session. It is usually a simple alias for the main server process.

+

A Rayo call is the entity with which most client interactions are made, and is responsible for sending its events to and receiving commands from a client. Calls may host components.

+

Calls have separate presence from the root domain of the service and thus appear to be separate entities.

+ + +

A Rayo mixer is an XMPP entity within the scope of the deployment's root domain, perhaps at a sub-domain, with the purpose of representing a service for the linking of media streams from several calls. It is usually a simple alias for the main server process.

+

A Rayo mixer is responsible for sending its events to and receiving commands from one or more clients, and can host components.

+

Mixers have separate presence from the root domain of the service and its calls and thus appear to be separate entities.

+ + +

A Rayo command is a simple combination of request and response and may be issued directly to the service domain, or to a call or a mixer. Commands are executed serially and are generally very short-lived.

+ + +

Components extend the Rayo protocol by providing additional media and call control functionality.

+ +

Components have a lifecycle and are started by sending a specialized command to a call or mixer. Thus, a request for creation of a component will return a reference to the component's ID, and the component will continue to execute until it completes, potentially sending events and processing commands along the way (such as an instruction to pause or terminate), before finally issuing an event indicating its completion and thus unavailability. Multiple components may be active on a call or mixer at any one time, and commands may be executed on any entity during the execution of a component.

+ + + + +

All of the actors described in the previous section (with the exception of commands) are represented by XMPP entities with a JID of their own. Thus, a scheme for determining the JIDs of each of these entities is required. The following is the required naming scheme for Rayo deployments, where elements in square brackets are optional.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActorJID formatExample JID
Server[service domain]shakespeare.lit
Clientany JIDjuliet@capulet.lit/balcony
Call<call ID>@[<call sub-domain>.]<service domain>f88eh2@call.shakespeare.lit
Mixer<mixer name>@[<mixer sub-domain>.]<service domain>conf1@mixer.shakespeare.lit
Call Component<call ID>@[<call sub-domain>.]<service domain>/<component ID>f88eh2@call.shakespeare.lit/8f83jf
Mixer Component<mixer name>@[<mixer sub-domain>.]<service domain>/<component ID>conf1@mixer.shakespeare.lit/932eu
Server Component<service domain>/<component ID>shakespeare.lit/f3fg4
+

Commands should be addressed to the entity on which they should be enacted. Individual commands only apply to certain object (for example instructing a component to hangup will return an error). In general, commands may be sent from a client to the service, a call, a mixer or a component. Events may be sent from a call, a mixer or a component to a client.

+ + + +

Rayo defines several events and commands which may be executed on one of the above actors. These payloads must be sent within an XMPP primitive element, and the rules are as such:

+
    +
  • Events: Sent as directed presence from the entity producing the event to a client.
    • +
  • Commands: Sent as an <iq/> with the 'type' attribute 'set' from the client to the entity to be acted on. Responses returned as an <iq/> with the 'type' attribute either 'result' or 'error'.
    • +
+ + + +

This section describes the form, function and order of Rayo stanzas sent across the wire, and the circumstances in which they apply and/or may arise.

+ + +

In order for a Rayo client to be considered a potential controlling party for incoming sessions, it MUST first notify the Rayo server that it is available for the receipt of calls. This is done by sending directed presence to the Rayo server with a <show/> element containing 'chat' as in the example:

+ + + chat + +]]> + +

Conversely, when a Rayo client wishes not to be considered a potential controlling party, it SHOULD send directed presence to the Rayo server with a <show/> element containing 'dnd' as in the example:

+ + + dnd + +]]> + + + +

Sessions may be established either at the request of the Rayo client (an outbound call) or as a result of a 3rd party request (an inbound call). Each scenario differs in the Rayo protocol only up to the point at which the session is established and media begins to flow. First we shall examine the sequence of stanzas passed between server and client in each of these scenarios.

+ + +

In order for a client to establish a new outbound call, it MUST first send a dial command to the server, indicating the proposed target for the call, its apparent source, and any meta-data to send to the target as headers.

+ + + +
+
+ + + ]]> + +

On successfully receiving and parsing the dial command, the server SHOULD perform its own proprietary authorization measures to ensure that only desirable outbound sessions are created. If it is established that the command should not be allowed, the server MUST return an error giving an authorization reason.

+ + +

There are several reasons why the server might immediately return an error instead of acknowledging the creation of a new call:

+
    +
  • The client is unknown to the server and the server does not permit session creation by unknown clients.
    • +
  • The client is not authorized to create this new session.
    • +
  • The server does not support outbound calls.
    • +
  • The server does not have sufficient resources to create a new session.
    • +
  • The dial command was malformed.
    • +
+ +

If the client is unknown to the server and the server does not permit session creation by unknown clients, the server MUST return a <registration-required/> error with a type of 'auth'.

+ + +
+
+ + + + + + ]]> + +

If the client is not authorized (as determined by an implementation/deployment-specific algorithm) to create a new outbound session given the parameters provided, the server MUST return a <not-authorized/> error with a type of 'auth'.

+ + +
+
+ + + + + + ]]> + +

If the server does not support outbound calls, the server MUST return a <feature-not-implemented/> error with a type of 'cancel'.

+ + +
+
+ + + + + + ]]> + +

If the server does not have sufficient resources to create a new session, the server MUST return a <resource-constraint/> error with a type of 'wait'.

+ + +
+
+ + + + + + ]]> + +

If the dial command was malformed, the server MUST return a <bad-request/> error with a type of 'modify'.

+ + +
+
+ + + + + + ]]> + + +

If the command is successful and the call is queued, however, confirmation of such should be sent to the client, including a reference to the unique ID of the call. This call ID may be used to execute commands and filter events for the duration of the session.

+ + + + ]]> + +

Once the server receives notification that the session has been accepted by the third party, it should send a ringing event to the client to indicate such:

+ + + + ]]> + +

Similarly, once the server receives notification that the session has been answered, it should negotiate media between the dialed party and its local media server. Once media negotiation is complete, it should send an answered event to the client to indicate such:

+ + + + ]]> + + +

When sending a dial request, a client MAY specify a join target within the dial element:

+ + + + + + ]]> + +

In this case, the server MUST treat the session creation in the same way as without the join element, until the point of media negotiation. Here, the server should negotiate media as specified by the join element, in accordance with the rules defined in joining calls. Media MUST NOT be negotiated with the local media server, unless the join specifies so. The join operation MUST behave as described in joining calls.

+ + + + +

When the system receives a call from one of its connected networks, it MUST then expose that requested session to Rayo clients. It SHOULD use an implementation-specific routing mechanism to map incoming calls to some set of registered JIDs which are considered appropriate controlling parties. From this set, it SHOULD then remove any parties whom it can identify as being temporarily inappropriate for control (either unavailable based on presence, under too much load, or any other metric which the server has available). If, as a result, the set of Potentially Controlling Parties is empty, the server MUST reject the call with a 'decline' reason.

+ +

If the server can identify active Potential Controlling Parties, it MUST offer them control of the call simultaneously. The server must broadcast an offer on behalf of the call to all Potential Controlling Parties, using applicable to/from/header data from the incoming session. The server MUST also include entity capabilities information in the presence stanza containing the offer, in order to advertise the fact that the entity is a call, qualified by the node name "urn:xmpp:rayo:call:1".

+ + + +
+
+ + + ]]> + +

Once the server has offered control, it MUST wait indefinitely for a response from a PCP. The server SHOULD monitor the availability of PCPs to whom offers have been sent. If they all cease to be PCPs (eg by going offline) then the call should be rejected in the same way as if there had not been any available PCPs to begin with.

+ +

If an offered PCP executes a command against the call, by sending a command node to the call's JID inside an IQ 'set', the server should execute the following routine:

+
    +
  1. If the call does not have a DCP, set it to the PCP from which the command originated.
    2. +
  2. If the call has a DCP, and the command did not originate from the DCP, return a conflict (cancel) error in response to the command of the following format: + + + + + + + ]]> + otherwise; +
    3. +
  3. If the command is an accept command, notify the remote calling party that the call has been accepted. Return an empty IQ result to the command issuing party to confirm successful execution.
    4. +
  4. If the command is an answer command, notify the remote calling party that the call has been answered and negotiate media between the calling party and the server's local media server. Return an empty IQ result to the command issuing party to confirm successful execution.
    5. +
  5. If the command is any other, handle it in the manner detailed in the following sections.
    6. +
+ + + + +

Calls in a Rayo system are capable of having their media streams moved/manipulated. Once such manipulation is to join the media streams of two calls. In a scenario where callA and callB should be joined, the client MUST send a join command to either call (not both) specifying the call ID of the other call, like so:

+ + + + + + ]]> + +

If the calls to be joined to each other are in the same security zone, the server MUST join the media streams of the two calls and return an empty IQ result to confirm that the operation has been successful. If the parties to be joined are not within the same security zone, an error should be returned as detailed below.

+ +

When calls are joined to each other by any mechanism, each call MUST dispatch a joined event specifying who they have been joined to:

+ + + + + + + + ]]> + +

By default, the server MUST join the calls by bridging their audio through its local media server, with bidirectional media. In order to specify alternative behaviour, the client MAY specify a media option (either 'bridge' or 'direct') and/or a direction option (either 'duplex', 'send' or 'recv'), and the server MUST bridge accordingly.

+ + +

There are several reasons why the call might return an error instead of acknowledging a join:

+
    +
  • The specified join party does not exist or cannot be found.
    • +
  • The specified join party is inaccessible for the purposes of being joined due to security restrictions.
    • +
  • The server does not have sufficient resources to complete the join.
    • +
  • The join command was malformed.
    • +
  • The specified media/direction options or their combination are not possible/supported.
    • +
+ +

If the specified join party does not exist or cannot be found, the server MUST return a <service-unavailable/> error with a type of 'cancel'.

+ + + + + + + ]]> + +

If the specified join party is inaccessible for the purposes of being joined due to security restrictions, the server MUST return a <not-allowed/> error with a type of 'cancel'.

+ + + + + + + ]]> + +

If the server does not have sufficient resources to complete the join, the server MUST return a <resource-constraint/> error with a type of 'wait'.

+ + + + + + + ]]> + +

If the join command was malformed (eg no call URI specified), the server MUST return a <bad-request/> error with a type of 'modify'.

+ + + + + + + ]]> + +

If the specified media/direction options or their combination are not possible/supported, the server MUST return a <feature-not-implemented/> error with a type of 'modify'.

+ + + + + + + ]]> + + + +

When the client wishes to terminate an existing join, it MUST send an unjoin command specifying the join to break (call-id).

+ + + + ]]> + +

The server MUST unjoin the media streams of the two calls, rejoin both to the media server and return an empty IQ result to confirm that the operation has been successful:

+ + ]]> + +

Optionally, if no join is specified on the unjoin command, all existing joins must be broken:

+ + + + + + ]]> + + +

There are several reasons why the call might return an error instead of acknowledging an unjoin command:

+
    +
  • The specified join does not exist.
    • +
  • The unjoin command was malformed.
    • +
+ +

If the specified join does not exist, the server MUST return a <service-unavailable/> error with a type of 'cancel'.

+ + + + + + + ]]> + +

If the unjoin command was malformed (eg an empty call URI specified), the server MUST return a <bad-request/> error with a type of 'modify'.

+ + + + + + + ]]> + + + + +

Calls may be unjoined from other calls either in response to an unjoin command, as the result of one of the calls disconnecting, or as the result of an error. The server MUST monitor calls for being unjoined from another call, and emit an unjoined event when this is detected.

+ + + + + + + + ]]> + + + +

If a client wishes to modify the parameters of a join, it MUST send a new join command to the target call with the new parameters. The server MUST renegotiate media using the new parameters, and acknowledge the command's completion. The server MUST NOT re-send joined events.

+ + + + + + + + + + + + + + + + + + + + ]]> + +

Rayo calls SHOULD support being joined to more than one other call at a time, each join having different parameters. Creating a new join MUST NOT destroy existing joins. If a join is requested but cannot be created without destroying existing joins, the call MUST return a conflict (cancel) error.

+ + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + + +

While calls may generally be joined peer-to-peer in any desirable combination, such an implementation is not necessarily scalable or practical to manage. Rayo, therefore, includes the concept of mixers, which are entities like calls, to which calls or other mixers may be joined in the same way as joining multiple calls directly. A mixer MUST be implicitly created the first time a call attempts to join it, MUST immediately broadcast presence to all controlling parties who have calls joined to it, and must respond to the join command with a reference to the mixer. The server MUST include entity capabilities information in the first presence stanza it sends, in order to advertise the fact that the entity is a mixer, qualified by the node name "urn:xmpp:rayo:mixer:1". A mixer MUST emit events (joined, unjoined) to all controlling parties who have calls joined to it, using the same semantics as joining calls.

+ +

In order to support friendly-named mixers without causing naming collisions between security zones, a server SHOULD represent a mixer internally using some alternative name scoped to the client's security zone and mapped to the friendly name/URI presented to the client for the emission of events and processing of commands. A server MUST NOT allow clients to interact with mixers allocated within other security zones either by observing their status or media.

+ + + + + + + + + + + + + + + + + + + + + ]]> + +

Mixers MUST respect the normal rules of XMPP presence subscriptions. If a client sends directed presence to a mixer, the mixer MUST implicitly create a presence subscription for the client. On receiving unavailable presence, the mixer MUST stop sending events to the client.

+ +

The error conditions on joining a mixer are the same as for calls, as are the unjoin and join modification semantics. Additionally, mixers SHOULD be able to host components just like calls, following the rules defined for each component.

+ + + + + + + + + ]]> + +

If the media server providing the mixer supports active speaker detection, it MUST emit active speaker events to all clients with a presence subscription. Such events MUST indicate the start and end of speaking for a particular call ID joined to the mixer.

+ + + + + + + + + + + + + + + + + ]]> + + +

Once the last participant unjoins from the mixer, the mixer SHOULD be destroyed. When a mixer is destroyed, it MUST send unavailable presence to all entities which have a presence subscription.

+ + +

Components are long-lived elements of a call or mixer which may execute in parallel, have a lifecycle (may send events and/or process commands during their execution, indicate their completion asynchronously) and typically implement media operations. A server SHOULD implement components in such a way that it is acceptable to execute multiple components of the same type or of differing types simultaneously. A server SHOULD implement all core components.

+ +

In the event that a call or mixer receives a command which triggers the execution of a component, it MUST use the normal command handling routine, schedule the component for immediate execution and return a reference to the requesting client as confirmation of the component's creation:

+ + + + + ]]> + + + + + ]]> + +

If a component execution command is received prior to the call being answered, the server MUST NOT answer the call, and SHOULD attempt to use early-media techniques to perform the relevant operation without answering the call. If such early-media is not possible, it MUST return an error indicating that the call state is incorrect (unexpected-request).

+ +

The whole command MUST be parsed up-front, and any applicable validation performed before acknowledgement of the command.

+ + +

There are several reasons why the server might immediately return an error instead of acknowledging the creation of a new component:

+
    +
  • The server does not implement the component.
    • +
  • The server does not implement a particular option value for the component.
    • +
  • Some aspect of the component does not comply with this specification.
    • +
  • The server does not have sufficient resources to create a new component on this call/mixer.
    • +
  • The component would cause a resource conflict with another component on this call/mixer.
    • +
  • The call/mixer is not in the correct state to begin executing the component.
    • +
+ +

If the server does not implement the command/component, it should return a feature-not-implemented (cancel) error:

+ + + + + + + ]]> + +

If the server does not implement a particular option value for the command/component, it should return a feature-not-implemented (modify) error:

+ + + + + + + ]]> + +

If the command does not meet the specification, the server should return a bad-request (modify) error:

+ + + + + + + ]]> + +

If the server does not have sufficient resources to create the component, it should return a resource-constraint (wait) error:

+ + + + + + + ]]> + +

If the server is not able to create the component due to a resource conflict with another component, it should return a resource-constraint (wait) error:

+ + + + + + + ]]> + +

If the server is not able to create the component due to the call being in an incorrect state, it should return an unexpected-request (wait) error:

+ + + + + + + ]]> + + + +

Once acknowleged, the component MUST begin execution according to its particular specification. During its execution, it MAY emit events relevant to its progress, and an implementation MUST be capable of emitting events specified for each component. Any events should be sent inside a directed presence element to the executing party.

+ +

During execution, the component MUST respond to commands addressed to it. Each component has its own set of commands, but all components have the 'stop' command in common. On receipt of the stop command, the component MUST acknowledge that it has been instructed to stop and gracefully cease its execution in whatever way is appropriate to the particular component.

+ + + + + + + ]]> + + +

There are several reasons why a component might return an error instead of acknowledging a command:

+
    +
  • The component does not implement the command.
    • +
  • The component does not implement a particular option value for the command.
    • +
  • Some aspect of the command does not comply with the components specification.
    • +
  • The command is not appropriate for the component at its current stage of execution.
    • +
  • The command is issued by a party other than that which created the component.
    • +
+ +

If the component does not implement the command, it should return a feature-not-implemented (cancel) error:

+ + + + + + + ]]> + +

If the component does not implement a particular option/value for the command, it should return a feature-not-implemented (modify) error:

+ + + + + + + ]]> + +

If some aspect of the command does not comply with the component's spec, it should return a bad-request (modify) error:

+ + + + + + + ]]> + +

If the command is not appropriate for the component's current stage of execution, it should return a unexpected-request (wait) error:

+ + + + + + + ]]> + +

If the command is issued by a party other than the component creator, it should return a conflict (cancel) error:

+ + + + + + + ]]> + + + +

When the component ceases to execute, it MUST send a complete event with a valid reason to the requesting party as directed presence with a type of 'unavailable'.

+ + + + + + ]]> + +

Once a component is completed, or if it did not exist, the server should return an item-not-found (cancel) error as response to any commands:

+ + + + + + + + + + + ]]> + + +

Media output is a core concept in Rayo, and is provided by the output component. The component allows media to be rendered to a call or a mixer, using the server's local media server. A server MUST support audio file playback and MUST support the text/uri-list document format. A server MAY support speech synthesis and MAY support SSML. The component is created using an <output/> command, containing one or more documents to render, along with a set of options to determine the nature of the rendering.

+ + + + + + + +

+ You have 4 new messages. + The first is from Stephanie Williams and arrived at 3:45pm. + + The subject is ski trip + +

+ + ]]]]> + + + + ]]> + + + + + + + + + ]]> + +

The server MUST validate that it has apropriate resources/mechanisms to render the requested document before acknowledging the component creation.

+ + +

In the case that an output component is executed on a call joined to other calls or mixers, the output SHOULD be rendered only to the call and not the joined parties (also known as 'whisper'). In the case that an output component is executed on a mixer, the output should be rendered into the mixer, such that all participants receive the output (also known as 'announce').

+ + + +

The output component implements several commands for manipulating the output during its execution.

+ + +

A client may instruct an output component to pause by sending a pause command. The server MUST cause the media server to pause rendering, maintaining position within the document and allowing for later resumption.

+ + + + + + + ]]> + + + +

A client may instruct an output component to resume rendering if it has previously been paused. The server MUST cause the media server to resume rendering at the last pause marker.

+ + + + + + + ]]> + + + +

A client may instruct an output component to increase the rendering rate by a unit amount, defined by the media server. The server MUST cause the media server to perform the rate increase and acknowledge the command.

+ + + + + + + ]]> + + + +

A client may instruct an output component to decrease the rendering rate by a unit amount, defined by the media server. The server MUST cause the media server to perform the rate decrease and acknowledge the command.

+ + + + + + + ]]> + + + +

A client may instruct an output component to increase the rendering volume by a unit amount, defined by the media server. The server MUST cause the media server to perform the volume increase and acknowledge the command.

+ + + + + + + ]]> + + + +

A client may instruct an output component to decrease the rendering volume by a unit amount, defined by the media server. The server MUST cause the media server to perform the volume decrease and acknowledge the command.

+ + + + + + + ]]> + + + +

A client may instruct an output component to move the play marker forward or back in time by a specified amount before resuming output. The server MUST cause the media to seek as instructed and acknowledge the command.

+

The attributes of the <seek/> element are as follows.

+ + + + + + ]]> + + + + +

The output component does not provide any intermediate events.

+ + + +

The output completion reason MUST be one of the core Rayo reasons, finish (indicating that the document finished rendering naturally) or max-time (indicating that the maximum time was exceeded). Output component completion does not provide any metadata.

+ + + + + + + ]]> + + + + +

Media input is a core concept in Rayo, and is provided by the input component. The component allows input to be collected from a call by way of either DTMF (dual-tone multi-frequency) or ASR (automatic speech recognition), using the server's local media server. A Rayo server MUST support DTMF input and MUST support SRGS XML grammars (application/srgs+xml). A server MAY suport speech input, and MAY support other grammar formats. The component is created using an <input/> command, containing one or more grammar documents by which to control input, along with a set of options to determine the nature of the collection.

+ + + + + + + + + + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + + + + + + + + # + + + * 9 + + + + + ]]]]> + + + + ]]> + +

The server MUST validate that it has appropriate resources/mechanisms to collect the requested input before acknowledging the component creation.

+ + +

In the case that an input component is executed on a call joined to other calls or mixers, the input SHOULD be collected only from the call and not the joined parties. Input components executed on a mixer SHOULD collect and combine input from all participants joined to the mixer.

+ + + +

The input component does not implement any intermediate commands, other than those specified for all components.

+ + + +

The input component does not provide any intermediate events.

+ + + +

The input completion reason MUST be one of the core Rayo reasons, or one of the following reasons. Input component completion provides match metadata for the <finish/> reason only.

+
    +
  • + match (indicating that one of the grammars matched the received input). +
    • +
  • + initial-timeout (indicating that the initial timeout was triggered). +
    • +
  • + inter-digit-timeout (indicating that the inter-digit timeout was triggered). +
    • +
  • + max-silence (indicating that the max-silence timeout was triggered). +
    • +
  • + min-confidence (indicating that the minimum confidence threshold was not reached). +
    • +
  • + no-match (indicating that input was received which did not match any of the specified grammars). +
    • +
+ +

If the media server reports a match to one of the provided grammars, the server MUST present the results of the match to the client by way of a match document in the format requested by the client. A server MUST be capable of supporting NLSML, and may support other formats.

+ + + + + + 1 2 3 4 + + + ]]]]> + + + + ]]> + + + + +

Prompt is a convenience component to wrap input and output components, combine their lifecycles, and allow input to barge-in on an output component in the standard sense.

+ + + + + + + + +

+ Please enter your pin number now. +

+ + ]]]]> + + + + + + + + + + + 0 + 1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 + + + + + + + + # + + + * 9 + + + + + ]]]]> + + + + + ]]> + +

The server MUST validate that it has appropriate resources/mechanisms to render the requested output and collect the requested input before acknowledging the component creation.

+ + +

The prompt component follows the same combined join considerations as output and input components.

+ + + +

The prompt component implements implements all intermediate commands from output and input and behaves the same. If output component commands are executed after the output component has ceased executing, a <unexpected-request> error MUST be returned.

+ + + +

The prompt component emits intermediate events from the nested output and input components.

+ + + +

The input completion reason MUST be one of the core Rayo reasons, or one of the Input component reasons. Events signalling completion of the output components are suppressed.

+ + + + +

Call recording is a core concept in Rayo, and is provided by the record component. The component allows media to be captured from a call or a mixer, using the server's local media server, stored, and made available to clients. The component is created using a <record/> command, with a set of options to determine the nature of the recording.

+ + + + + ]]> + +

The server MUST validate that it has apropriate resources/mechanisms to make the recording before acknowledging the component creation. The component MUST ignore any hints that it does not understand.

+ + +

In the case that a record component is executed on a call joined to other calls or mixers, the direction attibute will specify if the sent audio, received audio, or both will be present in the recording.

+

In send mode, only the audio sent by the caller is recorded.

+

In recv mode, when just joined to the media server, should record TTS, audio playback, etc; when joined to another call, should record that other call's sending audio (probably a human talking) also. When joined to a mixer, should record the audio send from the mixer (other people talking) also.

+

Duplex mode is a combination of send and recv. The platform may mix these or record them as separate channels.

+

When executing a record against a mixer, send mode is not supported. Recv mode records audio from all mixer participants. Duplex is a clone of recv.

+ + + +

The record component implements several commands for manipulating the recording during its execution.

+ + +

A client may instruct a record component to pause by sending a pause command. The server MUST cause the media server to pause recording, allowing for later appending.

+ + + + + + + ]]> + + + +

A client may instruct a record component to resume recording if it has previously been paused. The server MUST cause the media server to resume recording, appending to the original file.

+ + + + + + + ]]> + + + + +

The record component does not provide any intermediate events.

+ + + +

The record completion reason MUST be one of the core Rayo reasons, or one of the following reasons. Record component completion provides recording metadata in all cases.

+
    +
  • + max-duration (indicating that the max duration was reached). +
    • +
  • + initial-timeout (indicating that the initial timeout was triggered). +
    • +
  • + final-timeout (indicating that the final timeout was triggered). +
    • +
+ +

The server MUST present the recording for consumption by the client by way of recording meta-data on the complete reason, including a URI at which the recording may be fetched. It MUST provide uri, duration & size data as specified on the recording element.

+ + + + + + + ]]> + + + + + +

Session termination may occur by one of several methods:

+
    +
  • An inbound call may be redirected by a PCP to some other target.
    • +
  • An inbound call may be rejected by a PCP.
    • +
  • An active call, whether inbound or outbound, may be hung up (gracefully ended) by a DCP.
    • +
  • An active call may be hung up (gracefully ended) by the remote party.
    • +
  • An outbound call may be rejected by the remote party.
    • +
+ +

A call end notification will be dispatched to the PCP if one of the following conditions is met:

+
    +
  • The call has been accepted and has a PCP.
    • +
  • The call is outbound and implicitly has a PCP (the requesting party).
    • +
+ + +

If a client can determine a more appropriate target for an incoming call, it may wish to relay this information to the caller in the form of a URI (eg SIP). The client MUST do this before accepting a call. The target URI must be specified in the 'to' attribute of the redirect element.

+ + +
+
+ + + ]]> + +

The server should send an appropriate redirection instruction to the underlying session.

+ +

If the server is able to successfully relay the redirection to the calling party, it should send an empty IQ result to confirm the command has completed execution:

+ + ]]> + +

If the server is unable to perform the redirect because the call has already been accepted, it should return a not-allowed (cancel) error indicating such:

+ + +
+
+ + + + + + ]]> + + + +

If a client cannot handle an incoming call, it MAY reject it. The client MUST do this before accepting the call. The target URI must be specified in the 'to' attribute of the redirect element.

+ + +
+ + + ]]> + +

The server should reject the underlying session. If the server is able to do so successfully, it should send an empty IQ result to confirm the command has completed execution:

+ + ]]> + +

If the server is unable to perform the rejection because the call has already been accepted, it should return a not-allowed (cancel) error indicating such:

+ + +
+ + + + + + ]]> + + + +

If a client wishes to end a call it should send a hangup command to the call instructing it to do so:

+ + +
+ + + ]]> + +

The server should queue the call for immediate hangup and return a response indicating success of the command:

+ + ]]> + +

The server MUST follow this sequence to hang up a call:

+
    +
  • Terminate all components of the call, and components MUST send a complete event indicating hangup as the cause.
    • +
  • Terminate all joins on the call, sending unjoined events.
    • +
  • Terminate the underlying session.
    • +
+ + + +

The server MUST monitor a call's underlying session and react appropriately in the case that it comes to an end:

+
    +
  • The server MUST determine the reason for the call ending to be one of the appropriate end reasons.
    • +
  • If the call ending was not a result of a hangup command from a client, the server MUST terminate all components on the call, which MUST send a complete event indicating hangup as the cause. The server MUST additionally terminate all joins on the call, sending unjoined events.
    • +
  • The server MUST send an end event (of type unavailable) on behalf of the call, specifying the above determined reason as a child element, to all JIDs to which an offer was sent or from which a command was received.
    • +
  • The server MUST NOT send any more events from a call which has ended and declared itself unavailable.
    • +
  • The server MUST respond to any commands sent to an ended call (or one which never existed) with an item-not-found (cancel) error.
    • +
+ + + + + + + ]]> + + + + + + + + + + + + ]]> + + + + +

In elements which may carry child <header/> elements, a server or client MAY specify several header elements with the same name. In such cases, these MUST be considered to form a collection of ordered values for the key provided.

+ + + +
+
+ + + ]]> + + + + + +

The <header/> element MUST be empty.

+

The attributes of the <header/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
nameA token giving the name by which the header may be known.REQUIRED
valueThe string value of the named header.REQUIRED
+ + + +

Informs the recipient that a new call is available for control and invites it to take control using progress commands below.

+

The <offer/> element MAY contain one or more <header/> elements.

+

The attributes of the <offer/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
toThe target URI for the call. May me a tel URI, SIP URI, a JID (for Jingle) or some other platform-specific addressing mechanism.REQUIRED
fromThe caller ID URI for the call. May be a tel URI, SIP URI, a JID (for Jingle) or some other platform-specific addressing mechanism.OPTIONAL
+ + + +

Indication that an outbound call has begun ringing, or accepted by the remote party.

+

The <ringing/> element MAY contain one or more <header/> elements.

+

The <ringing/> element has no attributes.

+ + + +

Indication that an outbound call has been answered and that the 3rd party negotiation has completed. At this point, the media stream should be open.

+

The <answered/> element MAY contain one or more <header/> elements.

+

The <answered/> element has no attributes.

+ + + +

Indication that the call has come to an end, giving the reason.

+

The <end/> element MUST contain a single end reason element. It MAY also contain one or more <header/> elements.

+

The <end/> element has no attributes.

+ + +

The following are valid end reason elements. Unless otherwise stated, they all MUST be empty, and they do not have any attributes.

+ +
+ +
<hungup/>
+
Indication that the call ended due to a normal hangup by the remote party.
+ + +
<hangup-command/>
+
Indication that the call ended due to a normal hangup triggered by a hangup command.
+ + +
<timeout/>
+
Indication that the call ended due to a timeout in contacting the remote party.
+ + +
<busy/>
+
Indication that the call ended due to being rejected by the remote party subsequent to being accepted.
+ + +
<rejected/>
+
Indication that the call ended due to being rejected by the remote party before being accepted.
+ + +
<error/>
+
Indication that the call ended due to a system error.
+ +
+ + + + +

Instructs the server to send notification to the calling party that the call will be dealt with and that ringing may begin.

+

The <accept/> element MAY contain one or more <header/> elements.

+

The <accept/> element has no attributes.

+ + + +

Instructs the server to pick up an incoming call and connect the media stream.

+

The <answer/> element MAY contain one or more <header/> elements.

+

The <answer/> element has no attributes.

+ + + +

Instructs the calling party that the call will not be accepted and that instead it should try to call the URI indicated in the command.

+

The <redirect/> element MAY contain one or more <header/> elements.

+

The attributes of the <redirect/> element are as follows.

+ + + + + + + + + + + +
AttributeDefinitionInclusion
toThe new target URI for the call to be redirected to.REQUIRED
+ + + +

Instructs the server to reject the call with a given reason.

+

The <reject/> element MUST contain a single reject reason element. It MAY also contain one or more <header/> elements.

+

The <reject/> element has no attributes.

+ + +

The following are valid reject reason elements. Unless otherwise stated, they all MUST be empty, and they do not have any attributes.

+ +
+ +
<decline/>
+
Indicates that the controlling party refused the call for an unspecified reason, such as access control.
+ + +
<busy/>
+
Indicates that the controlling party refused the call due to excess load.
+ + +
<error/>
+
Indicates that the controlling party refused the call because some error occurred.
+ +
+ + + + +

Instructs the server to bring the call to an end naturally.

+

The <hangup/> element MAY contain one or more <header/> elements.

+

The <hangup/> element has no attributes.

+ + + +

Instructs the server to create a new call and surrender control of it to the requesting party.

+

The <dial/> element MAY contain one or more <header/> elements. It MAY contain one or more <join/> elements, instructing the server to join the new call in the indicated manner rather than the default (join to the local media server).

+

The attributes of the <dial/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionInclusionDefault
toIndicates the party to whom the call should be directed.REQUIRED
fromIndicates the caller ID with which the call should appear to originate.OPTIONAL
timeoutIndicates the maximum time allowed for a response to be provided by the third party before the call should be considered to have come to an end.OPTIONAL-1
+ + + +

Instructs the server to join the media streams of the call and the specified party, given direction and media negotiation parameters.

+

The <join/> element MUST be empty.

+

The attributes of the <join/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionInclusionDefault
direction +

Indicates the direction in which the media should flow between the call and the 3rd party. Must be one of the following values:

+
    +
  • "duplex" - Indicates that media should flow in both directions between the parties.
    • +
  • "send" - Indicates that media should only flow from the target call to the third party.
    • +
  • "recv" - Indicates that media should only flow from the third party to the target call.
    • +
+ 		OPTIONALduplex
media +

Indicates the manner in which the server should negotiate media between the two parties. Must be one of the following values:

+
    +
  • "bridge" - Instructs the server to bridge the parties media streams via its local media server.
    • +
  • "direct" - Instructs the server to have the parties negotiate media directly with one another.
    • +
+ 		OPTIONALbridge
call-uriIndicates the 3rd party call URI to which the target call should be joined.REQUIRED unless mixer-name is set. MUST NOT be set if mixer-name is set.
mixer-nameIndicates the mixer name to which the target call should be joined.REQUIRED unless call-uri is set. MUST NOT be set if call-uri is set.
+ + + +

Instructs the server to unjoin the media streams of the call and the specified party.

+

The <unjoin/> element MUST be empty.

+

The attributes of the <unjoin/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
call-uriIndicates the 3rd party call URI from which the target call should be unjoined.REQUIRED unless mixer-name is set. MUST NOT be set if mixer-name is set.
mixer-nameIndicates the mixer name from which the target call should be unjoined.REQUIRED unless call-uri is set. MUST NOT be set if call-uri is set.
+ + + +

Indicates that the call was successfully joined to the specified party.

+

The <joined/> element MUST be empty.

+

The attributes of the <joined/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
call-uriIndicates the 3rd party call URI to which the target call was joined.REQUIRED unless mixer-name is set. MUST NOT be set if mixer-name is set.
mixer-nameIndicates the mixer name to which the target call was joined.REQUIRED unless call-uri is set. MUST NOT be set if call-uri is set.
+ + + +

Indicates that the call ceased to be joined to the specified party.

+

The <unjoined/> element MUST be empty.

+

The attributes of the <unjoined/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
call-uriIndicates the 3rd party call URI from which the target call was unjoined.REQUIRED unless mixer-name is set. MUST NOT be set if mixer-name is set.
mixer-nameIndicates the mixer name from which the target call was unjoined.REQUIRED unless call-uri is set. MUST NOT be set if call-uri is set.
+ + + +

Indicates that a call joined to a mixer with which the controlling party has an events subscription has activated a speech detector, providing its URI.

+

The <started-speaking/> element MUST be empty.

+

The attributes of the <started-speaking/> element are as follows.

+ + + + + + + + + + + +
AttributeDefinitionInclusion
call-uriIndicates the URI of the call which has triggered the speech detector.REQUIRED
+ + + +

Indicates that a call joined to a mixer with which the controlling party has an events subscription has ceased activation of a speech detector, providing its URI.

+

The <stopped-speaking/> element MUST be empty.

+

The attributes of the <stopped-speaking/> element are as follows.

+ + + + + + + + + + + +
AttributeDefinitionInclusion
call-uriIndicates the URI of the call which has triggered the speech detector.REQUIRED
+ + + +

Used to give the address of a newly created resource, either a call or a component.

+

The <ref/> element MUST be empty.

+

The attributes of the <ref/> element are as follows.

+ + + + + + + + + + + +
AttributeDefinitionInclusion
uriGives the URI of the new resource.REQUIRED
+ + + + + +

Instructs a component to come to an end before it completes naturally.

+

The <stop/> element MUST be empty.

+

The <stop/> element has no attributes.

+ + + +

Indicates that the component has come to an end and no further processing will occurr. Gives the reason for the termination.

+

The <complete/> element MUST contain exactly one child element, indicating the reason for the complete event being raised. The reason may be a core complete reason or a reason specific to a particular component.

+

The <complete/> element has no attributes.

+ + +

The following are valid complete reason elements. They all MAY contain further component-specific metadata elements, but they do not have any attributes.

+ +
+ +
<stop/>
+
Indicates that the component came to an end because it was issued a stop command by the controlling party.
+ + +
<hangup/>
+
Indicates that the component came to an end because the call ended.
+ + +
<error/>
+
Indicates that the component came to an end because it encountered an error.
+ +
+ + + + +

An output component is used to instruct the server to generate audible output to a call or mixer.

+ + +

Instructs the server to begin an output component executing on the target call or mixer with the specified document and parameters.

+

The <output/> element MUST contain one or more <document/> elements. A server MUST support the application/ssml+xml content type, but MAY additionally support others.

+

The attributes of the <output/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
start-offsetIndicates some offset through which the output should be skipped before rendering begins.A positive integer in ms.0OPTIONAL
start-pausedIndicates wether or not the component should be started in a paused state to be resumed at a later time.true|falsefalseOPTIONAL
repeat-intervalIndicates the duration of silence that should space repeats of the rendered document.A positive integer in ms.0OPTIONAL
repeat-timesIndicates the number of times the output should be played.An integer greater than 0.1OPTIONAL
max-timeIndicates the maximum amount of time for which the output should be allowed to run before being terminated. Includes repeats.A positive integer in ms or -1 to disable.-1OPTIONAL
rendererIndicates which media engine the server should use to render the Output. The server defines the possible values and falls back to the platform default if not specified.An arbitrary stringOPTIONAL
voiceThe voice with which to speak the requested documentAny voice supported by the TTS engine.OPTIONAL
+ + +

Presents a document for rendering by the output engine.

+

The <document/> element MUST have either a url attribute set OR a content type and a body, containing a document for output rendering enclosed within CDATA.

+

The attributes of the <document/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
urlProvides a URI at which the document is available.Any valid URI scheme supported by the server (eg HTTP).noneREQUIRED unless content-type and content are set
content-typeIndicates the content type of the document provided as CDATA.A document content type tokenREQUIRED unless url is set
+ + + + +

Instructs the server to pause the media output, but not terminate the component.

+

The <pause/> element MUST be empty.

+

The <pause/> element has no attributes.

+ + + +

Instructs the server to continue rendering the output from the last pause marker.

+

The <resume/> element MUST be empty.

+

The <resume/> element has no attributes.

+ + + +

Instructs the server to increase the rate of output by a unit amount.

+

The <speed-up/> element MUST be empty.

+

The <speed-up/> element has no attributes.

+ + + +

Instructs the server to decrease the rate of output by a unit amount.

+

The <speed-down/> element MUST be empty.

+

The <speed-down/> element has no attributes.

+ + + +

Instructs the server to increase the volume of output by a unit amount.

+

The <volume-up/> element MUST be empty.

+

The <volume-up/> element has no attributes.

+ + + +

Instructs the server to decrease the volume of output by a unit amount.

+

The <volume-down/> element MUST be empty.

+

The <volume-down/> element has no attributes.

+ + + +

Instructs the server to move the play marker of the output forward or back in time before resuming output.

+

The <seek/> element MUST be empty.

+

The attributes of the <seek/> element are as follows.

+ + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesInclusion
directionIndicates the direction in time in which to move the play marker.forward|backREQUIRED
amountIndicates the duration by which to move the play marker.A positive integer, in ms.REQUIRED
+ + + +

Indicates that the output component came to an end as a result of reaching the end of the document to be rendered.

+

The <finish/> element MUST be empty.

+

The <finish/> element has no attributes.

+ + + +

Indicates that the output component came to an end due to the maximum time limit being reached.

+

The <max-time/> element MUST be empty.

+

The <max-time/> element has no attributes.

+ + + + +

An input component is used to instruct the server to gather media input from a call or mixer, using either DTMF or ASR.

+ + +

Instructs the server to begin an input detector of the specified mode, with certain attributes, governed by the rules provided in one or more grammar documents.

+

The <input/> element MUST contain one or more <grammar/> elements.

+

The attributes of the <input/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
modeThe method by which to collect input.any|dtmf|speechanyOPTIONAL
terminatorIndicates a terminator token which, when encountered, should cause the input detection to cease.A token stringnoneOPTIONAL
recognizerIndicates the name of the particular input processor to be engaged, used only for routing purposes (eg to choose which MRCP profile to invoke).A token stringnoneOPTIONAL
languageSpecifies the recognition language to the recognizer.Any valid ISO 639‑3 language codeen-USOPTIONAL
initial-timeoutIndicates the amount of time preceding input which may expire before a timeout is triggered.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
inter-digit-timeoutIndicates (in the case of DTMF input) the amount of time between input digits which may expire before a timeout is triggered.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
sensitivityIndicates how sensitive the interpreter should be to loud versus quiet input. Higher values represent greater sensitivity.A decimal value between 0 and 1.0.5OPTIONAL
min-confidenceIndicates the confidence threshold, below which a match is to be considered unreliable.A decimal value between 0 and 1.0OPTIONAL
max-silenceIndicates the maximum period of silence which may be encountered during input gathering before a timeout is triggered.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
match-content-typeIndicates the required response document format.Must support at least application/nlsml+xml, but may support others such as application/emma+xml.application/nlsml+xmlOPTIONAL
+ + +

Provides the grammar document by which the input detection should be governed.

+

The <grammar/> element MUST have either a url attribute set OR a content type and a body.

+

The attributes of the <grammar/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
urlProvides a URI at which the grammar document is available.Any valid URI scheme supported by the server (eg HTTP).noneREQUIRED unless content-type and content are set
content-typeIndicates the content type of the grammar document provided as CDATA.A grammar content type tokennoneREQUIRED unless url is set
+ + + + +

Indicates that the component came to an end due to one of its grammars matching the received input.

+

The <match/> element MUST contain a valid response document within CDATA.

+

The attributes of the <matchr/> element are as follows.

+ + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
content-typeIndicates the content type of the result document provided as CDATA.A result document content type tokenapplication/nlsml+xmlREQUIRED
+ + + +

Indicates that the component came to an end because the initial timeout was triggered.

+

The <initial-timeout/> element MUST be empty.

+

The <initial-timeout/> element has no attributes.

+ + + +

Indicates that the component came to an end because the inter-digit timeout was triggered.

+

The <inter-digit-timeout/> element MUST be empty.

+

The <inter-digit-timeout/> element has no attributes.

+ + + +

Indicates that the component came to an end because the max-silence timeout was triggered.

+

The <max-silence/> element MUST be empty.

+

The <max-silence/> element has no attributes.

+ + + +

Indicates that the component came to an end because the minimum confidence threshold was not reached.

+

The <min-confidence/> element MUST be empty.

+

The <min-confidence/> element has no attributes.

+ + + +

Indicates that the component came to an end because input was received which did not match any of the specified grammars.

+

The <nomatch/> element MUST be empty.

+

The <nomatch/> element has no attributes.

+ + + + +

An prompt component is a mixture of audio output and input, and is used to link the lifecycle of both such input may interrupt output via an arbitrary grammar.

+ + +

Instructs the server to begin an input detector of the specified mode, with certain attributes, governed by the rules provided in one or more grammar documents, while simultaneously rendering output.

+

The <prompt/> element MUST contain an <input/> element and an <output/> element.

+

The attributes of the <prompt/> element are as follows.

+ + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
barge-inWhether or not the input detector is permitted to interrupt the output.true|falsetrueOPTIONAL
+ + + + +

A record component is used to instruct the server to record audible or visual media for temporary or permanent storage.

+ + +

Instructs the server to begin recording input to the call to a file.

+

The <record/> element MAY contain one or more <hint/> elements.

+

The attributes of the <record/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesDefaultInclusion
formatFile format used during recording.A valid format token, such as 'mp3', 'wav', 'h264'. Implementation specific.mp3OPTIONAL
start-beepIndicates whether subsequent record will be preceded with a beep.true|falsefalseOPTIONAL
stop-beepIndicates whether subsequent record stop will be preceded with a beep.true|falsefalseOPTIONAL
start-pausedWhether subsequent record will start in PAUSE mode.true|falsefalseOPTIONAL
max-durationIndicates the maximum duration for the recording.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
initial-timeoutControls how long the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
final-timeoutControls the length of a period of silence after callers have spoken to conclude they finished.Any positive integer in miliseconds, or -1 to disable.-1OPTIONAL
direction +

Indicates the direction of the call to record, meaning which call legs(s) are included in the resulting file, in case the call is joined to another or a mixer.

+ 		+
    +
  • "duplex" - Records both sent and received audio.
    • +
  • "send" - Indicates that only the audio sent from the caller is to be recorded. Not supported when Record is executed against a mixer.
    • +
  • "recv" - Indicates that only and all audio received by the caller is recorded.
    • +
+ 		duplexOPTIONAL
mixWhether all channels (call legs) should be mixed into a single recording channel.true|falsefalseOPTIONAL
+ + +

Optional format-specific encoding hint

+

The <hint/> element MUST be empty.

+

The attributes of the <hint/> element are as follows.

+ + + + + + + + + + + + + + + + +
AttributeDefinitionInclusion
nameThe name of the hint value as expected by the recorder.REQUIRED
valueThe value of the hint provided.REQUIRED
+ + + + +

Instructs the server to cease recording input but to leave the destination open for appending to permit resumption from the same point.

+

The <pause/> element MUST be empty.

+

The <pause/> element has no attributes.

+ + + +

Instructs the server to continue recording input, appending to the same destination.

+

The <resume/> element MUST be empty.

+

The <resume/> element has no attributes.

+ + + +

Provides the result of a recording, as a reference to its location.

+

The <recording/> element MUST be empty.

+

The attributes of the <recording/> element are as follows.

+ + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeDefinitionPossible ValuesInclusion
uriIndicates the URI at which the recording is made available.A valid URIREQUIRED
durationIndicates the duration of the completed recording.A positive integer in milliseconds.REQUIRED
sizeIndicates the filesize of the completed recording.A positive integer in bytes.REQUIRED
+ + + +

Indicates that the component came to an end due to the max duration being reached.

+

The <max-duration/> element MUST be empty.

+

The <max-duration/> element has no attributes.

+ + + +

Indicates that the component came to an end due to no input being detected before the initial-timeout.

+

The <initial-timeout/> element MUST be empty.

+

The <initial-timeout/> element has no attributes.

+ + + +

Indicates that the component came to an end because no input had been detected for the final timeout duration.

+

The <final-timeout/> element MUST be empty.

+

The <final-timeout/> element has no attributes.

+ + + + + +

STRONGLY RECOMMENDED.

+ + +

If an entity supports Rayo, it MUST advertise that fact by returning a feature of "urn:xmpp:rayo:0" &VNOTE; in response to a &xep0030; information request. The response MUST also include features for the application formats and transport methods supported by the responding entity, as described in the relevant specifications.

+ + + + ]]> + + + + + + ]]> + + + + ]]> + + + + + + ]]> +

In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.

+ + +

Rayo is a protocol designed for extensibility. Rayo implementations and deployments have great flexibility in the way they map the Rayo protocol to their underlying transport and media layers, and the functionality they provide around the Rayo interface to the system.

+ +

Further commands and components may also be added to the Rayo protocol in order to extend its capabilities. Such extensions should be submitted to the XSF as ProtoXEPs and use namespaces aligning with the core component namespaces.

+ + +

A server MUST document any cases where its behaviour differs from that in this specification (such as lack of support for particular options/components/etc) and return an error whenever a command is not understood. A server MUST NOT silently ignore any instructions.

+ + + +

Rayo sessions can be resource-intensive. Therefore, it is possible to launch a denial-of-service attack against an entity by burdening it with too many Rayo sessions. Care must be taken to accept sessions only from known entities and only if the entity's device is able to process such sessions.

+ + +

Rayo communications can be enabled through gateways to non-XMPP networks, whose security characteristics can be quite different from those of XMPP networks. For example, on some SIP networks authentication is optional and "from" addresses can be easily forged. Care must be taken in communicating through such gateways.

+ + +

Mere negotiation of a Rayo session can expose sensitive information about the parties (e.g. IP addresses). Care must be taken in communicating such information, and end-to-end encryption should be used if the parties do not trust the intermediate servers or gateways.

+ + + +

This document requires no interaction with &IANA;.

+ + + +

This specification defines the following XML namespaces:

+
    +
  • urn:xmpp:rayo:1
    • +
  • urn:xmpp:rayo:client:1
    • +
  • urn:xmpp:rayo:call:1
    • +
  • urn:xmpp:rayo:mixer:1
    • +
  • urn:xmpp:rayo:ext:1
    • +
  • urn:xmpp:rayo:ext:complete:1
    • +
  • urn:xmpp:rayo:output:1
    • +
  • urn:xmpp:rayo:output:complete:1
    • +
  • urn:xmpp:rayo:input:1
    • +
  • urn:xmpp:rayo:input:complete:1
    • +
  • urn:xmpp:rayo:prompt:1
    • +
  • urn:xmpp:rayo:record:1
    • +
  • urn:xmpp:rayo:record:complete:1
    • +
+

The ®ISTRAR; includes the foregoing namespaces in its registry at &NAMESPACES;, as governed by &xep0053;.

+ + +

If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of XEP-0053.

+ + +

The XMPP Registrar maintains a registry of Rayo components. All component registrations with the exception of those defined above shall be defined in separate specifications (not in this document). Components defined within the XEP series MUST be registered with the XMPP Registrar, resulting in protocol URNs of the form "urn:xmpp:rayo:component_name:X" (where "component_name" is the registered name of the component and "X" is a non-negative integer).

+ ®PROCESS; + + The name of the component. + A natural-language summary of the component. + The document in which the component is specified. + + ]]> + + + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + + A token giving the name by which the header may be known. + + + + + + + The string value of the named header. + + + + + + + + + + Informs the recipient that a new call is available for control and invites it to take control using progress commands below. + + + + + + + The target URI for the call. May be a tel URI, SIP URI, a JID (for Jingle) or some other platform-specific addressing mechanism. + + + + + + + The caller ID URI for the call. May be a tel URI, SIP URI, a JID (for Jingle) or some other platform-specific addressing mechanism. + + + + + + + + Set of header variables sent by the originating party (eg SIP INVITE headers). + + + + + + + + + + + + + + + + + + Indication that an outbound call has begun ringing, or accepted by the remote party. + + + + + + + + + Indication that an outbound call has been answered and that the 3rd party negotiation has completed. At this point, the media stream should be open. + + + + + + + + + Indication that the call has come to an end, giving the reason. + + + + + + + + + Indication that the call ended due to a normal hangup by the remote party. + + + + + + + Indication that the call ended due to a normal hangup triggered by a hangup command. + + + + + + + Indication that the call ended due to a timeout in contacting the remote party. + + + + + + + Indication that the call ended due to being rejected by the remote party subsequent to being accepted. + + + + + + + Indication that the call ended due to being rejected by the remote party before being accepted. + + + + + + + Indication that the call ended due to a system error. + + + + + + + + Set of header variables sent by the remote party along with the indication of the call ending. + + + + + + + + + + + + Instructs the server to send notification to the calling party that the call will be dealt with and that ringing may begin. + + + + + + + + + + + + + + Instructs the server to pick up an incoming call and connect the media stream. + + + + + + + + + + + + + + Instructs the calling party that the call will not be accepted and that instead it should try to call the URI indicated in the command. + + + + + + + The new target URI for the call to be redirected to. + + + + + + + + + + + + + + Instructs the server to reject the call with a given reason. + + + + + + + + + Indicates that the controlling party refused the call for an unspecified reason, such as access control. + + + + + + + Indicates that the controlling party refused the call due to excess load. + + + + + + + Indicates that the controlling party refused the call because some error occurred. + + + + + + + + + + + + + + Instructs the server to bring the call to an end naturally. + + + + + + + + + + + + + + Instructs the server to create a new call and surrender control of it to the requesting party. + + + + + + + Indicates the party to whom the call should be directed. + + + + + + + Indicates the caller ID with which the call should appear to originate. + + + + + + + Indicates the maximum time allowed for a response to be provided by the third party before the call should be considered to have come to an end. + + + + + + + + + Instructs the server to join the new call in the indicated manner rather than the default (join to the local media server). + + + + + + + + + + + + Instructs the server to join the media streams of the call and the specified party, given direction and media negotiation parameters. + + + + + + + + + Indicates the direction in which the media should flow between the call and the 3rd party. + + + + + + + + Indicates that media should flow in both directions between the parties. + + + + + + + Indicates that media should only flow from the target call to the third party. + + + + + + + Indicates that media should only flow from the third party to the target call. + + + + + + + + + + Indicates the manner in which the server should negotiate media between the two parties. + + + + + + + + Instructs the server to bridge the parties media streams via its local media server. + + + + + + + Instructs the server to have the parties negotiate media directly with one another. + + + + + + + + + + + + + + + + Instructs the server to unjoin the media streams of the call and the specified party. + + + + + + + + + Indicates that the call was successfully joined to the specified party. + + + + + + + + + Indicates that the call ceased to be joined to the specified party. + + + + + + + + + Indicates the 3rd party call URI to which the target call should be joined. May not be set if the mixer-name attribute is set. + + + + + + + Indicates the mixer name to which the target call should be joined. May not be set if the call-id attribute is set. + + + + + + + + + + Indicates that a call joined to a mixer with which the controlling party has an events subscription has activated a speech detector, providing its ID. + + + + + + + + + Indicates that a call joined to a mixer with which the controlling party has an events subscription has ceased activation of a speech detector, providing its ID. + + + + + + + + + Indicates the URI of the call which has triggered the speech detector. + + + + + + + + + + Used to give an indication of the identity of a newly created resource, either a call or a component. + + + + + + + Gives the URI of the new resource. + + + + + + + + + + + + + + + + + + + Value is a duration in milleseconds + + + + + + + + + + A value of -1 indicates no timeout + + + + + + + + + + + + + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Instructs a component to come to an end before it completes naturally. + + + + + + + + + Indicates that the component has come to an end and no further processing will occurr. Gives the reason for the termination. + + + + + + + + The reason for component termination. May be either one of the core termination reasons (stop, hangup, error) or a component specific reason. + + + + + + + + + May be any component specific meta-data elements, such as . + + + + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Indicates that the component came to an end because it was issued a stop command by the controlling party. + + + + + + + + + Indicates that the component came to an end because the call ended. + + + + + + + + + Indicates that the component came to an end because it encountered an error. + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + + Provides a URI at which the document is available. Must not be provided if the content-type attribute is set or the element contains a document as CDATA. + + + + + + + Indicates the content type of the document provided as CDATA. Must not be set if the url attribute is set. + + + + + + + + + + + + + Instructs the server to begin an output component executing on the target call or mixer with the specified document and parameters. + + + + + + + Indicates some offset through which the output should be skipped before rendering begins. + + + + + + + Indicates wether or not the component should be started in a paused state to be resumed at a later time. + + + + + + + Indicates the duration of silence that should space repeats of the rendered document. + + + + + + + Indicates the number of times the output should be played. + + + + + + + Indicates the maximum amount of time for which the output should be allowed to run before being terminated. Includes repeats. + + + + + + + Indicates which media engine the server should use to render the Output. + + + + + + + The voice with which to speak the requested document. + + + + + + + + + Provides the document for rendering. + + + + + + + + + + + + Instructs the server to cease rendering output at the current marker and permit resumption from the same point. + + + + + + + + + Instructs the server to continue rendering the output from the last pause marker. + + + + + + + + + Instructs the server to increase the rate of output by a unit amount. + + + + + + + + + Instructs the server to decrease the rate of output by a unit amount. + + + + + + + + + Instructs the server to increase the volume of output by a unit amount. + + + + + + + + + Instructs the server to decrease the volume of output by a unit amount. + + + + + + + + + Instructs the server to move the play marker of the output forward or back in time before resuming output. + + + + + + + Indicates the direction in time in which to move the play marker. + + + + + + + + + + + + + Indicates the duration by which to move the play marker. + + + + + + + + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Indicates that the output component came to an end as a result of reaching the end of the document to be rendered. + + + + + + + + + Indicates that the output component came to an end due to the maximum time limit being reached. + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + + Provides a URI at which the grammar document is available. Must not be provided if the content-type attribute is set or the element contains a grammar document as CDATA. + + + + + + + Indicates the content type of the grammar document provided as CDATA. Must not be set if the url attribute is set. + + + + + + + + + + + + + Instructs the server to begin an input detector of the specified mode, with certain attributes, governed by the rules provided in one or more grammar documents. + + + + + + + + The method by which to collect input. + + + + + + + + + + + + + + Indicates a terminator token which, when encountered, should cause the input detection to cease. + + + + + + + Indicates the name of the particular input processor to be engaged, used only for routing purposes (eg to choose which MRCP profile to invoke). + + + + + + + Specifies the recognition language to the recognizer. + + + + + + + Indicates the amount of time preceding input which may expire before a timeout is triggered. + + + + + + + Indicates (in the case of DTMF input) the amount of time between input digits which may expire before a timeout is triggered. + + + + + + + Indicates how sensitive the interpreter should be to loud versus quiet input. Higher values represent greater sensitivity. + + + + + + + Indicates the confidence threshold, below which a match is to be considered unreliable. + + + + + + + Indicates the maximum period of silence which may be encountered during input gathering before a timeout is triggered. + + + + + + + Indicates the required response document format. + + + + + + + + + Provides the grammar document by which the input detection should be governed. + + + + + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Indicates that the component came to an end due to one of its grammars matching the received input. Provides the NLSML result of the grammar match after any symantic processing which may have been performed. See the NLSML spec for details. + + + + + + + + + Indicates the content type of the result document provided as CDATA. + + + + + + + + + + + + Indicates that the component came to an end because the initial timeout was triggered. + + + + + + + + + Indicates that the component came to an end because the inter-digit timeout was triggered. + + + + + + + + + Indicates that the component came to an end because the max-silence timeout was triggered. + + + + + + + + + Indicates that the component came to an end because the minimum confidence threshold was not reached. + + + + + + + + + Indicates that the component came to an end because input was received which did not match any of the specified grammars. + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Instructs the server to begin an input detector of the specified mode, with certain attributes, governed by the rules provided in one or more grammar documents, while simultaneously rendering output. + + + + + + + + Whether or not the input detector is permitted to interrupt the output. + + + + + + + + + Provides the output component to be executed + + + + + + + Provides the input component to be executed + + + + + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + Instructs the server to begin recording input to the call to a file. + + + + + + + File format used during recording. + + + + + + + Indicates whether subsequent record will be preceded with a beep. + + + + + + + Indicates whether subsequent record stop will be preceded with a beep. + + + + + + + Whether subsequent record will start in PAUSE mode. + + + + + + + Indicates the maximum duration for the recording. + + + + + + + Controls how long the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event. + + + + + + + Controls the length of a period of silence after callers have spoken to conclude they finished. + + + + + + + Indicates the direction of the call to record, as in media produced or received by the calling party. + + + + + + + + Records both sent and received audio. + + + + + + + Indicates that only the audio sent from the caller is to be recorded. Not supported when Record is executed against a mixer. + + + + + + + Indicates that only and all audio received by the caller is recorded. + + + + + + + + + + Whether all channels (call legs) should be mixed into a single recording channel. + + + + + + + + + Optional format-specific encoding hints + + + + + + + The name of the hint value as expected by the recorder. + + + + + + + The value of the hint provided. + + + + + + + + + + + + + + Instructs the server to cease recording input but to leave the destination open for appending to permit resumption from the same point. + + + + + + + + + Instructs the server to continue recording input, appending to the same destination. + + + + + + ]]> + + + + + + + + The protocol documented by this schema is defined at http://rayo.org/xep + + + + + + + + + Indicates the URI at which the recording is made available. + + + + + + + Indicates the duration of the completed recording. + + + + + + + Indicates the filesize (in bytes) of the completed recording. + + + + + + + + + + Indicates that the component came to an end due to the max duration being reached. + + + + + + + + + Indicates that the component came to an end due to no input being detected before the initial-timeout. + + + + + + + + + Indicates that the component came to an end because no input had been detected for the final timeout duration. + + + + + + ]]> + + + + Prior to the development of the Rayo protocol, the most widely-used 3PCC protocols were Asterisk's AGI and AMI. Unfortunately, these protocols have many drawbacks, not least in their inconsistency and relatively poor documentation, but also in that they are poorly secured and lacking in attributes required for significant scalability. Much 3PCC activity is also done using process-internal APIs rather than a wire protocol like XMPP. + +

Rayo was developed to satisfy three main desires:

+
    +
  • To separate the application logic from the back-end call processing infrastructure for large-scale scripting-based hosted voice application platforms. This helps to ensure that the performance of the back-end infrastructure cannot be impacted by the applications controling it, and specifically to allow sandboxing the applications.
    • +
  • To create a platform-agnostic protocol for the control of live media sessions that has been designed from the start for such use.
    • +
  • To enable authenticated, federated, web-scale 3PCC on platforms with APIs only suitable for trusted internal use (Asterisk, FreeSWITCH, etc).
    • +
+ + Initial development of the Rayo specification and its reference implementation was sponsored by Voxeo Labs and Telefónica, with Punchblock being the first client library implementation, as part of the Adhearsion project. Since the beginning of the development process, further implementation efforts have begun on top of Asterisk's AGI/AMI protocols and FreeSWITCH EventSocket, native to FreeSWITCH (mod_rayo), as well as client library implementations in Node/CoffeeScript and Python. + + +

The authors would like to acknowledge the input of teams at Voxeo Labs, Mojo Lingo and Telefónica in the development of the initial specification, and Grasshopper in expanding the implementation landscape.

+ +

Specific individuals who have contributed to the specification or to software significant to its completion include:

+
    +
  • Ben Langfeld
    • +
  • Ben Klang
    • +
  • Chris Rienzo
    • +
  • Jason Goecke
    • +
  • John Dyer
    • +
  • Jose de Castro
    • +
  • Juan de Bravo
    • +
  • Luca Pradovera
    • +
  • Martín Pérez
    • +
+ + From 19999d5c170cffaa9147c33bf850f0e6b3f569d9 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:50:04 -0600 Subject: [PATCH 08/12] protoxep --- inbox/sensor-network-control.xml | 1721 ++++++++++++++++++++++++++++++ 1 file changed, 1721 insertions(+) create mode 100644 inbox/sensor-network-control.xml diff --git a/inbox/sensor-network-control.xml b/inbox/sensor-network-control.xml new file mode 100644 index 00000000..8e2bbd59 --- /dev/null +++ b/inbox/sensor-network-control.xml @@ -0,0 +1,1721 @@ + + + %ents; +]> + + +
+ Sensor Networks - Control + This specification describes how to control devices or actuators in an XMPP-based sensor network. + + This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XEP-0001 + XEP-0004 + XEP-0030 + XEP-0122 + XEP-0137 + XEP-0141 + sensor-data + sensor-network-provisioning + xep-0000-DynamicForms + xep-0000-ColorParameter + + + + NOT_YET_ASSIGNED + + Peter + Waher + peter.waher@clayster.com + peter.waher@jabber.org + http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + + 0.0.1 + 2013-03-27 + pwa + +

First draft.

+ + +
+ +

+ Actuators are devices in sensor networks that can be controlled through the network and act with the outside world. In sensor networks and Internet of Things applications, + actuators make it possible to automate real-world processes. This document defines a mechanism whereby actuators can be controlled in XMPP-based sensor networks, making it + possible to integrate sensors and actuators of different brands, makes and models into larger Internet of Things applications. +

+

+ Note has to be taken, that these XEP's are designed for implementation in sensors, many of which have very limited amount of memory (both RAM and ROM) or resources (processing power). + Therefore, simplicity is of utmost importance. Furthermore, sensor networks can become huge, easily with millions of devices in peer-to-peer networks. +

+

+ Sensor networks contains many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
XEPDescription
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled, based on &xep0004;
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
exi + Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered + in all sensor network implementations where memory and packet size is an issue. +
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsDefines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlThis specification. Defines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
sensor-network-provisioningDefines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
sensor-data + Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. + It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs. +
+ + +

The following table lists common terms and corresponding descriptions.

+
+ +
Actuator
+
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
+ + +
Computed Value
+
A value that is computed instead of measured.
+ + +
Concentrator
+
Device managing a set of devices which it publishes on the XMPP network.
+ + +
Field
+
+ One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. + Fields should be unique within the triple (Node ID, Field Name, Timestamp). +
+ + +
Field Name
+
Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
+ + +
Field Type
+
What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
+ + +
Historical Value
+
A value stored in memory from a previous timestamp.
+ + +
Identification Value
+
A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
+ + +
Localization information
+
Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.
+ + +
Meter
+
A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
+ + +
Momentary Value
+
A momentary value represents a value measured at the time of the read-out.
+ + +
Node
+
+ Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gatewats, etc., are often depicted as nodes and links between sensors (friendships) + are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). + Each Node has a Node ID. +
+ + +
Node ID
+
+ An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted + ID scheme. +
+ + +
Parameter
+
+ Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters + on nodes/devices. Fields are not parameters, and parameters are not fields. +
+ + +
Peak Value
+
A maximum or minimum value during a given period.
+ + +
Precision
+
+ In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision + determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and + delivering field information in sensor networks should always retain the number of decimals in a message. +
+ + +
Sensor
+
+ Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. + Sensor values are reported as fields during read-out. Each sensor has a unique Node ID. +
+ + +
SN
+
Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
+ + +
Status Value
+
A value displaying status information about something.
+ + +
Timestamp
+
Timestamp of value, when the value was sampled or recorded.
+ + +
Token
+
+ A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate + access rights with the provisioning server. +
+ + +
Unit
+
Physical unit of value. Example: MWh, l/s, etc.
+ + +
Value
+
A field value.
+ + +
Value Status
+
Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
+ + +
Value Type
+
Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
+ + +
WSN
+
Wireless Sensor Network, a sensor network including wireless devices.
+ + +
XMPP Client
+
Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.
+ +
+ + +

+ Control in sensor networks is about setting output values. To make the implementation simple, it is assumed that control of a device can be made using a single message. + If only a simple set operation is requested, a <message> stanza can be sent. If an acknowledgement (ACK) of the operation (or Not-acknowledgement NACK) of the operation + is desired, an <iq> stanza can be used instead. +

+

+ To set control parameters in a device, the set command is sent to the device. The set command allows for two different ways of setting control parameters: +

+
    +
  • Using strongly typed parameters. This way performs best in EXI compression and automation.
    • +
  • Using a weakly typed data form. This might be better for manually setting control parameters, since it allows the device to give the user a better user interface explaining + available control parameters.
    • +
+

+ What type of control parameters there are available in different types of devices is described in + + XEP-xxxx: Sensor Networks - Interoperability <xep-0000-SN-Interoperability.html> + . +

+

+ If the device is a concentrator, as defined in + + XEP-xxxx: Sensor Networks - Concentrators <xep-0000-SN-Concentrators.html> + , an handles multiple nodes behind it, which node(s) to control is defined using node elements. If not a concentrator, + the use of node elements is not necessary, and control commands are sent directly to the device itself. +

+ + +

+ Following is an example of a control command sent using a message stanza: +

+ + + + + + ]]> + +

+ Note that any response is supressed when sending a message stanza, regardless if the desired control command could be executed or not. The following example shows how the same + control command could be issued using an IQ stanza instead: +

+ + +

+ Following is an example of a control command sent using an iq stanza: +

+ + + + + + + + + + ]]> + +

+ In the following use cases, often a message stanza will be used to illustrate the point. However, the same operation could equally well be used using an iq stanza instead. +

+ + +

+ By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed. + Following is an example of a control command sent using an iq stanza, where the receiver reports an error back to the caller: +

+ + + + + + + + + + Invalid parameter type. + + ]]> + + + + +

+ The following sub-sections illustrate how to set parameters of different types in a device. +

+ +

+ Setting single boolean-valued control parameters is a common use case, for instance when controlling digital outputs. The following example shows how a boolean value + can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. The following example shows how a 32-bit integer value + can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting single integer-valued control parameters is a common use case, for instance when controlling analog outputs. Even though 32-bit integers may cover most control needs, + it might in some cases be limiting. Therefore, a 64-bit control parameters can be created. The following example shows how a 64-bit integer value + can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting single string-valued control parameters is a common use case, for instance when controlling text displays. The following example shows how a string value + can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting single double-valued control parameters can be an alternative form of controlling analog outputs for instance. The following example shows how a double value + can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting date-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. + The following example shows how a date value can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. + The following example shows how a time value can be set in a device. +

+ + + + + ]]> + + + +

+ Setting date & time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. + The following example shows how a date & time value can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting time-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. + The following example shows how a time value can be set in a device. +

+ + + + + ]]> + + + +

+ Setting duration-valued control parameters might be necessary when timing is an issue. Often it forms part of a larger context. + The following example shows how a duration value can be set in a device. +

+ + + + + + ]]> + + + +

+ Setting single color values in a device can occur in instances where color or lighting is important. Sometimes color is set using enumerations (string-valued + or integer-valued parameters), and sometimes as a color property. The following example shows how a color value can be set in a device. +

+ + + + + + ]]> + + + +

+ Often, setting a single control parameter is not sufficient for a control action. In these cases, setting multiple control parameters at once is necessary. + The set command makes this easy however, since it allows for any number of control parameters to be set at once, as the following example shows: +

+ + + + + + + ]]> + +

+ Sometimes the order of control parameters are important in the device, and sometimes the parameters form part of a whole. It depends on the context of the device. + In the above example, the order is important. When the OutputPercent control parameter is set, it will start to fade in or out to the desired setting (10%), using the + fade time set previously. If the FadeTimeMilliseconds control parameter would have been set after the OutputPercent parameter, the fading would have been started using + the previous setting, which might be unknown. +

+

+ The order of control parameters to use depends on the device. The Control Form lists available control parameters of the device in the + order they are expected to be sent to the device. The XEP xep-0000-SN-Interoperability details what control parameters + must be available for different interfaces, and if the order of control parameters is important. +

+ + + + +

+ A client can get a control form containing available control parameters of the device. This is done using the getForm command, + as is shown in the following example: +

+ + + + + + + + + Dimmer + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + Time in milliseconds used to fade the light to the desired level. + 300 + + + + + + + Dimmer output, in percent. + 100 + + + + + + + If the dimmer is turned on or off. + true + + + + + ]]> + +

+ IMPORTANT: The device MUST mark all control parameters in the form as notSame, as defined in + + XEP-xxxx: Dynamic Data Forms <xep-0000-DynamicForms.html> + . If an end user would open the control form and press OK (submitting the form) without having entered a value, no value + would be written, and no action taken. If only a few parameter would be edited, only those parameters would be sent to the device + and only the corresponding actions taken. +

+

+ All parameters in the form MUST also have validation rules defined according to XEP-0122, + specifically validation data types and ranges where appropriate. This to give type information to the client, which the client later can use to send + typed control commands directly, without the need to get and send data forms to the device to control it. +

+

+ Also, the device SHOULD group control parameters that should be written together using pages and sections, as described in + XEP-0141. Parameters + MUST also be ordered in a way so that when set in that order using the typed commands, the corresponding control actions can be successfully executed. +

+

+ Note: There's a difference between node parameters, as described in XEP xep-0000-SN-Concentrators, + and control parameters as described in this document. For more information about this, please see + Difference between node parameters and node control parameters. +

+ + +

+ A device can reject a control form request. It does this returning an error iq stanza, and detailing the error in the result + attribute of the getformResponse element, as is shown in the following example: +

+ + + + + + + + ]]> + + + +

+ Control actions can be requested by submitting a full or partial control form back to the device. Control parameters not edited MUST not be included + in the form, and the device in turn MUST ONLY invoke control actions corresponding to the parameters returned in the form. +

+

+ The following example shows how control actions can be requested submitting a control parameters form to the device: +

+ + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + 500 + + + 10 + + + + + + + + ]]> + +

+ In this example, the FadeTimeMilliseconds and OutputPercent control parameters are sent, while the MainSwitch control parameter is left as is. Fading is therefore + parformed only if the dimmer is switched on. +

+ + +

+ A device can reject a control form submission. It does this returning an error iq stanza, and detailing the error in the result + attribute of the setResponse element. If there are errors in the form, details are listed using error elements in the response, + as is shown in the following example: +

+ + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + 500 + + + 200 + + + + + + + + Invalid parameter value. + + ]]> + + + + +

+ Controlling devices behind a concentrator can be done by specifying what device(s) to control using node elements within the + command elements sent to the concentrator. The following sub-sections show examples of how this is done. +

+ +

+ To send a control message to a specific node behind a concentrator, the node element can be used to identify the node, + as is shown in the following example: +

+ + + + + + + ]]> + + + +

+ The client can send the same control command to multiple nodes behind a concentrator by simply adding more node elements in the request, + as is shown in the following example: +

+ + + + + + + + + + ]]> + + + +

+ By using an IQ stanza, the caller can receive an acknowledgement of the reception of the command, or error information if the command could not be processed. + When sending a control command to multiple nodes at a time the device must validate all parameters against all nodes before taking any control action. If + validation fails, an error message is returned and no control action is taken. The following example shows an example of an erroneous control message made to + multiple nodes on a device: +

+ + + + + + + + + + + + + + + + + + Invalid parameter type. + + ]]> + + + +

+ A client can get a control form containing available control parameters common between a set of nodes controlled by the concentrator. This is done + adding a sequence of node elements to a getForm command sent to the concentrator, as is shown in the following example: +

+ + + + + + + + + + + + + + DigitalOutput1, DigitalOutput2, ... + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + If the digital output is high (checked) or low (uncheckd). + true + + + + + ]]> + +

+ Note that only parameters that are common between the nodes defined in the request must be returned. However, all parameters must have the + >notSame flag set, regardless of current output status. +

+ + +

+ A device can reject a control form request. It does this returning an error iq stanza, and detailing the error in the result + attribute of the getformResponse element. The following example shows the device rejecting a control form request, because it does not support + the handling of common parameters between multiple nodes: +

+ + + + + + + + + + + + + ]]> + + + +

+ You set a control form to multiple nodes controlled by a concentrator by adding node elements to the set + command sent to the concentrator, as is shown in the following example: +

+ + + + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + true + + + + + + + + ]]> + + + +

+ A device can reject a control form submission. It does this returning an error iq stanza, and detailing the error in the result + attribute of the setResponse element. The following example shows the device rejecting a control form submission because one of the control parameters, + even though it exists on all nodes, is not of the same type on all nodes. +

+ + + + + + + + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + true + + + + + + + + Invalid type + + ]]> + + + + + + +

+ If a client wants to know the current status of control parameters, it must perform a readout of Momentary and Status values + from the device, according to + + XEP-xxxx: Sensor Data <sensor-data.html> + , and from the returned set of values take the current control parameter value according to the following rules, ordered by priority: +

+
    +
  • +

    + If there's a field marked as momentary value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible + field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of + the control parameter. +

    +
    • +
  • +

    + If there's a field marked as status value, with an unlocalized field name equal to the unlocalized control parameter name and having a compatible + field value type (see table below) and a status field without the missing flag set, the value of the field should be considered the current value of + the control parameter. +

    +
    • +
+

+ Even though getting the the control form could provide the client with a quicker and easier way of retrieving control parameter values, the form is not + guaranteed to contain correct current values. In some cases, retrieving current values might take time and only be retrieved using an asynchronous read-out + process described in this section. +

+

+ The following table shows how corresponding field values should be converted to the corresponding control parameter value based on field type (x-axis) and + control parameter type (y-axis). N/A means conversion has no meaning and types are not compatible. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
numericstringbooleandateTimetimeSpanenum
boolean!=0N/AxN/AN/AN/A
colorN/ARRGGBBN/AN/AN/AN/A
dateN/A(1)N/ADate partN/AN/A
dateTimeN/A(2)N/AxN/AN/A
doublex(3)Z2N/AN/AN/A
durationN/A(4)N/AN/AxN/A
intx(5)Z2N/AN/AN/A
longx(5)Z2N/AN/AN/A
string(6)xxs:booleanxs:dateTimexs:durationx
timeN/A(7)N/ATime part(8)N/A
+

+ The following table lists notes with details on how to do conversion, if in doubt. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NoteDescription
(1) + The client should try to convert the string to a date value, first according to the format specified by the XML data type xs:date, and if not possible + by RFC 822. +
(2) + The client should try to convert the string to a date & time value, first according to the format specified by the XML data type xs:dateTime, and if not possible + by RFC 822. +
(3) + The client should try to convert the string to a double-precision floating-point value, first according to the format specified by the XML data type xs:double, + and if not possible using system-local string to floating-point conversion using local decimal and throusand separator settings. +
(4) + The client should try to convert the string to a duration value, first according to the format specified by the XML data type xs:duration, + and if not possible using the XML data type xs:time. +
(5)The client should try to convert the string to an integer value according to the corresponding XML data type formats xs:int and xs:long.
(6) + The numeric field value consists of three parts: Numeric value, number of decimals and optional unit. If no unit is provided, only the numeric value should + be converted to a string (compatible with the XML data type xs:double), using exactly the number of decimals provided in the field. If a unit is provided + (non-empty string) it must not be appended to the value, if the value is to be used for control output. For presentation purposes however, a space could be + appended to the number and the unit appended after the space. +
(7) + The client should try to convert the string to a time value according to the format specified by the XML data type xs:time. +
(8) + A timeSpan field value contains a xs:duration value. The xs:duration has a larger domain than xs:time, and contains all xs:time values, but xs:time does + not contain all possible xs:duration values. So, conversion of an xs:duration value to an xs:time value should be performed only if a duration lies + between 00:00:00 and 23:59:59. +
xUse the canonical conversion method.
Z2true = 1, false = 0.
N/ANot applicable. Conversion has no meaning. Value types are not compatible.
!=0Nonzero = true, Zero = false.
RRGGBBA string of six hexadecimal characters, the first two the red component of the color, the next two the green component and the last two the blue component.
Date partOnly the date part of the xs:dateTime value should be used.
Time partOnly the time part of the xs:dateTime value should be used.
xs:booleanConversion to a string should follow the rules specified for the XML datatype xs:boolean.
xs:dateTimeConversion to a string should follow the rules specified for the XML datatype xs:dateTime.
xs:durationConversion to a string should follow the rules specified for the XML datatype xs:duration.
+

+ Note: the namespace prefix xs is here supposed to be linked with the XML Schema namespace + http://www.w3.org/2001/XMLSchema. +

+ + +

+ A node defined in a concentrator, as defined by xep-0000-SN-Concentrators.html, supporting control has + two sets of parameters that are different: First a set of node parameters and then a set of control parameters. +

+

+ Node parameters are defined by the node type in the concentrator, as described in xep-0000-SN-Concentrators.html, + and they are typically used by the concentrator to define the node and how to communicate or interact with the underlying device. The important part here is to know + that the node parameters are maintained by the concentrator, not the underlying device. +

+

+ Control parameters however, are parameters that reside on the underlying device. When set, they change the actual state or behaviour of the underlying device. + The connection to the device however, controlled by the concentrator, remains unchanged by such a control parameter update. +

+ + +

+ Many control actions avilable in a device can be controlled using only one control parameter. If a device only publishes such control parameters, the order + of control paramters is not that important. +

+

+ However, there are many control actions that require the client to set multiple control parameters at the same time, for the device to have a complete understanding + what the client wants to do. +

+

+ XEP-0141 defines a way to group parameters in a data form by including the concept of pages and sections. + Even though these pages and sections are used for layout purposes, it should be used by devices to mark parameters that should be used together to perform control actions. +

+

+ The following set of rules should be adhered to, by devices as well as clients, to minimize confusion and resulting errors: +

+
    +
  • +

    + Control parameters should be listed in control forms in the order the device expects the client to write them back. +

    +
    • +
  • +

    + Clients should set control parameters in the order they are listed in the corresponding control forms. +

    +
    • +
  • +

    + Control actions that require multiple control parameters should report these together, grouped by pages or sections within pages, + to make clear that the parameters belong together. +

    +
    • +
  • +

    + For control actions requiring multiple control parameters, devices should strive to publish default values for all parameters involved. + These default values should then be used by the device if a client happens to write only a subset of the control parameters required for + a control action. The default value could be the current state of the parameter. +

    +
    • +
+

+ Note however, that one cannot always make the assumption that parameters on the same page or same section in a control form belong to the same control action. + For instance, a PLC with 16 digital outputs might publish a control form containing a single page with 16 check boxes on (boolean parameters), that can be + controlled individually. +

+

+ To solve the problem of grouping parameters together, so a client can know which parameters belong together, a new element is defined that can be used in + data forms: parameterGroup. It is optional, but can be added to control parameters in forms, as a way to tell the client that parameters + having the same parameterGroup belong together and should be written together. The following example illustrates this. +

+ + + + + + + + + Spotlight + + + + + + + + + 325ED0F3-9A9A-45A4-9634-4E0D41C5EA06 + + + If the spotlight is turned on or off. + true + + + + Horizontal angle of the spotlight. + 0 + + + + + + + + Elevation angle of the spotlight. + 0 + + + + + + + + + ]]> + +

+ The above example informs the client that the two parameters HorizontalAngle and ElevationAngle should be written together to control a control action + (named direction). +

+

+ For more information about common control actions and their parameters, see xep-0000-SN-Interoperability.html, + which defines a set of interoperable interfaces and their abilities. +

+ + +

+ Nodes behind a concentrator, as defined in xep-0000-SN-Concentrators.html, have an additional means of + publishing control interfaces: Node Commands. +

+

+ However, there are many differences between Node Commands and Control Parameters, as shown in the following list: +

+
    +
  • +

    + Node Commands are defined by the node type in the concentrator, and not by the device itself. +

    +
    • +
  • +

    + Node Commands may do many different things, not only performing control actions. +

    +
    • +
  • +

    + Parametrized Node Commands require the client to always get a parameter data form, and write back values. There's no way to send simple + control messages using Node Commands. +

    +
    • +
  • +

    + Node Commands can be partitioned, grouped and sorted separately. +

    +
    • +
  • +

    + Each Parametrized Node Command has a separate parameter form, which makes grouping of parameters normal. +

    +
    • +
  • +

    + Node Commands are only available for nodes controlled by a concentrator. +

    +
    • +
+

+ If implementing a device with many complex control actions (like an advanced PLC), consideration should be made to divide the device into logical groups and + implement the concentrators interface as well. Then the more complex control actions could be implemented as Node Commands instead of control actions + as defined in this document, and implementing the simpler more intuitive control actions as described in this document. +

+ + +

+ If control interaction is performed in a context of delegated trust, as defined in the Sensor Network Provisioning XEP + + XEP-xxxx: Sensor Networks - Provisioning <sensor-network-provisioning.html> + , tokens should always be included in all calls. This to allow devices to check privileges with provisioning servers. +

+

+ The set and getForm commands support the following token attributes: +

+
    +
  • + serviceToken +
    • +
  • + deviceToken +
    • +
  • + userToken +
    • +
+

+ For more information about provisioning, see sensor-network-provisioning.html. +

+ + +

+ Most examples in this document have been simplified examples where a few devices containing a few control parameters have been used. However, in many cases large subsystems with + very many actuators containing many different control actions have to be controlled, as is documented in xep-0000-SN-Concentrators.html. + In such cases, a node may have to be specified using two or perhaps even three ID's: a sourceId identifying the data source controlling the device, a possible + cacheType narrowing down the search to a specific kind of node, and the common nodeId. For more information about this, see + xep-0000-SN-Concentrators.html. +

+

+ Note: For cases where the nodeId is sufficient to uniquelly identify the node, it is sufficient to provide this attribute in the request. + If there is ambiguity in the request, the receptor must treat the request as a request with a set of nodes, all with the corresponding nodeId as requested. +

+ + + + +

+ All timestamps and dateTime values use the XML data type xs:dateTime to specify values. These values include a date, an optional time and an optional time zone. +

+

+ Note: If time zone is not available, it is supposed to be undefined. The client reading the sensor that reports fields without time zone information + should assume the sensor has the same time zone as the client, if not explicitly configured otherwise on the client side. +

+

+ If devices report time zone, this information should be propagated throughout the system. Otherwise, comparing timestamps from different time zones will be impossible. +

+ + +

+ Control commands sent using IQ stanzas instead of messages, should consider using the xml:lang attribute to specify the desired language + used (if possible) when returning information back to the caller, like error messages, localized control forms, etc. +

+ + + +

+ Controlling devices in a large sensor network is a hackers wet dream. Therefore, consideration of how network security is implemented should not be underestimated. + The following sections provide some general items that should be considered. +

+ +

+ Consider to always use an encrypted connection with any XMPP Server used in the network. Also, make sure the server is properly authenticated and any server + certificate properly validated. +

+

+ Control commands should only be accepted by trusted parties. A minimum is to make sure only authenticated and validated clients (friends) can perform control actions + on the device. +

+ + +

+ Consider using provisioning servers to allow for detailed control of who can do what in a sensor network. Implementing proper provisioning support decreases + the risk for adverse effects, not only from intentional hacking, but also from unintentional errors. +

+

+ If using delegated trust, make sure the provisioning servers are properly authenticated and validated before trusting them. +

+

+ More information about provisioning can be found in sensor-network-provisioning.html. +

+ + + +

This document requires no interaction with &IANA;.

+ + +

REQUIRED.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + +

Thanks to Joachim Lindborg for all valuable feedback.

+ + From cd5d7ff0e5ab933679b65cfeede7a569bf767690 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 13:50:08 -0600 Subject: [PATCH 09/12] protoxep --- inbox/sensor-network-concentrators.xml | 5006 ++++++++++++++++++++++++ 1 file changed, 5006 insertions(+) create mode 100644 inbox/sensor-network-concentrators.xml diff --git a/inbox/sensor-network-concentrators.xml b/inbox/sensor-network-concentrators.xml new file mode 100644 index 00000000..3892226c --- /dev/null +++ b/inbox/sensor-network-concentrators.xml @@ -0,0 +1,5006 @@ + + + + + %ents; +]> + + +
+ Sensor Networks - Concentrators + This specification describes how to manage and get information from concentrators of devices over XMPP networks. + + This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). + Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. + ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## + In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. + + This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). + + + xxxx + ProtoXEP + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0004 + XEP-0030 + XEP-0122 + XEP-0137 + XEP-0141 + sensor-data + sensor-network-provisioning + xep-0000-DynamicForms + xep-0000-ColorParameter + + + + NOT_YET_ASSIGNED + + Peter + Waher + peter.waher@clayster.com + peter.waher@jabber.org + http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + + 0.0.1 + 2013-03-20 + pwa + +

First draft.

+ + +
+ +

+ Concentrators are devices in sensor networks, concentrating the management of a sub set of devices to one point. They can be small (for example: PLC:s managing a small + set of sensors and actuators), medium-sized (for example: mid-level concentrators, controlling branches of the network, islands, perhaps using separate communication protocols), + large (for example: entire sub-systems, perhaps managed by a separate child/partner organization) to massive (for example: The entire top-level system, smart-grid, IoT network). +

+

+ Even though this XEP is generally written and can be used by other implementations not based on sensor networks, much of the requirements used to define this specification + comes from requirements used in sensor networks and Internet of Things applications and infrastructure. +

+

+ This specification will define the following aspects of a general concentrator profile, that can handle all different types of concentrators available in sensor network architectures: +

+
    +
  • + A concentrator works with multiple data sources. Effective management of data sources and their contents is a vital part of this XEP. +
    • +
  • The ability to work with massive quantities of entities.
    • +
  • Effective synchronization of contents between interested parties.
    • +
  • Effective ways to interact with entities controlled by the concentrator.
    • +
+ +

+ Even though there are technologies available in forms of XEPs that solve parts of the above mentioned problem, they do not provide sufficient support. The following paragraphs will + take the time to list why different technologies are not applicable. +

+ +

+ This XEP defines tree structures for nodes in different data sources. &xep0060; defines a model where a tree structure of nodes is published and users can browse this + tree structure. Furthermore, it allows the possibility to publish items on these nodes as well as syndicalization of this information. +

+

+ This XEP also defines data sources (in a tree structure). These data sources contain nodes. &xep0248; defines a structure called a node collection, a structure that + allows the creation of collections containing loosely coupled nodes. +

+

+ Even though this document defines tree structures of data, it is not however based on XEP-0060. There are multiple reasons for this: +

+
    +
  • + The structures defined in this specification do not include items to publish for each node. +
    • +
  • + We want to be able to use XEP-0060 in parallel to this specification, for the purpose of publishing sensor data. + More information about this is found in xep-0000-SN-PubSub.html. +
    • +
  • + For massive systems (hundreds of thousands, or millions, of nodes behind a concentrator, its vitally important to be able to manage sets of nodes directly + (for example: Edit multiple nodes at once). Many of the operations in XEP-0060 only allow for operations of singular nodes. Furthermore, many simple operations + require multiple messages per node. This document defines way to operate of sets of nodes simultaneously, as well as ways to perform operations with a smaller + number of operations. +
    • +
  • + In this document, nodes have specific functions, controlled by a specific Node Type. Different Node Types have different parameter sets, different options, commands, + capabilities, etc. XEP-0060 does not differ between node types. There, nodes are only a structural way to sort data into a tree graph. +
    • +
  • + In this document, nodes have real-time status, like errors, warnings, etc. +
    • +
+ + +

+ XEP-0248 defines the concept of node collections and syndicalization of information from nodes in these collections. But XEP-0248 is not used in this specification. + There are multiple reasons: +

+
    +
  • + We want to be able to use XEP-0248 in parallel to this specification, for the purpose of publishing sensor data. + More information about this is found in xep-0000-SN-PubSub.html. +
    • +
  • + Node IDs are not necessarily unique by themselves in the system. This document defines a uniqueness concept based on a triple of data: (Data Source ID, Cache Type, Node ID). This + means that Nodes must have IDs unique within a given Cache Type, within a given data source. +
    • +
  • + We need to expand on types of events generated from a data source, to make them adhere to the particulars of nodes as defined in this specification. +
    • +
  • + Data sources own their nodes. XEP-0248 define a loosely coupled structure with references to nodes. In this document, a data source is the owner of all nodes + contained in it. +
    • +
+ + +

+ &xep0050; defines how ad-hoc commands can be implemented and how clients can use such commands to interact with underlying logic. But XEP-0050 is not used in this specification. + There are multiple reasons: +

+
    +
  • + We want to be able to use XEP-0050 for other types of commands, than commands defined in this specification. Generally, XEP-0050 is used to implement + system-wide commands. +
    • +
  • + Commands defined in this specification are context sensitive, i.e. they depend on the type of node and the context of the node on which the act. +
    • +
  • + It is a requirement to be able to execute commands on sets of nodes directly. +
    • +
  • + Since commands have to be context sensitive, a large concentrator system may have hundreds or thousands of different commands, making it impossible to create + context sensitive GUI's using XEP-0050. +
    • +
  • + Dialog types used for Ad-Hoc-commands are not sufficient. First, dynamic dialogs are required in the general case. + (XEP xep-0000-DynamicForms.html define how to create dynamic forms.) Furthermore, the + wizard style type of dialogs used for more complex dialogs in ad-hoc commands, are difficult to automate. +
    • +
+ + + +

+ Sensor networks contains many different architectures and use cases. For this reason, the sensor network standards have been divided into multiple XEPs according to the following table: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
XEPDescription
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled, based on &xep0004;
XEP-0000-DynamicFormsDefines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
exi + Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not a sensor network specific XEP, this XEP should be considered + in all sensor network implementations where memory and packet size is an issue. +
xep-0000-SN-BatteryPoweredSensorsDefines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
xep-0000-SN-ConcentratorsThis specification. Defines how to handle architectures containing concentrators or servers handling multiple sensors.
xep-0000-SN-ControlDefines how to control actuators and other devices in sensor networks.
xep-0000-SN-DiscoveryDefines the peculiars of sensor discovery in sensor networks. Apart from discovering sensors by JID, it also defines how to discover sensors based on location, etc.
xep-0000-SN-EventsDefines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
xep-0000-SN-InteroperabilityDefines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
xep-0000-SN-MulticastDefines how sensor data can be multicast in efficient ways.
sensor-network-provisioningDefines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
xep-0000-SN-PubSubDefines how efficient publication of sensor data can be made in sensor networks.
sensor-data + Provides the underlying architecture, basic operations and data structures for sensor data communication over XMPP networks. + It includes a hardware abstraction model, removing any technical detail implemented in underlying technologies. This XEP is used by all other sensor network XEPs. +
+ + +

The following table lists common terms and corresponding descriptions.

+
+ +
Actuator
+
Device containing at least one configurable property or output that can and should be controlled by some other entity or device.
+ + +
Computed Value
+
A value that is computed instead of measured.
+ + +
Concentrator
+
Device managing a set of devices which it publishes on the XMPP network.
+ + +
Data Source
+
+ A Data source contains a collection of nodes. Three types of data sources exist: Singular, Flat and Tree. Singular data sources only include one object. + Flat data sources contain a list of objects and Tree data sources contain nodes formed as a tree graph with one root element. +
+ + +
Field
+
+ One item of sensor data. Contains information about: Node, Field Name, Value, Precision, Unit, Value Type, Status, Timestamp, Localization information, etc. + Fields should be unique within the triple (Node ID, Field Name, Timestamp). +
+ + +
Field Name
+
Name of a field of sensor data. Examples: Energy, Volume, Flow, Power, etc.
+ + +
Field Type
+
What type of value the field represents. Examples: Momentary Value, Status Value, Identification Value, Calculated Value, Peak Value, Historical Value, etc.
+ + +
Historical Value
+
A value stored in memory from a previous timestamp.
+ + +
Identification Value
+
A value that can be used for identification. (Serial numbers, meter IDs, locations, names, etc.)
+ + +
Localization information
+
Optional information for a field, allowing the sensor to control how the information should be presented to human viewers.
+ + +
Meter
+
A device possible containing multiple sensors, used in metering applications. Examples: Electricity meter, Water Meter, Heat Meter, Cooling Meter, etc.
+ + +
Momentary Value
+
A momentary value represents a value measured at the time of the read-out.
+ + +
Node
+
+ Graphs contain nodes and edges between nodes. In Sensor Networks, sensors, actuators, meters, devices, gateways, etc., are often depicted as nodes and links between sensors (friendships) + are depicted as edges. In abstract terms, it's easier to talk about a Node, than have to list different types of nodes possible (sensors, actuators, meters, devices, gateways, etc.). + Each Node has a Node ID. Nodes belong to a data source, and all nodes have a Node Type. Some nodes have a parent node, and some nodes have child nodes. Nodes with the same + parent nodes a called sibling nodes. +
+ + +
Node ID
+
+ An ID uniquelly identifying a node within its corresponding context. If a globally unique ID is desired, an architechture should be used using a universally accepted + ID scheme. +
+ + +
Node Type
+
Each node has a Node Type. The Node Type defines the functionality of the node in the system.
+ + +
Parameter
+
+ Readable and/or writable property on a node/device. The XEP xep-0000-SN-Concentrators deals with reading and writing parameters + on nodes/devices. Fields are not parameters, and parameters are not fields. +
+ + +
Peak Value
+
A maximum or minimum value during a given period.
+ + +
Precision
+
+ In physics, precision determines the number of digits of precision. In sensor networks however, this definition is not easily applicable. Instead, precision + determines, for example, the number of decimals of precision, or power of precision. Example: 123.200 MWh contains 3 decimals of precision. All entities parsing and + delivering field information in sensor networks should always retain the number of decimals in a message. +
+ + +
Sensor
+
+ Device measuring at least one digital value (0 or 1) or analog value (value with precision and physical unit). Examples: Temperature sensor, pressure sensor, etc. + Sensor values are reported as fields during read-out. Each sensor has a unique Node ID. +
+ + +
SN
+
Sensor Network. A network consisting, but not limited to sensors, where transport and use of sensor data is of primary concern. A sensor network may contain actuators, network applications, monitors, services, etc.
+ + +
Status Value
+
A value displaying status information about something.
+ + +
Timestamp
+
Timestamp of value, when the value was sampled or recorded.
+ + +
Token
+
+ A client, device or user can get a token from a provisioning server. These tokens can be included in requeests to other entities in the network, so these entities can validate + access rights with the provisioning server. +
+ + +
Unit
+
Physical unit of value. Example: MWh, l/s, etc.
+ + +
Value
+
A field value.
+ + +
Value Status
+
Status of field value. Contains important status information for Quality of Service purposes. Examples: Ok, Error, Warning, Time Shifted, Missing, Signed, etc.
+ + +
Value Type
+
Can be numeric, string, boolean, Date & Time, Time Span or Enumeration.
+ + +
WSN
+
Wireless Sensor Network, a sensor network including wireless devices.
+ + +
XMPP Client
+
Application connected to an XMPP network, having a JID. Note that sensors, as well as applications requesting sensor data can be XMPP clients.
+ +
+ + +

+ To create a complete set of operations supported by all types of concentrators, ranging from PLCs to subsystems to entire systems is very difficult. So, the aim + of this document is instead to create a very small reduced set of operations, a common denominator, that would allow for basic maintenance and interoperability of + concentrators of different makes and models and of these varying ranges. +

+ + +

+ This document lists a sequence of commands. Some are very basic, while others are used for managing massive amounts of devices. When developing a small PLC, it might + be difficult to motivate the implementation of the more advanced commands. They are simply not necessary for the management of the device. So, clients connecting to + the concentrator need a way to learn what operations are available in the concentrator, and as a consequence what operations are not. To do this, the + getCapabilities command is sent, as is shown in the following example. +

+ + + + + + + + getCapabilities + getAllDataSources + getRootDataSources + getChildDataSources + containsNode + containsNodes + getNode + getNodes + getAllNodes + getNodeInheritance + getRootNodes + getChildNodes + getIndices + getNodesFromIndex + getNodesFromIndices + getAllIndexValues + getNodeParametersForEdit + setNodeParametersAfterEdit + getCommonNodeParametersForEdit + setCommonNodeParametersAfterEdit + getAddableNodeTypes + getParametersForNewNode + createNewNode + destroyNode + getAncestors + getNodeCommands + getCommandParameters + executeNodeCommand + getCommonNodeCommands + getCommonCommandParameters + executeCommonNodeCommand + moveNodeUp + moveNodeDown + moveNodesUp + moveNodesDown + subscribe + unsubscribe + getDatabases + getDatabaseReadoutParameters + startDatabaseReadout + + ]]> + +

+ A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows: +

+ + + + + + + + getCapabilities + getAllDataSources + getRootDataSources + getChildDataSources + containsNode + containsNodes + getNode + getNodes + getAllNodes + getNodeInheritance + getRootNodes + getChildNodes + getIndices + getNodesFromIndex + getNodesFromIndices + getAllIndexValues + getNodeParametersForEdit + setNodeParametersAfterEdit + getCommonNodeParametersForEdit + setCommonNodeParametersAfterEdit + getAddableNodeTypes + getParametersForNewNode + createNewNode + destroyNode + getAncestors + getNodeCommands + getCommandParameters + executeNodeCommand + getCommonNodeCommands + getCommonCommandParameters + executeCommonNodeCommand + moveNodeUp + moveNodeDown + moveNodesUp + moveNodesDown + subscribe + unsubscribe + + ]]> + +

+ A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems: +

+ + + + + + + + getCapabilities + getAllDataSources + getRootDataSources + getChildDataSources + containsNode + getNode + getNodeInheritance + getRootNodes + getChildNodes + getNodeParametersForEdit + setNodeParametersAfterEdit + getAddableNodeTypes + getParametersForNewNode + createNewNode + destroyNode + getAncestors + getNodeCommands + getCommandParameters + executeNodeCommand + moveNodeUp + moveNodeDown + moveNodesUp + moveNodesDown + subscribe + unsubscribe + + ]]> + +

+ But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands: +

+ + + + + + + + getCapabilities + getAllDataSources + containsNode + getNode + getRootNodes + getChildNodes + getNodeCommands + getCommandParameters + executeNodeCommand + + ]]> + +

+ So, clients who need to interact with different types of concentrators need to be aware of what commands are supported, and limit operations to those commands. +

+ + + + +

+ This command will return a flat list of all available data sources on the concentrator. It is not structured hierarchically. +

+ + + + + + + + + + + ... + + ]]> + + + +

+ If the client is interested in the hierarchical structure of available data sources, it should request only the root sources, and then ask the client for their + corresponding child data sources. If the client wants to present the data sources to a user, presenting them in their hierarchical order may be more intuitive. +

+ + + + + + + + + + + ... + + ]]> + + + +

+ Having the ID of a data source that contains child data sources, you can fetch the child sources as follows: +

+ + + + + + + + + + + + + + + + ]]> + + + +

+ A client can subscribe to changes made in a data source. It does this by sending the subscribe command to the concentrator, + as is shown in the following example: +

+ + + + + + + + ]]> + +

+ Multiple subscriptions to the same source will not result in an error, however the server will still only send one event message for each event in the data source. +

+

+ Important: Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist + event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription + is removed. +

+

+ Note: The parameters and messages attributes can be used to retrieve parameter and status message information + about the nodes in event messages sent from the concentrator. Note that the xml:lang may be used to select the language used in such events, + if the concentrator supports localization of strings. +

+ + + + + + + + ]]> + +

+ The subscribe command has a set of optional attributes, one for each event type available, and with the same names, that the + client can use to subscribe to individual events, but not to others. They have the default value of true implying that if not provided, the + default action is to subscribe to those events. +

+

+ The following example shows how a client can subscribe to a set of events only: +

+ + + + + + + + ]]> + +

+ For more information on types of events sent, see the Data Source Events section. +

+ + +

+ A client can unsubscribe to changes made in a data source it is subscribed to. It does this by sending the unsubscribe command to the concentrator, + as is shown in the following example: +

+ + + + + + + + ]]> + +

+ An unsubscription made to an existing data source, but where an event subscription does not exist, must not result in an error. +

+

+ The unsubscribe command has a set of optional attributes, one for each event type available, and with the same names, that the + client can use to unsubscribe from individual events, but not from others. They have the default value of true implying that if not provided, the + default action is to unsubscribe from those events. +

+

+ The following example shows how a client can unsubscribe from a subset of events, keeping subscriptions on the others (if subscribed to): +

+ + + + + + + + ]]> + + + +

+ If a client comes back online and wants to know any changes that have taken place on the concentrator since last time it was in contact with it, + it can include a getEventsSince attribute in the subscribe command sent to the concentrator. This will make the + concentrator send all event messages since the given timestamp to the client before subscribing the client to events in the given data source. +

+ + + + + + + + + + ... Sequence of event messages sent from concentrator to client.]]> + +

+ Important: Event subscriptions only last for as long as the client and concentrator both maintain presence. The concentrator must not persist + event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription + is removed. +

+

+ Note: The parameters and messages attributes can be used to retrieve parameter and status message information + about the nodes in event messages sent from the concentrator. +

+

+ For more information on types of events sent, see the Data Source Events section. +

+ + + + +

+ This command permits the client to check the existence of a node in the concentrator. +

+ + + + + + + true + ]]> + + + +

+ If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead: +

+ + + + + + + + + + + + + true + true + false + true + + ]]> + +

+ The array returned will have one item for each item in the request, in the same order. +

+ + +

+ This command returns basic information about a node in the concentrator. +

+ + + + + + + + ]]> + +

+ For more information, see Node Information. +

+ + +

+ This commands lets the client get information from multiple nodes at once. +

+ + + + + + + + + + + + + + + + ]]> + +

+ For more information, see Node Information. +

+ + +

+ This command returns basic information about a node in the concentrator, as well as node parameters. +

+ + + + + + + + + + + + + + + + + ]]> + +

+ For more information, see Node Information. +

+ + +

+ This commands lets the client get information from multiple nodes at once, including node parameters. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ For more information, see Node Information. +

+ + +

+ If the device does not manage too many nodes, it could choose to implement this function. It would return all available nodes with one call. +

+ + + + + + + + + + + + + ]]> + + + +

+ If the device does not manage too many nodes, it could choose to implement this function. It would return all available nodes with their parameters with one call. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance. +

+ + + + Namespace.BaseClass1 + + + + + + + + + ]]> + + + +

+ This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance. It also returns node parameters + directly in the response. +

+ + + + Namespace.BaseClass1 + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the caller can list multiple classes in the request. This would return only nodes having the correct base class(es) and + implementing all interfaces. +

+ + +

+ This command assumes node types exist in a class hierarchy. It allows the caller to get a list of the node class hierarchy and implemented interfaces the + node has. +

+ + + + + + + + + Namespace.BaseClass1 + Namespace.AbstractBase + + + ]]> + + + +

+ This commands returns the root node of a data source (in case the source is a tree-shaped data source) or the root nodes of a data source (in case the + source is flat). +

+ + + + + + + + + + ]]> + + + +

+ This commands returns the root node of a data source (in case the source is a tree-shaped data source) or the root nodes of a data source (in case the + source is flat), and also returns the parameters for the corresponding nodes. +

+ + + + + + + + + + + + + + + + + + + ]]> + + + +

+ This commands returns the child nodes of a node in a data source. +

+ + + + + + + + + + + ]]> + + + +

+ This commands returns the child nodes of a node in a data source, and also returns the parameters for the corresponding nodes. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ This command returns a list of available indices in a data source. Indices can be used for efficient node look-up. +

+ + + + + + + + country + region + city + area + street + building + apartment + oid + + ]]> + + + +

+ This command can be used to get a node or nodes from a data source using an index and an index value. +

+ + + + + + + + + + ]]> + + + +

+ This command can be used to get a node or nodes from a data source using an index and an index value, and also returns the parameters for the corresponding nodes. +

+ + + + + + + + + + + + + + ]]> + + + +

+ This command can be used to get nodes from a set of data source using indices and index values. +

+ + + + + + + + + + + + + + ]]> + + + +

+ This command can be used to get nodes from a set of data source using indices and index values, and also returns the parameters for the corresponding nodes. +

+ + + + + + + + + + + + + + + + + + + + + + ]]> + + + +

+ This command can be used to get a list of available index values, given a data source and an index. +

+ + + + + + + + A1-1 + A1-2 + ... + + ]]> + + + +

+ In a tree formed data source, all nodes except the root node has a parent node. The getAncestors command allows the client to get a list + of all ancestors (parent, grand parent, etc.) of a node, as is shown in the following example: +

+ + + + + + + + + + + + + + + + + + ]]> + +

+ Note that the concentrator returns information about the node itself in the response. The parameters and messages + attributes are used in the request to control if the concentrator should return node parameters and node status messages in the response as well. +

+ + +

+ As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings. + To move a node upwards among its siblings is done using the command moveNodeUp, as is shown in the following example: +

+ + + + + + + + ]]> + +

+ Note that a node that is first among its siblings will maintain its position. The response to the command must still be OK. +

+ + +

+ As the order of siblings in a tree can be important, depending on the context and type of nodes involved, the client may be allowed to move nodes up and down among siblings. + To move a node downwards among its siblings is done using the command moveNodeDown, as is shown in the following example: +

+ + + + + + + + ]]> + +

+ Note that a node that is last among its siblings will maintain its position. The response to the command must still be OK. +

+ + +

+ To move a set of nodes upwards among its siblings is done using the command moveNodesUp, as is shown in the following example: +

+ + + + + + + + + + + + ]]> + +

+ Note that a node that is first among its siblings will maintain its position. The response to the command must still be OK. If an attempt is performed to move a + sequence of nodes that are together first as siblings, none of the nodes move relative to each other. +

+ + +

+ To move a set of nodes downwards among its siblings is done using the command moveNodesDown, as is shown in the following example: +

+ + + + + + + + + + + + ]]> + +

+ Note that a node that is last among its siblings will maintain its position. The response to the command must still be OK. If an attempt is performed to move a + sequence of nodes that are together last as siblings, none of the nodes move relative to each other. +

+ + + + +

+ Previously described commands can return parameters for a node. But these parameters are for presentational or informational use. If the client wants to edit + the parameters of a node, another set of commands must be used. This use case shows how getNodeParametersForEdit can be used to edit available + parameters for one node. +

+

+ Note: When editing parameters for a node, a different set of parameters might be returned compared to the set of parameters available in commands + mentioned above. There may be various reasons for this, among other things (but not limited to) user rights, node settings, and parameter type. User rights may restrict the number + of parameters the user can access. The node may be configured not to allow editing of certain parameters. Also, some types of parameters may only be available in + an edit mode (like long multi-line parameters) and not in a shorter presentation mode. +

+ + + + + + + + + Node1 + + + + + + + + + + + + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + ID of the node. + + Node1 + + + Type of node. + Watchamacallit Temperature Sensor v1.2 + + + + Class of node + Temperature + + + + + + + ... + + + Serial number of node/device. + 123456 + + + Meter Location. + P123502-2 + + + + + + Bus address + 123 + + + + + + Latitude of node. + 12.345 + + + + + + Longitude of node. + 123.45 + + + + ]]> + +

+ The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
XEPDescription
XEP-0004Describes how basic forms are handled.
XEP-0122Makes it possible to add certain client validation rules to form parameters.
XEP-0137Makes it possible to publish a file upload parameter.
XEP-0141Makes it possible to layout parameters into pages and sections.
XEP-0000-ColorParameterDefines extensions for how color parameters can be handled.
xep-0000-DynamicFormsMakes it possible to create dynamic forms, with server-side validation and forms that change dynamically depending on input.
+

+ Read-only parameters will be returned with the readOnly element, as defined in xep-0000-DynamicForms. + Clients SHOULD support this extension if using this command. However, the server MUST NOT change parameters in a node that are read-only, even if clients happen + to try to set them. +

+ + +

+ After editing the form, the client uses the setNodeParametersAfterEdit command to set the parameters in the node. Note that it is possible to + set the same parameters (or a sub-set of the same parameters) to a different node using this command, without the need to get new form parameters. However, after the first + successful set operation, any form session used for dynamic validation during edit will not be available on the server any more. +

+ + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + Node1 + + + Temperature + + + 123456 + + + P123502-2 + + + 123 + + + 12.345 + + + 123.45 + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set + to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources + related to the form, which disables any future dynamic validation of the contents of the form. The newly edited node will also be available in the response + in a node element. +

+ + +

+ The following example shows how the server responds when the client tries to set invalid parameters. The response contains detailed information about why, + information which the client can use to inform the user (if any) of what went wrong. +

+ + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + Node1 + + + Temperature + + + 123456 + + + P123502-2 + + + 123 + + + 12.345 + + + 123.45 + + + + + + + + There already exists a node with this ID. + + ]]> + +

+ As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as + dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been + explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms + + XEP-xxxx: Dynamic Data Forms <xep-0000-DynamicForms.html> + for more information. +

+ + +

+ Advanced concentrators handling large quantities of nodes may let users edit sets of nodes at once to be practical. This is done by publishing the + getCommonNodeParametersForEdit command. It will return a form with parameters that are common for all selected nodes. Since nodes + may have different node types it is assumed that different nodes have different sets of parameters. But if this command is used, only parameters matching + in IDs, descriptions, validation rules, etc., (but not values) will be returned in a form. +

+

+ Important: A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the + notSame element, according to xep-0000-DynamicForms. Clients using this command MUST + support the extensions defined in xep-0000-DynamicForms. +

+ + + + + + + + + + + + + Node1, Node2, Node3 + + + + + + + + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + Type of node. + Watchamacallit Temperature Sensor v1.2 + + + + + Class of node + Temperature + + + + + + + + ... + + + Serial number of node/device. + 123456 + + + + Meter Location. + P123502-2 + + + + + + + Bus address + 123 + + + + + + + Latitude of node. + 12.345 + + + + + + + Longitude of node. + 123.45 + + + + + ]]> + +

+ Note that parameters that are not available in all selected nodes will have been removed. Also and ID-parameter will have been removed, since they + cannot be set for a collection of nodes. +

+

+ Fields marked with the notSame element only present one value, perhaps the value of the first node. However, the field should be clearly + marked in any end-user GUI (for example by graying the field), and MUST ONLY be sent back to the server in a set operation if explicitly edited by the end-user. + The parameter will be set in all selected nodes in that case. Unedited fields should be treated as if the end-user accepts the different values for the current set of nodes. +

+ + +

+ After editing the form, the client uses the setCommonNodeParametersAfterEdit command to set the parameters in the set of nodes. Note that it is possible to + set the same parameters (or a sub-set of the same parameters) to a different set of nodes using this command, without the need to get new form parameters. However, after the first + successful set operation, any form session used for dynamic validation during edit will not be available on the server any more. +

+ + + + + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + Temperature + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + +

+ Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set + to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources + related to the form, which disables any future dynamic validation of the contents of the form. +

+

+ Important: A parameter that exists in multiple nodes, but has different parameter values among the nodes, will be marked with the + notSame element, according to xep-0000-DynamicForms. Such parameters MUST NOT be sent back to the server + unless they have explicitly been edited or signed by the end-user. The value sent back to the server will be set in all nodes. +

+ + +

+ The following example shows how the server responds when the client tries to set invalid parameters to a set of nodes. The response contains detailed information about why, + information which the client can use to inform the user (if any) of what went wrong. +

+ + + + + + + + + 009c7956-001c-43fb-8edb-76bcf74272c9 + + + Node1 + + + Temperature + + + + + + + + Parameter not available. + + ]]> + +

+ As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as + dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been + explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms + xep-0000-DynamicForms.html for more information. +

+ + +

+ Each node in the concentrator has a state. This state is a dynamic run-time state, and therefore not presented as a more static property. + This state can be any of the following values, in order of increasing importance: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StateDescription
NoneNothing has been reported on the node.
InformationThere are informative events reported on the node.
WarningSignedThere are warnings reported on the node. But these warnings have been viewed by an operator.
WarningUnsignedThere are new or unreviewed warnings reported on the node.
ErrorSignedThere are errors reported on the node. But these errors have been viewed by an operator.
ErrorUnsignedThere are new or unreviewed errors reported on the node.
+

+ Other types of "states" are of course possible, such as phase - installation phase, test phase, production phase, etc. - but such "states" are seen as static + and presented as parameters on the node. The purpose of the dynamic state attribute of a node, is to give a dynamic runtime state that has + the possibility to change during runtime, which operators must be aware of. +

+

+ The following commands have an optional attribute messages, with which they can ask the server to return any events logged on the node, giving more details of the + current state of the node: +

+
    +
  • + getNode +
    • +
  • + getNodes +
    • +
  • + getChildNodes +
    • +
  • + getAllNodes +
    • +
  • + getRootNodes +
    • +
  • + getNodesFromIndex +
    • +
  • + getNodesFromIndices +
    • +
+ + + + + + + + Internal clock is offset more than 7 seconds. + + ]]> + +

+ The messages attribute can be combined with the parameters attribute to provide both node parameters and + messages in the response. +

+ + + + + + + + + + + + + + + + Internal clock is offset more than 7 seconds. + + ]]> + + + + + +

+ Since nodes are context sensitive, depending on node type and tree structure, before being able to create a new node, it is important to know what types of nodes + that can be added to a given node. This is done using the getAddableNodeTypes command, as is shown in the following example: +

+ + + + + + + + + + + + ]]> + + + +

+ When you know what type of node you want to create, you need to get a set of parameters you need to fill in for the new node, before you can create it. + This is done using the getParametersForNewNode command, as is shown in the following example: +

+ + + + + + + + + Metering Topology + + + + + + 0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D + + + ID of the node. + + + + + ID of the node in the metering topology. + + + + + + ]]> + + + +

+ After editing the form, the client uses the createNewNode command to create the new node using the parameters provided in the form. +

+ + + + + + 0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D + + + Reference to Node1 + + + Node1 + + + + + + + + + + + + + + ]]> + +

+ Note that validation rules, pagination, etc., can be stripped from the form when submitting it to the server. Also the form type attribute must be set + to 'submit'. Note also that as the result attribute is OK, it is assumed the server has dropped any parameter form resources + related to the form, which disables any future dynamic validation of the contents of the form. The newly created node with corresponding parameters is also returned + in the response in a node element. +

+ + +

+ The following example shows how the server responds when it cannot accept parameters provided when trying to create a node. The response will contain detailed information + about why, information which the client can use to inform the user (if any) of what went wrong. +

+ + + + + + 0B146517-8EA3-4BEC-A2E9-CF3F209D4A5D + + + Node2 + + + NodeX + + + + + + + + There already exists a node with this ID. + Referenced node was not found. + + ]]> + +

+ As the result attribute is FormError, the server maintains any parameter form resources related to the form, and features such as + dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been + explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms + xep-0000-DynamicForms.html for more information. +

+ + +

+ To destroy (remove) a node from the concentrator, the destroyNode command is sent, as is shown in the following example: +

+ + + + + + + + ]]> + +

+ Since the result attribute in the response is OK, the node has been removed. +

+ + +

+ If the result attribute in the response is other than OK, the node was not removed from the concentrator. + The result attribute contains the reason why the operation failed, as is shown in the following example: +

+ + + + + + + + ]]> + + + + + +

+ Each node can have a context sensitive set of commands available to it. This is shown using the hasCommands attribute in the + Node Information record describing the corresponding node. If the client wants to get a list of available commands, + the getNodeCommands command is sent to the concentrator, as is shown in the following example: +

+ + + + + + + + + + + ]]> + +

+ There are two types of commands available: Simple and Parameterized. Simple commands take no parameters, and + are therefore simpler to execute. Parameterized commands require the client to get a set of parameters for the corresponding command before it + can be executed. For more information about command attributes, see Node Commands. +

+ + +

+ Executing a simple command is done by sending the executeNodeCommand command to the concentrator, as is shown in the following example: +

+ + + + + + + + ]]> + + + +

+ To execute a parameterized command on the node, the client first needs to get (and edit) a set of parameters for the command. Getting a set of parameters for a + parameterized command is done as follows: +

+ + + + + + + + + Schedule wake-up call + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + Time of the wake-up call. + + + + + + + + Type of wake-up call + Soft + + + + + + + ]]> + + + +

+ Executing a parameterized command is also done by sending the executeNodeCommand command to the concentrator, but including the edited form parameters, + as is shown in the following example: +

+ + + + + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + 04:30:00 + + + Harass + + + + + + + + ]]> + + + +

+ If an error occurs during the execution of a command or if the server rejects the execution of a command, the server returns a response code different from + OK. If the response code is FormError, the server maintains any parameter form resources related to the form, and features such as + dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been + explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms + xep-0000-DynamicForms.html for more information. +

+ + + + + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + 04:30:00 + + + Harass + + + + + + + + You are not allowed to harass people at 04:30:00! + + ]]> + + + +

+ Using the command getCommonNodeCommands, the client can receive commands that are common for a set of nodes, + as is shown in the following example: +

+ + + + + + + + + + + + + + + + + + ]]> + + + +

+ Executing a simple command on multiple nodes is done by sending the executeCommonNodeCommand command to the concentrator, + as is shown in the following example: +

+ + + + + + + + + + + + + + + true + true + true + true + true + true + + ]]> + + + +

+ To execute a parameterized command on a set of nodes, the client first needs to get (and edit) a set of parameters for the common command. Getting a set of parameters for a + common parameterized command is done as follows: +

+ + + + + + + + + + + + + + + + Schedule wake-up call + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + Time of the wake-up call. + + + + + + + + Type of wake-up call + Soft + + + + + + + ]]> + + + +

+ Executing a common parameterized command is also done by sending the executeCommonNodeCommand command to the concentrator, but including the edited form parameters, + as is shown in the following example: +

+ + + + + + + + + + + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + 04:30:00 + + + Harass + + + + + + + + true + true + true + true + true + true + + ]]> + + + +

+ If an error occurs during the execution of a common command or if the server rejects the execution of a common command, the server returns a response code different from + OK. If the response code is FormError, the server maintains any parameter form resources related to the form, and features such as + dynamic validation of the contents of the form will still be available until the parameters have been successfully set, the operation has been + explicitly cancelled or a form session time-out has occurred. See xep-0000-DynamicForms + xep-0000-DynamicForms.html for more information. +

+ + + + + + + + + + + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + 04:30:00 + + + Harass + + + + + + + + You are not allowed to harass people at 04:30:00! + + ]]> + + + +

+ When executing a command, simple or parameterized, on multiple nodes, it might happen that the command fails on some nodes, but not on others, even though + any parameters are validated beforehand. Therefore, the client needs to check any result elements in the response, even though the + response code is OK. +

+

+ The following example shows the execution of a parameterized command on multiple nodes that fail on some nodes but are executed on others. +

+ + + + + + + + + + + + E14E330F-8496-46F0-8F40-178808AB13A7 + + + 04:30:00 + + + Harass + + + + + + + + true + true + false + true + false + true + + ]]> + + + + +

+ Events are asynchronous messages sent from the concentrator to devices registered with the concentrator and having subscribed to events from the concentrator. + Event subscription can be activated using the subscribe command. You can also retrieve historical events + using the subscribe command. +

+

+ Each event is sent from the concentrator to each subscriber using a message stanza. Each such message stanza may contain multiple + events. The following subsections list the different types of events that can be sent. Even though these examples may list only one element in a message stanza, this + is not a limitation. Different types of events may also be mixed within the message stanza. +

+

+ Event subscriptions only last for as long as the client and concentrator both maintains presence. The concentrator must not persist + event notification subscriptions, and if it goes offline and back online, or if the client goes offline or online again for any reason, the event subscription + is removed. +

+

+ Node events may contain parameters or status messages. This depends on how the subscription was made. The parameters and messages attributes + in the subscribe command determine if node parameters and/or status messages should be sent in event messages. +

+ +

+ The nodeAdded event is sent when a node has been added to a data source which the client subscribes to. The following example + shows how such an event message may look like: +

+ + + + ]]> + + + + + + + + + + + + + + ]]> + +

+ Note: Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first + removing it from the current source (sending a nodeRemoved event) and then adding it to the new data source (sending a nodeAdded + event), in that order. +

+ + +

+ The nodeRemoved event is sent when a node in a data source has been removed or destroyed. It does not include status message or parameter + information about the node, only the reference to the node. The following example shows how such an event message may look like: +

+ + + + ]]> + +

+ Note: Moving a node in a data source from one parent to another, possibly between different data sources, is performed by first + removing it from the current source (sending a nodeRemoved event) and then adding it to the new data source (sending a nodeAdded + event), in that order. +

+ + +

+ The nodeUpdated event is sent when a node has been updated in a data source which the client subscribes to. The following example + shows how such an event message may look like: +

+ + + + ]]> + + + + + + + + + + + + + + ]]> + +

+ The event has an optional attribute named oldId. It is set when the node has been renamed. It must be used, if available, to identify + what node has been updated, as the following example shows: +

+ + + + ]]> + + + + + + + + + + + + + + ]]> + +

+ Note: If only the status has changed, and no other parameters have changed, the nodeStatusChanged + event could be sent instead, for somewhat improved performance in this case. +

+ + +

+ The nodeStatusChanged event is sent when the state of the node has changed, but no other parameters have been changed. + If the client has subscribed to state messages, these will also be included in the event. +

+ + + + ]]> + + + + + Sensor does not respond to read-out requests. + + ]]> + + + +

+ The nodeMovedUp event is sent when a node in a data source has been moved up among its siblings. It does not include status message or parameter + information about the node, only the reference to the node. The following example shows how such an event message may look like: +

+ + + + ]]> + +

+ Note: If issuing a moveNodeUp command on a node that is already first among its siblings, the node is not moved and the + concentrator must not send a nodeMovedUp event. However, if the client receives such an event pointing to a node that is already first among + its siblings, it should not move the node. +

+ + +

+ The nodeMovedDown event is sent when a node in a data source has been moved down among its siblings. It does not include status message or parameter + information about the node, only the reference to the node. The following example shows how such an event message may look like: +

+ + + + ]]> + +

+ Note: If issuing a moveNodeDown command on a node that is already last among its siblings, the node is not moved and the + concentrator must not send a nodeMovedDown event. However, if the client receives such an event pointing to a node that is already last among + its siblings, it should not move the node. +

+ + + +

+ A concentrator can often store data from sensors locally (or remotely but controlled locally). Storage is done in field databases. A concentrator with + only communicative abilities will publish zero such field databases (and support for none of the field database commands), while a pure metering database will publish + one or many field databases, but none of the nodes available in any of the different data sources are readable or writable. The nodes in this latter case only acts as + placeholders for the data that the concentrator is storing or controlling. +

+

+ The following subsections lists different use cases relating to field databases and how to use them. +

+ +

+ The client can retrieve the list of available databases on the concentrator using the getDatabases command, as is shown in the following example: +

+ + + + + + + + + + + + + ]]> + + + +

+ Before reading data from a database can begin, a parameter form containing database specific search parameters needs to be fetched from the server. + This is done using the getDatabaseReadoutParameters command, as is shown in the following example: +

+ + + + + + + + + Database read-out + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + C20D4F0C-8F8A-490F-8188-53017DF2B71A + + + + + + + Read values not older that this timestamp. + + + + + + + + Read values not newer that this timestamp. + + + + If specified, only the following fields (include wildcards) will be read out. + + + + If checked, momentary values will be read. + false + + + If checked, peak values will be read. + false + + + If checked, status values will be read. + false + + + If checked, computed values will be read. + false + + + If checked, identity values will be read. + false + + + If checked, historical values (second) will be read. + false + + + If checked, historical values (minute) will be read. + false + + + If checked, historical values (hour) will be read. + false + + + If checked, historical values (day) will be read. + false + + + If checked, historical values (week) will be read. + false + + + If checked, historical values (month) will be read. + false + + + If checked, historical values (quarter) will be read. + false + + + If checked, historical values (year) will be read. + false + + + If checked, historical values (other) will be read. + false + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + Determines how this flag should be treated during readout. + Ignore + + + + + + This parameter specifies how multiple status flags are to be treated in the readout. + Any + + + + + + ]]> + + + +

+ Once the parameter form has been filled out, a database readout can be started using the startDatabaseReadout command. + Data read from the concentrator will follow the same flow of sensor data as that described in sensor-data + + XEP-xxxx: Sensor Data sensor-data + . The only difference is that the read-out is started with the startDatabaseReadout command instead of the req + command of the sensor data namespace. +

+

+ The following diagram shows the flow of messages when requesting a readout from a database: +

+

+ +

+

+ The following example shows a startDatabaseReadout request: +

+ + + + + + + + + C20D4F0C-8F8A-490F-8188-53017DF2B71A + + + 2013-03-22T00:00:00 + + + 2013-03-23T00:00:00 + + + Temperature + Pressure + Power + + + true + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + false + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Ignore + + + Any + + + + + + + + + + ... Readout messages follow.]]> + + + +

+ The following example shows a response when the concentrator rejects the read-out request: +

+ + + + + + + + ... + + + + + + + ]]> + +

+ The error might also be a result of invalid input parameters being sent: +

+ + + + + + + + ... + + 2013-03-23T00:00:00 + + + 2013-03-22T00:00:00 + + ... + + + + + + + The To timestamp cannot be older than the From timestamp. + + ]]> + + + +

+ A client can cancel a database read-out using the cancel read-out command, + as described in sensor-data. +

+ + + + + + + + ... + + + + + + + + + ... + + + + + + + + ]]> + + + + + + +

+ Several commands return basic node information. The following table lists possible fields with corresponding descriptions. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeUseDefaultDescription
idrequired The ID of the node in the data source.
displayNameoptional If provided, a string presentable to users. If localization is supported and a correct language attribute was provided, this string will be localized.
nodeTypeoptional A string representing the type of the node.
localIdoptional If provided, an ID for the node, but unique locally between siblings.
logIdoptional If provided, an ID for the node, as it would appear or be used in system logs.
cacheTypeoptional Used to uniquely identify the node in sources where the ID of the node is not sufficient. Example: In a spatial ordering different nodes may represent + countries, regions, cities, areas, streets, buildings and apartments in the same source. However, the ID of each node would depend on what type of node it + represents. It might be valid to have a region, city and/or area with the same ID. So, to these circumstances, a Cache Type of Country, Region, City, Area, + Street, Building and Apartment can be used to allow for non-unique IDs within the source, as long as they are unique within the same cache type. ***
staterequired Current overall state of the node.
hasChildrenrequired If the node has children or not.
childrenOrderedoptionalfalseIf the children of the node have an intrinsic order (true), or if the order is not important (false). If the order is not important, the client + can present the order as it wishes, for example sorted on Node ID or any other parameter available on the child nodes. However, if the children have an + intrinsic order, it's important for the client to refresh the child list when necessary whenever the order is unknown, such as after a nodeAdded event or + a nodeRemoved event. +
isReadableoptionalfalseIf the node can be read. (*)
isConfigurableoptionalfalseIf the node can be configured. (**)
hasCommandsoptionalfalseIf the node has registered commands or not.
parentIdoptional The node ID of the parent node. If not available, the node is considered a root node.
parentCacheTypeoptional The Cache Type of the parent node.
lastChangedoptional When the node was last changed. Can be used by clients to synchronize content between the concentrator and itself.
+

+ (*) See sensor-data for more information about how to read nodes. +

+

+ (**) See xep-0000-SN-Control for more information about how to configure nodes. +

+

+ (***) Note that cacheType is optional. In some data sources it might be necessary to include a cache type to allow for IDs that are not unique + within the source. In these cases, it concentrator must include the cacheType attribute for nodes in the corresponding data source, and clients must use the corresponding + cacheType value when referencing the node. But if such a separation of IDs within a source is not required, the concentrator may ignore the cacheType attribute. + In these instances clients may also ignore the cacheType attribute when referencing the nodes in the corresponding data source, or use the empty string as value for the + cacheType value. The server must ignore empty cacheType values for data sources not using a cache type separation mechanism. +

+ + +

+ Nodes can report parameters of different types. The following table lists available parameter types. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Element NameParameter Value
booleanBoolean values. Can be true or false.
colorColor values. They are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component.
dateTimeDate and time value, with possible time zone information.
doubledouble precision floating point value.
durationA time duration value.
intA 32-bit integer value.
longA 64-bit integer value.
stringA string value.
timeA time value using a 24-hour clock.
+ + +

+ All responses have a response code that the client is required to check. The following table lists possible response codes and their corresponding meanings. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Response CodeDescription
OKRequest is OK and accepted.
NotFoundCorresponding object, node, etc., was not found.
InsufficientPrivilegesInsufficient privileges to perform the corresponding action or execute the corresponding command. Make sure to provide sufficient credentials in the call + (user, service, device tokens) with sufficient privileges to perform the action/command.
LockedThe object/node is locked, and operation could not be performed or completed.
NotImplementedCommand is not implemented.
FormErrorThe form send to the concentrator contains errors. The response contains detailed error information.
OtherErrorAnother error occurred.
+ + +

+ It's important that the concentrator responds to unrecognized commands. This, to make sure future extensions to this document does not produce unexpected + results in concentrators implementing a previous version, or in concentrators implementing only a subset of available commands. +

+

+ When a concentrator receives an element that it does not understand, it must do as follows: +

+
    +
  • If the element is received in a message stanza, the element must be ignored.
    • +
  • If the element is received in an iq-result stanza, the element must be ignored.
    • +
  • If the element is received in an iq-get or iq-set stanza, an iq-result stanza must be composed containing an element with the same name as the incoming + element, but with Response appended to it, having a response code of NotImplemented.
    • +
+

+ The following example shows how unrecognized commands must be handled by the concentrator: +

+ + + + ... + + + + + + ]]> + + + +

+ Node commands have a set of attributes. The following table lists available attributes and what they mean. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
AttributeUseDescription
idrequiredID of the command. Used to identify the command.
namerequiredA string that can be presented to an end-user. Should be localized if the request contained a language preference.
typerequiredIf the command is 'Simple' or 'Parameterized'.
sortCategoryoptionalShould be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and + lastly by Name.
sortKeyoptional + Should be used (if available) by clients to sort available node commands before presenting them to an end-user. Commands should be sorted by Sort Category, Sort Key and + lastly by Name. +
confirmationStringoptionalShould presented to clients (if available) before letting an end-user execute the command. A delete command might have a confirmationString saying + 'Are you sure you want to delete the current item?' The confirmation string should be presented as a Yes/No[/Cancel] dialog.
failureStringoptional + Could be presented to end-users (if available) if a command fails. It provides the client with an optionally localized string giving some context to the error message. + A delete command might have a failureString saying 'Unable to delete the current item.'. The client could then add additional error information, if available, + for instance from the response code. +
successStringoptional + Could be presented to end-users (if available) if a command is successfully executed. It provides the client with an optionally localized string giving some context + to the message. A delete command might have a successString saying 'Current item successfully deleted.'. +
+ + +

+ Nodes can be in different states. Even though nodes are free to publish any amount of states as parameters, there are a set of states that are so crucial to the + concept of a node state, that they are published using a separate attribute and separate events. These node states are as follows: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StateDescription
NoneThe node has nothing special to report.
InformationThe node has informative events reported on it.
WarningSignedThe node has warnings reported on it. These warnings have been viewed by an operator.
WarningUnsignedThe node has warnings reported on it that have not been viewed by anybody.
ErrorSignedThe node has errors reported on it. These errors have been viewed by an operator.
ErrorUnsignedThe node has errors reported on it that have not been viewed by anybody.
+ + +

+ The following table lists required data sources for concentrators (of sensors, actuators, meters, etc.) in sensor networks: +

+ + + + + + + + + +
Data SourceDescription
MeteringTopologyData Source containing the topology of metering devices, including sensors, actuators, meter, infrastructure components, etc.
+

+ More information can be found in the XEP-xxxx: Interoperability Interoperability section. +

+ + + + +

+ Localization of content can be performed if clients provide xml:lang attributes in commands made to the concentrator. If omitted, the + default language will be used in responses. If provided, but the concentrator does not support localization, or the requested language, + the default language will also be used. +

+ + +

+ Concentrators of larger sub-systems spanning multiple time-zones should specify all timestamps with time-zone information, so readers can perform comparisons + of time information. +

+

+ Information read from a concentrator that lacks time-zone information should be considered to lie in the same time-zone as the reader, unless not explicitly + configured with a time-zone. +

+ + +

+ For concentrators to be interoperable in sensor networks, they need to adhere to rules and guidelines described in the + xep-0000-SN-Interoperability document. +

+ + + + +

+ This document publishes a lot of commands with which to interact with a concentrator. If security and access rights is an issue, it might not be sufficient + to allow all friends access to the system. There are many ways in which to restrict access to the contents of the concentrator. Following are some examples: +

+
    +
  • + The concentrator can restrict friendships to trusted friends, and then assign access rights internally to the approved contacts. +
    • +
  • + The concentrator can use a provisioning server (see XEP-xxxx: Provisioning sensor-network-provisioning) + to delegate trust to a third party responsible for controlling who can get access to the concentrator (isFriend or canAccess commands), + and what items can be viewed (hasPrivilege or downloadPrivileges commands). +
    • +
  • + All requests to the concentrator can contain the optional attributes deviceToken, serviceToken and userToken. + Clients making requests to the concentrator can use these attributes to forward information about who originated the action (userToken), + what service is performing the action (serviceToken) or what device is performing the action (deviceToken). The concentrator + can use this information to check with provisioning servers what access rights and user privileges exist before performing the action. +
    • +
+ + +

+ The sensor-network-provisioning document describes how trust can be delegated to trusted provisioning servers + that can be used to restrict access to and privileges in a network. +

+

+ If a concentrator has a trusted relationship with a provisioning server, external or internal, the provisioning server must be used to guarantee that the + concetrator only allows access according to rules defiend by the provisioning server. In order to do this, it's important that clients always provide + available tokens (userToken, serviceToken and deviceToken) to the concentrator so that it can forward this + information to the provisioning server. +

+

+ The following subsections show different examples of how such an integration can be performed. +

+ +

+ This section shows how a provisioning server can be used to restrict access to data sources to users allowed to access those data sources. +

+

+ +

+

+ Notice the following: +

+
    +
  • + The user has a userToken it received during connection with the service. This user token should + be included in all calls made by the user. +
    • +
  • + The service has a serviceToken it received during service registration. This service token + should be aggregated by all calls made by the service. +
    • +
  • + The concentrators should cache all calls made to the provisioning server according to available cache rules. +
    • +
  • + The conversion of a Data Source ID to a Privilege ID should be performed according to rules defined in xep-0000-SN-Interoperability. +
    • +
+ + +

+ This section shows how a provisioning server can be used to restrict access to node parameters that users allowed to access and edit. +

+

+ +

+
    +
  • + Not that privileges for all parameters needs to be checked in every call. And if lost from the cache, a new request needs to be made to the provisioning server. +
    • +
  • + The conversion of a Parameter ID (and Page) to a Privilege ID should be performed according to rules defined in + xep-0000-SN-Interoperability. +
    • +
+ + +

+ This section shows how a provisioning server can be used to restrict access to node commands to users allowed to access those commands. +

+

+ +

+

+ In addition to rules noted above, also notice the following: +

+
    +
  • + Not that privileges for all parameters needs to be checked in every call. And if lost from the cache, a new request needs to be made to the provisioning server. +
    • +
  • + The conversion of a Command ID to a Privilege ID should be performed according to rules defined in xep-0000-SN-Interoperability. +
    • +
+ + + + +

This document requires no interaction with &IANA;.

+ + +

REQUIRED.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +]]> + + + +

Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.

+ + \ No newline at end of file From 7f14caeb2f5ed8cdc7b498ac31fd69f605101c5a Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 14:06:54 -0600 Subject: [PATCH 10/12] added XEPs 0320 through 0324 --- xep.ent | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/xep.ent b/xep.ent index d58c21ab..dad213d3 100644 --- a/xep.ent +++ b/xep.ent @@ -1267,3 +1267,8 @@ IANA Service Location Protocol, Version 2 (SLPv2) Templates Hats XEP-0317: Hats <http://xmpp.org/extensions/xep-0317.html>." > Last Presence using Delayed Delivery XEP-0318: Last Presence using Delayed Delivery <http://xmpp.org/extensions/xep-0318.html>." > Last User Interaction in Presence XEP-0319: Last User Interaction in Presence <http://xmpp.org/extensions/xep-0319.html>." > +Use of DTLS-SRTP in Jingle Sessions XEP-0320: Use of DTLS-SRTP in Jingle Sessions <http://xmpp.org/extensions/xep-0320.html>." > +Remote Roster Management XEP-0321: Remote Roster Management <http://xmpp.org/extensions/xep-0321.html>." > +Efficient XML Interchange (EXI) Format XEP-0322: Efficient XML Interchange (EXI) Format <http://xmpp.org/extensions/xep-0322.html>." > +Sensor Networks - Sensor Data XEP-0323: Sensor Networks - Sensor Data <http://xmpp.org/extensions/xep-0323.html>." > +Sensor Networks - Provisioning XEP-0324: Sensor Networks - Provisioning <http://xmpp.org/extensions/xep-0324.html>." > From e574ff82c6b0e55994545279088ea42ce4f107d4 Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 14:07:31 -0600 Subject: [PATCH 11/12] 0.1 --- xep-0320.xml | 10 +- xep-0321.xml | 590 +++++++++++++++++++++++++-------------------------- xep-0322.xml | 22 +- xep-0323.xml | 19 +- xep-0324.xml | 24 +-- 5 files changed, 333 insertions(+), 332 deletions(-) diff --git a/xep-0320.xml b/xep-0320.xml index 6dae5254..58412a49 100644 --- a/xep-0320.xml +++ b/xep-0320.xml @@ -9,8 +9,8 @@ Use of DTLS-SRTP in Jingle Sessions This specification defines how to use DTLS-SRTP (RFC 5763) in the Jingle application type for the Real-time Transport Protocol (RTP) as a way to negotiate media path key agreement for secure RTP in one-to-one media sessions. &LEGALNOTICE; - xxxx - ProtoXEP + 0320 + Experimental Standards Track Standards Council @@ -31,6 +31,12 @@ --> jingle &fippo; + + 0.1 + 2013-04-16 + psa +

Initial published version approved by the XMPP Council.

 + 0.0.2 2013-02-18 diff --git a/xep-0321.xml b/xep-0321.xml index 25c219d6..42c6773e 100644 --- a/xep-0321.xml +++ b/xep-0321.xml @@ -1,295 +1,295 @@ - - -%ents; -]> - - -
- Remote Roster Management - This document defines a way remote entities may manage user's roster to provide a simple way to keep rosters in sync. - - This XMPP Extension Protocol is copyright (c) 1999 - 2012 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the 'Specification'), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - xxxx - ProtoXEP - Standards Track - Standards - Council - - XMPP Core - XEP-0001 - XEP-0004 - XEP-0100 - - - - NOT_YET_ASSIGNED - - Sergey - Dobrov - binary@jrudevels.org - binary@jrudevels.org - - - Jan - Kaluža - hanzz.k@gmail.com - hanzz@njs.netlab.cz - - - 0.0.1 - 2012-12-07 - snd -

First draft.

 - -
- -

It's often desirable for some XMPP based services to make it possible to manage user's roster to provide some contacts there. The most obvious example of such kind of service is a gateway to some legacy IM system (see &xep0100;). The current way that's recommended by the &xep0100; is to use the &xep0144; to synchronize items that's not sutiable in certain situations.

- - -

This document addresses the following requirements:

-
    -
  1. Make it possible for remote services or entities to manage user's roster by the same mechanisms that descibed in the &rfc6121;.
    2. -
  2. Provide a way for user to control which services have permission to manage his roster.
    3. -
- - -
    -
  • Remote entity — the entity that wants to modify user's roster.
    • -
  • User — the entity which roster the remote entity wants to have access to.
    • -
  • User's server — the XMPP server User connected to.
    • -
  • Roster — the list of User's contacts as defined in the &rfc6121;.
    • -
- - - -

In order to be able to make any changes to the user's roster the remote entity MUST ask permission to do so first.

-

NOTE: in order to be able to perform the query, the remote entity MUST have a presence subscription to the User

- - -]]> -

If the presence subscription is absent, the server MUST NOT proceed with the request but MUST respond with the "forbidden" error:

- - - - You must have a presence subscription to be able to request remote roster management service. - -]]> -

The user's server SHOULD then generate a form request using &xep0004; to client in order to ask user if he's OK with granting the permission to the remote entity. The "challenge" form field is generated by the server and is used to identify the client's response. The server also MUST immediatly answer to the request IQ.

-

NOTE: if the entity is already granted with the permission, the server SHOULD immediatly answer with a success response and skip querying the user.

- - icq.example.com wants to be able to manage your roster with following reason: - Manage contacts in the ICQ contact list - Do you want to allow it? Send "yes 5439123" or "no 5439123" back, pleas. - - Roster management permission request - icq.example.com wants to be able to manage your roster with following reason: - Manage contacts in the ICQ contact list. - Do you allow it? - 5439123 - - urn:xmpp:tmp:roster-management:0 - - - 1 - - -]]> -

The client can answer by submit the form or with a text message response:

- - - - urn:xmpp:tmp:roster-management:0 - - 5439123 - 1 - -]]> - - yes 5439123 -]]> - -

If the user allowed the roster management then the server MUST inform the remote entity that it has been granted the permission:

- - -]]> - - -

If the user disallowed the roster management then the server MUST inform the remote entity that it hasn't been granted the permission:

- - -]]> - - -

In order to reject the permission to manage roster it's enough to reject entity's presence subscription:

- ]]> -

If the presence subscription is restored then the permission is needed to be rerequested as defined above.

- - - -

The remote entity being granted the permission to manage roster can request it from the User's server using usual jabber:iq:roster protocol to be able to edit it:

- - -]]> -

The server MUST then answer with User's roster including there only the items that belongs to the entity's hostname:

- - - - Friends - - - Friends - - - Friends - - -]]> - - -

If client updates roster and this update affects the remote entity's contacts (i.e. belongs to it's hostname) then the server MUST forward these items to the remote entity:

- - - - Friends - Lovers - - -]]> - - - - Friends - Lovers - - -]]> - - -

The remote entity can also send the push query to the roster with the same semantics as specified for the jabber:iq:roster protocol described in the &rfc6121;:

- - - - Friends - Lovers - - -]]> -

The server MUST then inform the remote entity of success or an error and in the case of success also forward the push request to all connected User's resources.

-

If the entity tries to make changes into the items it's not allowed to, the server MUST NOT do any changes in the User's roster but respond to the entity with an error:

- - - You have tried to modify the item you don't allowed to. -]]> - - -

User can ask the server to provide a list of components or servers which have permissions to edit their roster.

- - - - ]]> -

In this case, server responds with list of components or servers which can edit user's roster.

- - - - - - - ]]> -

Eventually, user can reject permission granted to component to edit their roster.

- - - - - ]]> - - - - - - - - - - The protocol documented by this schema is defined in - XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ]]> - - + + +%ents; +]> + + +
+ Remote Roster Management + This document defines a way remote entities may manage user's roster to provide a simple way to keep rosters in sync. + &LEGALNOTICE; + 0321 + Experimental + Standards Track + Standards + Council + + XMPP Core + XEP-0001 + XEP-0004 + XEP-0100 + + + + NOT_YET_ASSIGNED + + Sergey + Dobrov + binary@jrudevels.org + binary@jrudevels.org + + + Jan + Kaluža + hanzz.k@gmail.com + hanzz@njs.netlab.cz + + + 0.1 + 2013-04-16 + psa +

Initial published version approved by the XMPP Council.

 + + + 0.0.1 + 2012-12-07 + snd +

First draft.

 + +
+ +

It's often desirable for some XMPP based services to make it possible to manage user's roster to provide some contacts there. The most obvious example of such kind of service is a gateway to some legacy IM system (see &xep0100;). The current way that's recommended by the &xep0100; is to use the &xep0144; to synchronize items that's not sutiable in certain situations.

+ + +

This document addresses the following requirements:

+
    +
  1. Make it possible for remote services or entities to manage user's roster by the same mechanisms that descibed in the &rfc6121;.
    2. +
  2. Provide a way for user to control which services have permission to manage his roster.
    3. +
+ + +
    +
  • Remote entity — the entity that wants to modify user's roster.
    • +
  • User — the entity which roster the remote entity wants to have access to.
    • +
  • User's server — the XMPP server User connected to.
    • +
  • Roster — the list of User's contacts as defined in the &rfc6121;.
    • +
+ + + +

In order to be able to make any changes to the user's roster the remote entity MUST ask permission to do so first.

+

NOTE: in order to be able to perform the query, the remote entity MUST have a presence subscription to the User

+ + +]]> +

If the presence subscription is absent, the server MUST NOT proceed with the request but MUST respond with the "forbidden" error:

+ + + + You must have a presence subscription to be able to request remote roster management service. + +]]> +

The user's server SHOULD then generate a form request using &xep0004; to client in order to ask user if he's OK with granting the permission to the remote entity. The "challenge" form field is generated by the server and is used to identify the client's response. The server also MUST immediatly answer to the request IQ.

+

NOTE: if the entity is already granted with the permission, the server SHOULD immediatly answer with a success response and skip querying the user.

+ + icq.example.com wants to be able to manage your roster with following reason: + Manage contacts in the ICQ contact list + Do you want to allow it? Send "yes 5439123" or "no 5439123" back, pleas. + + Roster management permission request + icq.example.com wants to be able to manage your roster with following reason: + Manage contacts in the ICQ contact list. + Do you allow it? + 5439123 + + urn:xmpp:tmp:roster-management:0 + + + 1 + + +]]> +

The client can answer by submit the form or with a text message response:

+ + + + urn:xmpp:tmp:roster-management:0 + + 5439123 + 1 + +]]> + + yes 5439123 +]]> + +

If the user allowed the roster management then the server MUST inform the remote entity that it has been granted the permission:

+ + +]]> + + +

If the user disallowed the roster management then the server MUST inform the remote entity that it hasn't been granted the permission:

+ + +]]> + + +

In order to reject the permission to manage roster it's enough to reject entity's presence subscription:

+ ]]> +

If the presence subscription is restored then the permission is needed to be rerequested as defined above.

+ + + +

The remote entity being granted the permission to manage roster can request it from the User's server using usual jabber:iq:roster protocol to be able to edit it:

+ + +]]> +

The server MUST then answer with User's roster including there only the items that belongs to the entity's hostname:

+ + + + Friends + + + Friends + + + Friends + + +]]> + + +

If client updates roster and this update affects the remote entity's contacts (i.e. belongs to it's hostname) then the server MUST forward these items to the remote entity:

+ + + + Friends + Lovers + + +]]> + + + + Friends + Lovers + + +]]> + + +

The remote entity can also send the push query to the roster with the same semantics as specified for the jabber:iq:roster protocol described in the &rfc6121;:

+ + + + Friends + Lovers + + +]]> +

The server MUST then inform the remote entity of success or an error and in the case of success also forward the push request to all connected User's resources.

+

If the entity tries to make changes into the items it's not allowed to, the server MUST NOT do any changes in the User's roster but respond to the entity with an error:

+ + + You have tried to modify the item you don't allowed to. +]]> + + +

User can ask the server to provide a list of components or servers which have permissions to edit their roster.

+ + + + ]]> +

In this case, server responds with list of components or servers which can edit user's roster.

+ + + + + + + ]]> +

Eventually, user can reject permission granted to component to edit their roster.

+ + + + + ]]> + + + + + + + + + + The protocol documented by this schema is defined in + XEP-XXXX: http://www.xmpp.org/extensions/xep-xxxx.html + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ]]> + + diff --git a/xep-0322.xml b/xep-0322.xml index 4bb5d667..e9017670 100644 --- a/xep-0322.xml +++ b/xep-0322.xml @@ -9,17 +9,9 @@
Efficient XML Interchange (EXI) Format This specification describes how EXI compression can be used in XMPP networks. - - This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - - xxxx - ProtoXEP + &LEGALNOTICE; + 0322 + Experimental Standards Track Standards Council @@ -38,6 +30,12 @@ peter.waher@jabber.org http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + 0.1 + 2013-04-16 + psa +

Initial published version approved by the XMPP Council.

 + 0.0.4 2013-03-19 @@ -835,4 +833,4 @@

Thanks to Joachim Lindborg, Yusuke Doi, Takuki Kamiya, Tina Beckman, Karin Forsell, Jeff Freund and Rumen Kyusakov for all valuable feedback.

 - \ No newline at end of file + diff --git a/xep-0323.xml b/xep-0323.xml index 1287730c..ad8e7536 100644 --- a/xep-0323.xml +++ b/xep-0323.xml @@ -8,15 +8,8 @@
Sensor Networks - Sensor Data This specification provides the common framework for sensor data interchange over XMPP networks. - - This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - xxxx - ProtoXEP + 0323 + Experimental Standards Track Standards Council @@ -35,6 +28,12 @@ peter.waher@jabber.org http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + 0.1 + 2013-04-16 + psa +

Initial published version approved by the XMPP Council.

 + 0.0.5 2013-04-01 @@ -1427,4 +1426,4 @@

Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman, Kevin Smith and Tobias Markmann for all valuable feedback.

 - \ No newline at end of file + diff --git a/xep-0324.xml b/xep-0324.xml index e1d0746d..038c579c 100644 --- a/xep-0324.xml +++ b/xep-0324.xml @@ -8,17 +8,9 @@
Sensor Networks - Provisioning This specification describes an architecture for efficient provisioning of services, access rights and user privileges in sensor networks. - - This XMPP Extension Protocol is copyright (c) 1999 - 2013 by the XMPP Standards Foundation (XSF). - Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation. - ## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ## - In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages. - - This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://www.xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA). - - - xxxx - ProtoXEP + &LEGALNOTICE; + 0324 + Experimental Standards Track Standards Council @@ -26,7 +18,7 @@ XMPP Core XEP-0001 XEP-0030 - sensor-data + XEP-0323 @@ -38,6 +30,12 @@ peter.waher@jabber.org http://se.linkedin.com/pub/peter-waher/1a/71b/a29/ + + 0.1 + 2013-04-16 + psa +

Initial published version approved by the XMPP Council.

 + 0.0.5 2013-04-04 @@ -1669,4 +1667,4 @@

Thanks to Joachim Lindborg and Karin Forsell for all valuable feedback.

 - \ No newline at end of file + From 75cf6b1d36b5a58962b3b443c3f8edb72b2bd72f Mon Sep 17 00:00:00 2001 From: stpeter Date: Tue, 16 Apr 2013 14:10:13 -0600 Subject: [PATCH 12/12] Proposed --- xep-0220.xml | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/xep-0220.xml b/xep-0220.xml index 83299bc5..39128b45 100644 --- a/xep-0220.xml +++ b/xep-0220.xml @@ -10,7 +10,8 @@ This specification defines the Server Dialback protocol, which is used between XMPP servers to provide identity verification. Server Dialback uses the Domain Name System (DNS) as the basis for verifying identity; the basic approach is that when a receiving server accepts a server-to-server connection from an initiating server, it does not process traffic over the connection until it has verified the initiating server's key with an authoritative server for the domain asserted by the initiating server. Additionally, the protocol is used to negotitate whether the receiving server is accepting stanzas for the target domain. Although Server Dialback does not provide strong authentication and it is subject to DNS poisoning attacks, it has effectively prevented address spoofing on the XMPP network since its development in the year 2000. &LEGALNOTICE; 0220 - Experimental + Proposed + 2013-05-10 Standards Track Standards Council @@ -22,11 +23,7 @@ dialback &jer; &stpeter; - - Philipp - Hancke - fippo@psyced.org - + &fippo; 0.14 ph