diff --git a/xep-0323.xml b/xep-0323.xml
index bf6eee42..bfa9bcd7 100644
--- a/xep-0323.xml
+++ b/xep-0323.xml
@@ -1,7 +1,7 @@
- %ents;
+
+ %ents;
]>
Updated contact information. Updated example JIDs to example.org Updated example JIDs to example.org
@@ -479,12 +479,12 @@
@@ -493,16 +493,16 @@
Depending on the reason for rejecting the request, different XMPP errors can be returned, according to the description in the following table. The table also
@@ -597,76 +597,76 @@
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,
@@ -1410,257 +1410,257 @@
Updated contact information. Updated example JIDs to example.org Element renamed from Friend to friend when recommending friendships. clearCache IQ stanzas now of type set instead of get. Corrected schema with regards to tokens. The getToken command now takes a base-64 encoded X.509 certificate (public part) instead of arbitrary string IDs. An additional challenge/response step has been added to make sure the sender of a certificate has access to the private part of the certificate. Named links to all sections in the document. Added reference to XEP-0347, for how things can find provisioning servers. Added method of finding provisioning server, if server hosted as a server component. Updated examples to reflect a provisioning server hosted as a server component, harmonizing with XEP-0347. Added a section about token challenges and token propagation. Added a security note regarding token challenges. Updated id-attributes in examples. Corrected downloadPrivileges example. Made several corrections of the language. Expanded the introduction. Changes "Sensor Networks" to "Internet of Things". Fixed links to documents with new numbers. Changed namespace urn:xmpp:sn to urn:xmpp:iot Initial published version approved by the XMPP Council. Added control use cases. Grouped use cases. 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. Added information about how to read sensors from large subsystems. Added friend recommendation message. Added client/device/service tokens. Added use cases for service access rights and corresponding user privileges. First draft.
- This specification describes an architecture for efficient provisioning of services, access rights and user privileges in for the Internet of Things, where
- communication between Things is done using the XMPP protocol.
-
- Note has to be taken, that this XEP, and other Internet of Things-related XEP's, are designed for implementation in small devices, many of which have very limited
- amount of memory (both RAM and ROM) or resources (processing power). Therefore, simplicity is of utmost importance. Furthermore, Internet of Things networks can
- become huge, easily containing millions or billions of devices in peer-to-peer networks.
+ Updated contact information. Updated example JIDs to example.org Element renamed from Friend to friend when recommending friendships. clearCache IQ stanzas now of type set instead of get. Corrected schema with regards to tokens. The getToken command now takes a base-64 encoded X.509 certificate (public part) instead of arbitrary string IDs. An additional challenge/response step has been added to make sure the sender of a certificate has access to the private part of the certificate. Named links to all sections in the document. Added reference to XEP-0347, for how things can find provisioning servers. Added method of finding provisioning server, if server hosted as a server component. Updated examples to reflect a provisioning server hosted as a server component, harmonizing with XEP-0347. Added a section about token challenges and token propagation. Added a security note regarding token challenges. Updated id-attributes in examples. Corrected downloadPrivileges example. Made several corrections of the language. Expanded the introduction. Changes "Sensor Networks" to "Internet of Things". Fixed links to documents with new numbers. Changed namespace urn:xmpp:sn to urn:xmpp:iot Initial published version approved by the XMPP Council. Added control use cases. Grouped use cases. 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. Added information about how to read sensors from large subsystems. Added friend recommendation message. Added client/device/service tokens. Added use cases for service access rights and corresponding user privileges. First draft.
+ This specification describes an architecture for efficient provisioning of services, access rights and user privileges in for the Internet of Things, where
+ communication between Things is done using the XMPP protocol.
+
+ Note has to be taken, that this XEP, and other Internet of Things-related XEP's, are designed for implementation in small devices, many of which have very limited
+ amount of memory (both RAM and ROM) or resources (processing power). Therefore, simplicity is of utmost importance. Furthermore, Internet of Things networks can
+ become huge, easily containing millions or billions of devices in peer-to-peer networks.
+
+ An added complexity in the provisioning case is that Things (small sensors for example) 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 document defines the following important operations to allow for efficient provisioning of services in the Internet of Things, based on XMPP:
+
+ This XEP relies on &xep0323; and &xep0325; for sensor data readout and control interfaces. It relies on &xep0326; for bridging protocols and interfaing entities with multiple devices
+ behind them. It also ties into &xep0347; for automatic discovery of provisioning servers by things.
+
+ Internet of Things contain many different architectures and use cases. For this reason, the IoT standards have been divided into multiple XEPs according to the following table:
+ The following table lists common terms and corresponding descriptions.
+ 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:
+
+ A provisioning server can be accessed either through a JID published by the provisioning server, or through a subdomain address, if hosted as a server component.
+ This section will show how to delegate original trust to a Provisioning Server, in the case the server uses a JID to communicate with things.
- An added complexity in the provisioning case is that Things (small sensors for example) 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 document defines the following important operations to allow for efficient provisioning of services in the Internet of Things, based on XMPP:
-
- This XEP relies on &xep0323; and &xep0325; for sensor data readout and control interfaces. It relies on &xep0326; for bridging protocols and interfaing entities with multiple devices
- behind them. It also ties into &xep0347; for automatic discovery of provisioning servers by things.
-
- Internet of Things contain many different architectures and use cases. For this reason, the IoT standards have been divided into multiple XEPs according to the following table:
- The following table lists common terms and corresponding descriptions.
- 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:
+ 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.
- A provisioning server can be accessed either through a JID published by the provisioning server, or through a subdomain address, if hosted as a server component.
- This section will show how to delegate original trust to a Provisioning Server, in the case the server uses a JID to communicate with things.
-
- 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.
-
- The following diagram shows the general case:
-
-
-
- The successful case can also be illustrated in a sequence diagram, as follows:
-
-
-
- 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 be necessary. 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.
-
- Note 2: A certificate token has an undefined lifetime. It can be reused across sessions.
-
- The following use cases will assume such a trust relationship has been created between the corresponding device and the provisioning server.
-
- A provisioning server can also be hosted as a server component, and in these cases be addressed by using the component address, or sub-domain address of the component.
- In this case, the client searches through the components hosted by the server to see if one of them is a Provisioning Server. There are no friendship requests and
- presence subscriptions necessary, when communicating with a Provisioning Server hosted as a server component.
-
- To search for a Provisioning Server hosted as a component on an XMPP Server, you first request a list of available components, as follows:
-
+ The following diagram shows the general case:
+
+
+
+ The successful case can also be illustrated in a sequence diagram, as follows:
+
+
+
+ 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 be necessary. 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.
+
+ Note 2: A certificate token has an undefined lifetime. It can be reused across sessions.
+
+ The following use cases will assume such a trust relationship has been created between the corresponding device and the provisioning server.
+
+ A provisioning server can also be hosted as a server component, and in these cases be addressed by using the component address, or sub-domain address of the component.
+ In this case, the client searches through the components hosted by the server to see if one of them is a Provisioning Server. There are no friendship requests and
+ presence subscriptions necessary, when communicating with a Provisioning Server hosted as a server component.
+
+ To search for a Provisioning Server hosted as a component on an XMPP Server, you first request a list of available components, as follows:
+
- If components (items) are supported, a request for available components is made:
-
- The client then loops through all components (items) and checks what features they support, until a Provisioning Server is found:
-
- The provisioning server contains a set of rules defining what operation can take place and by whom, by participants in the network. Rules can be applied based on JIDs used,
- content affected, and also through device, service and user identities based on X.509 Certificates. In order for a service (for instance) to identify itself in the network, it
- uses an X.509 certificate. It sends the public part of this certificate to the provisioning server, and receives a token back in the form of a simple string. This token can then
- be used in requests and propagated through the network.
-
- To validate that the sender is allowed to use the certificate using its token, it encrypts a challenge using the public part of the certificate and sends it to the sender of the
- token, who in turn decrypts it using the private part of the certificate and returns it to the server. The provisioning server can also use the public part of the certificate to
- perform validation checks on the certificate itself. If the certificate becomes invalid, the provisioning server can invalidate any corresponding rules in the network. If the sender
- of a token cannot respond to a token challenge, the provisioning server can also refuse to allow the operation.
-
- In case of multiple units being part of an operation, a token can be propagated in the network. For example, a service can read data from U1, who reads data from U2. The service
- provides a token to U1, who propagates this token in the request to U2. When U2 asks the provisioning server if the operation should be allowed or not, the server knows what entity
- originated the request. If the provisioning server wants to challenge U2, concerning the token, U2 propagates the challenge to U1, who propagates it to the service, who can resolve
- the challenge, returns the response back to U1 who returns the response to U2 who in turn returns it to the provisioning server.
-
-
-
- The following example shows how a device or service can request a token from the provisioning server, by providing the base-64 encoded public part of an X.509 certificate.
- This step is optional, but can be used as a method to identify the device (or service), apart from the JID it is using. This might be useful if you want to assign a particular
- device or service privileges in the provisioning server, regardless of the JID it uses to perform the action.
-
- The getToken element contains the base-64 encoded public version of the certificate that is used to identify the device or service. The server
- responds with a challenge in a getTokenChallenge response. This challenge is also a base-64 encoded binary block of data, which corresponds to a random
- sequence of bytes that is then encrypted using the public certificate. Now, the device, or service, decrypts this challenge using the private part of the certificate, and
- returns the base-64 encoded decrypted version of the challenge back to the provisioning server using the getTokenChallengeResponse element. The provisioning
- server checks the response to the original random sequence of bytes. If equal, the provisioning server responds with a getTokenResponse result, containing
- the token (a string this time) that can be used when reference to the identity defined by the certificate has to be made. The provisioning server must not return tokens that
- contain white space characters.
-
- If the response to the challenge is wrong, the server returns a bad-request error result, as is shown below.
-
- If the sequence number identifying the challenge is not found on the server, the server returns a item-not-found error result, as is shown below.
-
- The server must retain the challenge in memory for at least one minute before assuming the challenge will go unresponded.
-
- For reasons the provisioning server determines, it can challenge the use of a token in any of the requests made to it. This is done by sending a
- iq get stanza with a tokenChallenge to the party sending the token. This element contains both the token being challenged, and a binary
- challenge. This challenge is made up of a random block of data that is encrypted using the public certificate referred to by the token.
-
- The receiver of the challenge, if it has access to the private certificate referenced, decrypts the challenge, and returns the decrypted binary block of data
- to the caller (i.e. the Provisioning Server in this case). If the decrypted block of data corresponds to the original random block of data encrypted, the sender
- of the token is considered to be allowed to use the token.
-
- If the received of the challenge does not have access to the private certificate referenced, but used the token in a propagated request made to it, it can propagate the
- request to the original sender of the token. When the response is returned, it returns the response in turn to the sender of the challenge.
-
- A challenge/response sequence can look as follows:
-
- Note: It is important that a unit only responds to a tokenChallenge request from a JID to which the corresponding token
- has been sent. If a token challenge is received from a JID to which the token has not been sent the last minute, the following error message must be returned:
-
- 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.
-
- Note: When a provisioning server wants to challenge multiple tokens, separate token challenges are sent, one for each token being challenged.
-
- 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-0323
- Internet of Things - Sensor Data.
-
- The following example shows the communication first between the client and the device, then between 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 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-0323
- Internet of Things - 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 between 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 between 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 a list of both 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 between 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 between 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 between 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 a list of both 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, by providing a base-64 encoded X.509 certificate.
- 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:
-
- 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.
-
- 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 Privilege IDs, with suggestive descriptions. (Only used as an example.)
-
- 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:
-
- 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.
-
- Note: If the user or service has not been correctly identified, logged in, etc., the resulting list must only include privileges
- that default users that are not logged in can have. This list can be empty.
-
- If an entity is a Provisioning Server and supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:provisioning"
- in response to &xep0030; information requests.
-
+ The client then loops through all components (items) and checks what features they support, until a Provisioning Server is found:
+
- 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.
+ The provisioning server contains a set of rules defining what operation can take place and by whom, by participants in the network. Rules can be applied based on JIDs used,
+ content affected, and also through device, service and user identities based on X.509 Certificates. In order for a service (for instance) to identify itself in the network, it
+ uses an X.509 certificate. It sends the public part of this certificate to the provisioning server, and receives a token back in the form of a simple string. This token can then
+ be used in requests and propagated through the network.
- A client must treat the connection between a Provisioning Server differently if it is hosted as a client, having a JID, or if it is hosted as a Jabber Server Component.
- If it is hosted as a server component, there's no need for the thing to become friends with the Provisioning Server. Messages and requests can be made directly to the
- server component without having to add it to the roster or request presence subscriptions. If the Provisioning Server is hosted as a client, having a JID (@ in the address),
- the Provisioning Server must be added to the roster of the client before the client can communicate with the Provisioning Server.
-
- 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:
-
- 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 Internet of Things - Concentrators
- Internet of Things - Concentrators. 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
- Internet of Things - Concentrators.
-
- 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:
-
- When receiving token challenges from somebody, make sure you've sent the corresponding token to the corresponding party less than a minute before receiving the token
- challenge. If not, the token challenge might represent a malicious attempt by somebody else to use the token to gain privileges in the network otherwise not enjoyed.
- This document requires no interaction with &IANA;.
- The protocol schema needs to be added to the list of XMPP protocol schemas.
-
+ To validate that the sender is allowed to use the certificate using its token, it encrypts a challenge using the public part of the certificate and sends it to the sender of the
+ token, who in turn decrypts it using the private part of the certificate and returns it to the server. The provisioning server can also use the public part of the certificate to
+ perform validation checks on the certificate itself. If the certificate becomes invalid, the provisioning server can invalidate any corresponding rules in the network. If the sender
+ of a token cannot respond to a token challenge, the provisioning server can also refuse to allow the operation.
+
+ In case of multiple units being part of an operation, a token can be propagated in the network. For example, a service can read data from U1, who reads data from U2. The service
+ provides a token to U1, who propagates this token in the request to U2. When U2 asks the provisioning server if the operation should be allowed or not, the server knows what entity
+ originated the request. If the provisioning server wants to challenge U2, concerning the token, U2 propagates the challenge to U1, who propagates it to the service, who can resolve
+ the challenge, returns the response back to U1 who returns the response to U2 who in turn returns it to the provisioning server.
+
+
+
+ The following example shows how a device or service can request a token from the provisioning server, by providing the base-64 encoded public part of an X.509 certificate.
+ This step is optional, but can be used as a method to identify the device (or service), apart from the JID it is using. This might be useful if you want to assign a particular
+ device or service privileges in the provisioning server, regardless of the JID it uses to perform the action.
+
+ The getToken element contains the base-64 encoded public version of the certificate that is used to identify the device or service. The server
+ responds with a challenge in a getTokenChallenge response. This challenge is also a base-64 encoded binary block of data, which corresponds to a random
+ sequence of bytes that is then encrypted using the public certificate. Now, the device, or service, decrypts this challenge using the private part of the certificate, and
+ returns the base-64 encoded decrypted version of the challenge back to the provisioning server using the getTokenChallengeResponse element. The provisioning
+ server checks the response to the original random sequence of bytes. If equal, the provisioning server responds with a getTokenResponse result, containing
+ the token (a string this time) that can be used when reference to the identity defined by the certificate has to be made. The provisioning server must not return tokens that
+ contain white space characters.
+
+ If the response to the challenge is wrong, the server returns a bad-request error result, as is shown below.
+
+ If the sequence number identifying the challenge is not found on the server, the server returns a item-not-found error result, as is shown below.
+
+ The server must retain the challenge in memory for at least one minute before assuming the challenge will go unresponded.
+
+ For reasons the provisioning server determines, it can challenge the use of a token in any of the requests made to it. This is done by sending a
+ iq get stanza with a tokenChallenge to the party sending the token. This element contains both the token being challenged, and a binary
+ challenge. This challenge is made up of a random block of data that is encrypted using the public certificate referred to by the token.
+
+ The receiver of the challenge, if it has access to the private certificate referenced, decrypts the challenge, and returns the decrypted binary block of data
+ to the caller (i.e. the Provisioning Server in this case). If the decrypted block of data corresponds to the original random block of data encrypted, the sender
+ of the token is considered to be allowed to use the token.
+
+ If the received of the challenge does not have access to the private certificate referenced, but used the token in a propagated request made to it, it can propagate the
+ request to the original sender of the token. When the response is returned, it returns the response in turn to the sender of the challenge.
+
+ A challenge/response sequence can look as follows:
+
+ Note: It is important that a unit only responds to a tokenChallenge request from a JID to which the corresponding token
+ has been sent. If a token challenge is received from a JID to which the token has not been sent the last minute, the following error message must be returned:
+
+ 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.
+
+ Note: When a provisioning server wants to challenge multiple tokens, separate token challenges are sent, one for each token being challenged.
+
+ 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-0323
+ Internet of Things - Sensor Data.
+
+ The following example shows the communication first between the client and the device, then between 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 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-0323
+ Internet of Things - 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 between 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 between 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 a list of both 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 between 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 between 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 between 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 a list of both 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, by providing a base-64 encoded X.509 certificate.
+ 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:
+
+ 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.
+
+ 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 Privilege IDs, with suggestive descriptions. (Only used as an example.)
+
+ 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:
+
+ 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.
+
+ Note: If the user or service has not been correctly identified, logged in, etc., the resulting list must only include privileges
+ that default users that are not logged in can have. This list can be empty.
+
+ If an entity is a Provisioning Server and supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot: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.
+
+ A client must treat the connection between a Provisioning Server differently if it is hosted as a client, having a JID, or if it is hosted as a Jabber Server Component.
+ If it is hosted as a server component, there's no need for the thing to become friends with the Provisioning Server. Messages and requests can be made directly to the
+ server component without having to add it to the roster or request presence subscriptions. If the Provisioning Server is hosted as a client, having a JID (@ in the address),
+ the Provisioning Server must be added to the roster of the client before the client can communicate with the Provisioning Server.
+
+ 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:
+
+ 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 Internet of Things - Concentrators
+ Internet of Things - Concentrators. 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
+ Internet of Things - Concentrators.
+
+ 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:
+
+ When receiving token challenges from somebody, make sure you've sent the corresponding token to the corresponding party less than a minute before receiving the token
+ challenge. If not, the token challenge might represent a malicious attempt by somebody else to use the token to gain privileges in the network otherwise not enjoyed.
+ This document requires no interaction with &IANA;.
+ The protocol schema needs to be added to the list of XMPP protocol schemas.
+
- For more information, please see the following resources:
-
- The Sensor Network section of the XMPP Wiki contains further information about the
- use of the sensor network XEPs, links to implementations, discussions, etc.
-
- The XEP's and related projects are also available on github, thanks to Joachim Lindborg.
-
- A presentation giving an overview of all extensions related to Internet of Things can be found here:
- http://prezi.com/esosntqhewhs/iot-xmpp/.
- Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Teemu Väisänen for all valuable feedback.
+ For more information, please see the following resources:
+
+ The Sensor Network section of the XMPP Wiki contains further information about the
+ use of the sensor network XEPs, links to implementations, discussions, etc.
+
+ The XEP's and related projects are also available on github, thanks to Joachim Lindborg.
+
+ A presentation giving an overview of all extensions related to Internet of Things can be found here:
+ http://prezi.com/esosntqhewhs/iot-xmpp/.
+ Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Teemu Väisänen for all valuable feedback.
+ 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:
+ The following table lists common terms and corresponding descriptions.
+ 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:
+
+ What type of control parameters there are available in different types of devices is described in
+
+ If the device is a concentrator, as defined in Internet of Things - Concentrators,
+ 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.
+
- 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.
+ 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:
+
+ Note: An empty setResponse element means that the control command was executed as provided in the request. Sometimes, the device
+ can restrict the command to a subset of nodes and/or parameters. In such cases, the setResponse element will contain what nodes and/or parameters
+ were finally used to perform the command. For examples of this, see &xep0324;.
- 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.
+ 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:
+
+ Here, the paramError element is used in the IQ Error response, to provide error information related to a specific control parameter.
+
+ 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 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.
- 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:
+ 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-IoT-Interoperability details what control parameters
+ must be available for different interfaces, and if the order of control parameters is important.
The following table lists common terms and corresponding descriptions.
- 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.
+ 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:
- 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:
-
- What type of control parameters there are available in different types of devices is described in
-
- If the device is a concentrator, as defined in Internet of Things - Concentrators,
- 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:
-
- Note: An empty setResponse element means that the control command was executed as provided in the request. Sometimes, the device
- can restrict the command to a subset of nodes and/or parameters. In such cases, the setResponse element will contain what nodes and/or parameters
- were finally used to perform the command. For examples of this, see &xep0324;.
-
- 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:
-
- Here, the paramError element is used in the IQ Error response, to provide error information related to a specific control parameter.
-
- 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 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-IoT-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:
-
- IMPORTANT: The device MUST mark all control parameters in the form as notSame, as defined in
-
- 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-0326
- Internet of Things - 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, 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:
-
- 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. If there are errors in the form, details are listed
- using paramError elements in the response, as is shown in the following example:
-
- 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:
-
- 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:
-
- 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. 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:
-
- A device can reject a control form submission. It does this returning an error iq stanza. 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.
- If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:control" in response to &xep0030; information requests.
+ IMPORTANT: The device MUST mark all control parameters in the form as notSame, as defined in
+
+ 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-0326
+ Internet of Things - 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, 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:
+
+ 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. If there are errors in the form, details are listed
+ using paramError elements in the response, as is shown in the following example:
+
+ 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:
+
+ 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:
+
+ 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. 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:
+
+ A device can reject a control form submission. It does this returning an error iq stanza. 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.
+ If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:control" 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.
-
- Depending on the reason for rejecting a control request, different XMPP errors can be returned, according to the description in the following table. The table also
- lists recommended error type for each error. Error stanzas may also include paramError child elements to provide additional textual error information that
- corresponds to a particular control parameter provided in the request. Any custom error message not related to control parameters is returned in a text
- element.
-
- The simplest way to read the current control states of a device, is to request the control form of the device. The control form should contain the current
- values for all avilable control parameters. However, since current states might not be available at the time of the request, the states might be delivered
- asynchronously, using messages defined in &xep0336;.
-
- Using this method has the advantage that a small actuator device does not need to implement other XEPs to support readout of current control states. If the device
- contains all current states readily accessible, there's no need of asynchronous updates making readout simple and straightforward.
-
- A second option is to use &xep0323; to deliver current control states. Since this XEP contains mechanisms allowing for asynchronous readout of control parameter
- states. This makes readout of such parameters simpler. However, there's a need to map values between the two XEPs.
-
- If a client wants to know the current status of control parameters using this method, it performs a readout of Momentary and Status values
- from the device, 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.
-
- To simplify mapping, a writable attribute can be used to inform the client if a field name corresponds to a control parameter or not. If the
- attribute is available, it tells the client if it corresponds to a control parameter or not. If not available, no such deduction can be made.
-
- 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, as described above.
-
- 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). An empty cell means conversion has no meaning and types are not compatible.
-
- The following table lists notes with details on how to do conversion, if in doubt.
-
- Note: the namespace prefix xs is here supposed to be linked with the XML Schema namespace
- http://www.w3.org/2001/XMLSchema.
-
- When representing control parameters as momentary field values, it is important to note the similarities and differences between XEP-0323 (Sensor Data) and XEP-0325 (this document):
-
- The enum field value data type is not available in XEP-0325 (this document). Instead enumeration valued parameters are represented as string control
- parameters, while the control form explicitly lists available options for the parameter. Options are not available in XEP-0323, since it would not be practical to list all options
- every time the corresponding parameter was read out. Instead, the enum element contains a data type attribute, that can be used to identify the type of the enumeration.
-
- The numeric field value data type is not available in XEP-0325 (this document). The reason is that a controller is not assumed to understand unit conversion. Any
- floating-point valued control parameters are represented by double control parameters, which lack a unit attribute. They are assumed to have the same unit as
- the corresponding numeric field value. On the other hand, floating point valued control parameters without units, are reported using the numeric
- field element, but leaving the unit blank.
-
- Control pameters of type color have no corresponding field value data type. The color value must be represented in another way, and is implementation specific.
- Possibilities include representing the color as a string, using a specific pattern (for instance RRGGBBAA), or report it using multiple fields, one for each component for instance.
-
- The boolean, date, dateTime, duration, int, long, string
- and time field value data types correspond to control parameters having the same types and same element names.
-
- A node defined in a concentrator, as defined by Internet of Things - Concentrators, 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 Internet of Things - Concentrators,
- 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 available in a device can be controlled using only one control parameter. If a device only publishes such control parameters, the order
- of control parameters 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.
-
- Note: If used, the server must not include a parameter in more than one parameter group at a time. The form may contain multiple group, but each
- parameter must only have at most one parameterGroup element.
-
- The following example illustrates the use of the parameterGroup element to group parameters together.
-
- 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-IoT-Interoperability.html,
- which defines a set of interoperable interfaces and their abilities.
-
- Nodes behind a concentrator, as defined in Internet of Things - Concentrators, 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-0324 &xep0324;,
- 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:
-
- For more information about provisioning, see Internet of Things - Provisioning.
-
- 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
- Internet of Things - Concentrators.
- 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
- Internet of Things - Concentrators.
-
- 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.
-
- 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.
-
+
+
+
+
+
+ XEP
+ Description
+
+
+ xep-0000-IoT-BatteryPoweredSensors
+ Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
+
+
+ xep-0000-IoT-Events
+ Defines how Things send events, how event subscription, hysteresis levels, etc., are configured.
+
+
+ xep-0000-IoT-Interoperability
+ Defines guidelines for how to achieve interoperability in Internet of Things, publishing interoperability interfaces for different types of devices.
+
+
+ xep-0000-IoT-Multicast
+ Defines how sensor data can be multicast in efficient ways.
+
+
+ xep-0000-IoT-PubSub
+ Defines how efficient publication of sensor data can be made in Internet of Things.
+
+
+ xep-0000-IoT-Chat
+ Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.
+
+
+ XEP-0322
+
+ Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not an Internet of Things specific XEP, this XEP should be considered
+ in all Internet of Things implementations where memory and packet size is an issue.
+
+
+
+ XEP-0323
+
+ 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
+ Internet of Things XEPs.
+
+
+
+ XEP-0324
+ This specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
+
+
+ XEP-0325
+ Defines how to control actuators and other devices in Internet of Things.
+
+
+ XEP-0326
+ Defines how to handle architectures containing concentrators or servers handling multiple Things.
+
+
+ XEP-0331
+ Defines extensions for how color parameters can be handled, based on &xep0004;
+
+
+ XEP-0336
+ Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
+
+
+ XEP-0347
+ Defines 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
- Description
-
-
- xep-0000-IoT-BatteryPoweredSensors
- Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
-
-
- xep-0000-IoT-Events
- Defines how Things send events, how event subscription, hysteresis levels, etc., are configured.
-
-
- xep-0000-IoT-Interoperability
- Defines guidelines for how to achieve interoperability in Internet of Things, publishing interoperability interfaces for different types of devices.
-
-
- xep-0000-IoT-Multicast
- Defines how sensor data can be multicast in efficient ways.
-
-
- xep-0000-IoT-PubSub
- Defines how efficient publication of sensor data can be made in Internet of Things.
-
-
- xep-0000-IoT-Chat
- Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.
-
-
- XEP-0322
-
- Defines how to EXI can be used in XMPP to achieve efficient compression of data. Albeit not an Internet of Things specific XEP, this XEP should be considered
- in all Internet of Things implementations where memory and packet size is an issue.
-
-
-
- XEP-0323
-
- 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
- Internet of Things XEPs.
-
-
-
- XEP-0324
- This specification. Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
-
-
- XEP-0325
- Defines how to control actuators and other devices in Internet of Things.
-
-
- XEP-0326
- Defines how to handle architectures containing concentrators or servers handling multiple Things.
-
-
- XEP-0331
- Defines extensions for how color parameters can be handled, based on &xep0004;
-
-
- XEP-0336
- Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
-
-
- XEP-0347
- Defines 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.
-
-
-
-
-
-
-
-
-
-
- Type
- Protocols
- Description
-
-
- JID
- XMPP
- Allows provisioning to be done on the JID the user has.
-
-
- IP Address
- HTTP, HTTPS
- Allows provisioning to be done on IP address or IP-ranges for instance.
-
-
- Host Name
- HTTP, HTTPS with DNS
- If the service has access to the client host name, for instance in an intra network, this can be used for provisioning.
-
-
- X.509 Certificate
- HTTPS
- If the client provides a client certificate, such a certificate can be used to provide provisioning.
-
-
- X.509 Certificate Thumbprint
- HTTPS
-
- 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 Name
- HTTP, 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.
-
-
-
- Geolocation
- HTML5 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 Token
- Intranet
- If a single sign on token is available, such a token could be provided as credentials.
-
-
- Protocol
- Any
- Connection protocol used to connect to the service.
-
-
-
-
- Privilege ID
- Description
-
-
- Databases.Energy.Select
- Gives the user the rights to select data from the Energy database.
-
-
- Databases.Energy.Insert
- Gives the user the rights to insert data into the Energy database.
-
-
- Databases.Energy.Delete
- Gives the user the rights to delete data from the Energy database.
-
-
-
-
-
-
-
+
+
+
+
+ Type
+ Protocols
+ Description
+
+
+ JID
+ XMPP
+ Allows provisioning to be done on the JID the user has.
+
+
+ IP Address
+ HTTP, HTTPS
+ Allows provisioning to be done on IP address or IP-ranges for instance.
+
+
+ Host Name
+ HTTP, HTTPS with DNS
+ If the service has access to the client host name, for instance in an intra network, this can be used for provisioning.
+
+
+ X.509 Certificate
+ HTTPS
+ If the client provides a client certificate, such a certificate can be used to provide provisioning.
+
+
+ X.509 Certificate Thumbprint
+ HTTPS
+
+ 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 Name
+ HTTP, 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.
+
+
+
+ Geolocation
+ HTML5 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 Token
+ Intranet
+ If a single sign on token is available, such a token could be provided as credentials.
+
+
+ Protocol
+ Any
+ Connection protocol used to connect to the service.
+
+
+
+
+ Privilege ID
+ Description
+
+
+ Databases.Energy.Select
+ Gives the user the rights to select data from the Energy database.
+
+
+ Databases.Energy.Insert
+ Gives the user the rights to insert data into the Energy database.
+
+
+ Databases.Energy.Delete
+ Gives the user the rights to delete data from the Energy database.
+
+
+
+
+
+
+
+
-
-
-
+
+
+
+
+
+ XEP
+ Description
+
+
+ xep-0000-IoT-BatteryPoweredSensors
+ Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
+
+
+ xep-0000-IoT-Discovery
+ Defines 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-IoT-Events
+ Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
+
+
+ xep-0000-IoT-Interoperability
+ Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
+
+
+ xep-0000-IoT-Multicast
+ Defines how sensor data can be multicast in efficient ways.
+
+
+ xep-0000-IoT-PubSub
+ Defines how efficient publication of sensor data can be made in sensor networks.
+
+
+ xep-0000-IoT-Chat
+ Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.
+
+
+ XEP-0322
+
+ 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-0323
+
+ 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.
+
+
+
+ XEP-0324
+ Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
+
+
+ XEP-0325
+ This specification. Defines how to control actuators and other devices in Internet of Things.
+
+
+ XEP-0326
+ Defines how to handle architectures containing concentrators or servers handling multiple sensors.
+
+
+ XEP-0331
+ Defines extensions for how color parameters can be handled, based on &xep0004;
+
+
+ XEP-0336
+ Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
+
+
+
+
+
-
-
-
- XEP
- Description
-
-
- xep-0000-IoT-BatteryPoweredSensors
- Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network.
-
-
- xep-0000-IoT-Discovery
- Defines 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-IoT-Events
- Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured.
-
-
- xep-0000-IoT-Interoperability
- Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices.
-
-
- xep-0000-IoT-Multicast
- Defines how sensor data can be multicast in efficient ways.
-
-
- xep-0000-IoT-PubSub
- Defines how efficient publication of sensor data can be made in sensor networks.
-
-
- xep-0000-IoT-Chat
- Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture.
-
-
- XEP-0322
-
- 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-0323
-
- 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.
-
-
-
- XEP-0324
- Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented.
-
-
- XEP-0325
- This specification. Defines how to control actuators and other devices in Internet of Things.
-
-
- XEP-0326
- Defines how to handle architectures containing concentrators or servers handling multiple sensors.
-
-
- XEP-0331
- Defines extensions for how color parameters can be handled, based on &xep0004;
-
-
- XEP-0336
- Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;.
-
-
-
-
-
-
-
-
- Error Type
- Error Element
- Namespace
- Description
-
-
- cancel
- forbidden
- urn:ietf:params:xml:ns:xmpp-stanzas
- If the caller lacks privileges to perform the action.
-
-
- cancel
- item-not-found
- urn:ietf:params:xml:ns:xmpp-stanzas
- If an item, parameter or data source could not be found.
-
-
- modify
- bad-request
- urn:ietf:params:xml:ns:xmpp-stanzas
- If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range.
-
-
- cancel
- feature-not-implemented
- urn:ietf:params:xml:ns:xmpp-stanzas
- If an action has not been implemented in the device.
-
-
- wait
- conflict
- urn:ietf:params:xml:ns:xmpp-stanzas
- If an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time.
-
-
-
-
-
-
- 325 \ 323
- boolean
- date
- dateTime
- duration
- enum
- int
- long
- numeric
- string
- time
-
-
- boolean
- x
-
-
-
-
- !=0
- !=0
- !=0
-
-
-
-
- color
-
-
-
-
-
-
-
-
- RRGGBB or RRGGBBAA
-
-
-
- date
-
- x
- Date part
-
-
-
-
-
- (1)
-
-
-
- dateTime
-
- x
- x
-
-
-
-
-
- (2)
-
-
-
- double
- Z2
-
-
-
-
- x
- x
- x
- (3)
-
-
-
- duration
-
-
-
- x
-
-
-
-
- (4)
- x
-
-
- int
- Z2
-
-
-
- Ordinal
- x
- Thunk
- Thunk
- (5)
-
-
-
- long
- Z2
-
-
-
- Ordinal
- x
- x
- Thunk
- (5)
-
-
-
- string
- xs:boolean
- xs:date
- xs:dateTime
- xs:duration
- x
- xs:int
- xs:long
- (6)
- x
- xs:time
-
-
- time
-
-
- Time part
- (7)
-
-
-
-
- (8)
- x
-
-
-
-
- Note
- Description
-
-
- (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)
-
- A duration 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.
-
-
-
- (8)
-
- The client should try to convert the string to a time value according to the format specified by the XML data type xs:time.
-
-
-
- x
- Use the canonical conversion method.
-
-
- Z2
- true = 1, false = 0.
-
-
- !=0
- Nonzero = true, Zero = false.
-
-
- RRGGBB
- A 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.
-
-
- RRGGBBAA
- A string of eight hexadecimal characters, the first two the red component of the color, the next two the green component, the following two the blue component and the last two the alpha channel.
-
-
- Date part
- Only the date part of the xs:dateTime value should be used.
-
-
- Time part
- Only the time part of the xs:dateTime value should be used.
-
-
- Ordinal
- Each enumeration value may in the implementation correspond to an ordinal number.
-
-
- Thunk
- The value is thunked down to lower precision in the canonical way.
-
-
- xs:boolean
- Conversion to a string should follow the rules specified for the XML datatype xs:boolean.
-
-
- xs:dateTime
- Conversion to a string should follow the rules specified for the XML datatype xs:dateTime.
-
-
- xs:duration
- Conversion to a string should follow the rules specified for the XML datatype xs:duration.
-
-
-
-
-
-
-
+ 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. +
+ ++ Depending on the reason for rejecting a control request, different XMPP errors can be returned, according to the description in the following table. The table also + lists recommended error type for each error. Error stanzas may also include paramError child elements to provide additional textual error information that + corresponds to a particular control parameter provided in the request. Any custom error message not related to control parameters is returned in a text + element. +
+Error Type | +Error Element | +Namespace | +Description | +
---|---|---|---|
cancel | +forbidden | +urn:ietf:params:xml:ns:xmpp-stanzas | +If the caller lacks privileges to perform the action. | +
cancel | +item-not-found | +urn:ietf:params:xml:ns:xmpp-stanzas | +If an item, parameter or data source could not be found. | +
modify | +bad-request | +urn:ietf:params:xml:ns:xmpp-stanzas | +If the request was malformed. Examples can include trying to set a parameter to a value outside the allowed range. | +
cancel | +feature-not-implemented | +urn:ietf:params:xml:ns:xmpp-stanzas | +If an action has not been implemented in the device. | +
wait | +conflict | +urn:ietf:params:xml:ns:xmpp-stanzas | +If an item was locked by another user or process and could not be accessed. The operation can be retried at a later point in time. | +
- 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. + The simplest way to read the current control states of a device, is to request the control form of the device. The control form should contain the current + values for all avilable control parameters. However, since current states might not be available at the time of the request, the states might be delivered + asynchronously, using messages defined in &xep0336;.
-+ Using this method has the advantage that a small actuator device does not need to implement other XEPs to support readout of current control states. If the device + contains all current states readily accessible, there's no need of asynchronous updates making readout simple and straightforward. +
++ A second option is to use &xep0323; to deliver current control states. Since this XEP contains mechanisms allowing for asynchronous readout of control parameter + states. This makes readout of such parameters simpler. However, there's a need to map values between the two XEPs. +
++ If a client wants to know the current status of control parameters using this method, it performs a readout of Momentary and Status values + from the device, and from the returned set of values take the current control parameter value according to the following rules, ordered by priority: +
+- 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. + 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.
+- 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. + 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.
-- 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. + To simplify mapping, a writable attribute can be used to inform the client if a field name corresponds to a control parameter or not. If the + attribute is available, it tells the client if it corresponds to a control parameter or not. If not available, no such deduction can be made.
-- 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 Internet of Things - Provisioning. -
-This document requires no interaction with &IANA;.
-- The protocol schema needs to be added to the list of XMPP protocol schemas. -
-
-
+
+
+ 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, as described above.
+
+
+ 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). An empty cell means conversion has no meaning and types are not compatible.
+
+
+
+ 325 \ 323
+ boolean
+ date
+ dateTime
+ duration
+ enum
+ int
+ long
+ numeric
+ string
+ time
+
+
+ boolean
+ x
+
+
+
+
+ !=0
+ !=0
+ !=0
+
+
+
+
+ color
+
+
+
+
+
+
+
+
+ RRGGBB or RRGGBBAA
+
+
+
+ date
+
+ x
+ Date part
+
+
+
+
+
+ (1)
+
+
+
+ dateTime
+
+ x
+ x
+
+
+
+
+
+ (2)
+
+
+
+ double
+ Z2
+
+
+
+
+ x
+ x
+ x
+ (3)
+
+
+
+ duration
+
+
+
+ x
+
+
+
+
+ (4)
+ x
+
+
+ int
+ Z2
+
+
+
+ Ordinal
+ x
+ Thunk
+ Thunk
+ (5)
+
+
+
+ long
+ Z2
+
+
+
+ Ordinal
+ x
+ x
+ Thunk
+ (5)
+
+
+
+ string
+ xs:boolean
+ xs:date
+ xs:dateTime
+ xs:duration
+ x
+ xs:int
+ xs:long
+ (6)
+ x
+ xs:time
+
+
+ time
+
+
+ Time part
+ (7)
+
+
+
+
+ (8)
+ x
+
+
+
+ The following table lists notes with details on how to do conversion, if in doubt.
+
+
+
+ Note
+ Description
+
+
+ (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)
+
+ A duration 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.
+
+
+
+ (8)
+
+ The client should try to convert the string to a time value according to the format specified by the XML data type xs:time.
+
+
+
+ x
+ Use the canonical conversion method.
+
+
+ Z2
+ true = 1, false = 0.
+
+
+ !=0
+ Nonzero = true, Zero = false.
+
+
+ RRGGBB
+ A 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.
+
+
+ RRGGBBAA
+ A string of eight hexadecimal characters, the first two the red component of the color, the next two the green component, the following two the blue component and the last two the alpha channel.
+
+
+ Date part
+ Only the date part of the xs:dateTime value should be used.
+
+
+ Time part
+ Only the time part of the xs:dateTime value should be used.
+
+
+ Ordinal
+ Each enumeration value may in the implementation correspond to an ordinal number.
+
+
+ Thunk
+ The value is thunked down to lower precision in the canonical way.
+
+
+ xs:boolean
+ Conversion to a string should follow the rules specified for the XML datatype xs:boolean.
+
+
+ xs:dateTime
+ Conversion to a string should follow the rules specified for the XML datatype xs:dateTime.
+
+
+ xs:duration
+ Conversion 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.
+
+
+
+
+ When representing control parameters as momentary field values, it is important to note the similarities and differences between XEP-0323 (Sensor Data) and XEP-0325 (this document):
+
+
+ The enum field value data type is not available in XEP-0325 (this document). Instead enumeration valued parameters are represented as string control
+ parameters, while the control form explicitly lists available options for the parameter. Options are not available in XEP-0323, since it would not be practical to list all options
+ every time the corresponding parameter was read out. Instead, the enum element contains a data type attribute, that can be used to identify the type of the enumeration.
+
+
+ The numeric field value data type is not available in XEP-0325 (this document). The reason is that a controller is not assumed to understand unit conversion. Any
+ floating-point valued control parameters are represented by double control parameters, which lack a unit attribute. They are assumed to have the same unit as
+ the corresponding numeric field value. On the other hand, floating point valued control parameters without units, are reported using the numeric
+ field element, but leaving the unit blank.
+
+
+ Control pameters of type color have no corresponding field value data type. The color value must be represented in another way, and is implementation specific.
+ Possibilities include representing the color as a string, using a specific pattern (for instance RRGGBBAA), or report it using multiple fields, one for each component for instance.
+
+
+ The boolean, date, dateTime, duration, int, long, string
+ and time field value data types correspond to control parameters having the same types and same element names.
+
+
+
+
+
+ A node defined in a concentrator, as defined by Internet of Things - Concentrators, 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 Internet of Things - Concentrators,
+ 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 available in a device can be controlled using only one control parameter. If a device only publishes such control parameters, the order
+ of control parameters 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.
+
+
+ Note: If used, the server must not include a parameter in more than one parameter group at a time. The form may contain multiple group, but each
+ parameter must only have at most one parameterGroup element.
+
+
+ The following example illustrates the use of the parameterGroup element to group parameters together.
+
+
+
+
+
+
+
+
+ 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-IoT-Interoperability.html,
+ which defines a set of interoperable interfaces and their abilities.
+
+
+
+
+ Nodes behind a concentrator, as defined in Internet of Things - Concentrators, 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-0324 &xep0324;,
+ 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 Internet of Things - Provisioning.
+
+
+
+
+ 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
+ Internet of Things - Concentrators.
+ 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
+ Internet of Things - Concentrators.
+
+
+ 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.
+
+
+
+ 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 Internet of Things - Provisioning. +
+This document requires no interaction with &IANA;.
++ The protocol schema needs to be added to the list of XMPP protocol schemas. +
+
+
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'
+ targetNamespace='urn:xmpp:iot:control'
+ xmlns='urn:xmpp:iot:control'
+ xmlns:sn='urn:xmpp:iot:sensordata'
+ xmlns:xd="jabber:x:data"
+ xmlns:xdv="http://jabber.org/protocol/xdata-validate"
+ xmlns:xdl="http://jabber.org/protocol/xdata-layout"
+ elementFormDefault='qualified'>
-
-
-
-
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
-
-
+
+
+
+
+
+
+
-
-
-
+
+
+
+
+
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
]]>
-
- - For more information, please see the following resources: -
-- The Sensor Network section of the XMPP Wiki contains further information about the - use of the sensor network XEPs, links to implementations, discussions, etc. -
-- The XEP's and related projects are also available on github, thanks to Joachim Lindborg. -
-- A presentation giving an overview of all extensions related to Internet of Things can be found here: - http://prezi.com/esosntqhewhs/iot-xmpp/. -
-Thanks to Joachim Lindborg and Tina Beckman for all valuable feedback.
-+ For more information, please see the following resources: +
++ The Sensor Network section of the XMPP Wiki contains further information about the + use of the sensor network XEPs, links to implementations, discussions, etc. +
++ The XEP's and related projects are also available on github, thanks to Joachim Lindborg. +
++ A presentation giving an overview of all extensions related to Internet of Things can be found here: + http://prezi.com/esosntqhewhs/iot-xmpp/. +
+Thanks to Joachim Lindborg and Tina Beckman for all valuable feedback.
+Updated contact information.
-Updated example JIDs to example.org
-Updated contact information.
+Updated example JIDs to example.org
+Namespace in dynamic form examples has been changed to urn:xmpp:xdata:dynamic.
+Namespace in dynamic form examples has been changed to urn:xmpp:xdata:dynamic.
Added the following node query events: title, status, beginSection and endSection.
Updated the schema to more strictly validate references to x-data forms.
Updated attribute names so queries and responses are consistent.
@@ -62,1797 +62,1797 @@Initial published version approved by the XMPP Council.
-Initial published version approved by the XMPP Council.
+First draft.
-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: +
++ 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: +
+ +XEP | +Description | +
---|---|
xep-0000-IoT-BatteryPoweredSensors | +Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network. | +
xep-0000-IoT-Discovery | +Defines 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-IoT-Events | +Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured. | +
xep-0000-IoT-Interoperability | +Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices. | +
xep-0000-IoT-Multicast | +Defines how sensor data can be multicast in efficient ways. | +
xep-0000-IoT-PubSub | +Defines how efficient publication of sensor data can be made in sensor networks. | +
xep-0000-IoT-Chat | +Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture. | +
XEP-0322 | ++ 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-0323 | ++ 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. + | +
XEP-0324 | +Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented. | +
XEP-0325 | +Defines how to control actuators and other devices in Internet of Things. | +
XEP-0326 | +This specification. Defines how to handle architectures containing concentrators or servers handling multiple sensors. | +
XEP-0331 | +Defines extensions for how color parameters can be handled, based on &xep0004; | +
XEP-0336 | +Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;. | +
+ 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. +
+- 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). + 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 syndication of this information.
- 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 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.
- 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: + Even though this document defines tree structures of data, it is not however based on XEP-0060. There are multiple reasons for this:
- 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: -
- -XEP | -Description | -
---|---|
xep-0000-IoT-BatteryPoweredSensors | -Defines how to handle the peculiars related to battery powered devices, and other devices intermittently available on the network. | -
xep-0000-IoT-Discovery | -Defines 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-IoT-Events | -Defines how sensors send events, how event subscription, hysteresis levels, etc., are configured. | -
xep-0000-IoT-Interoperability | -Defines guidelines for how to achieve interoperability in sensor networks, publishing interoperability interfaces for different types of devices. | -
xep-0000-IoT-Multicast | -Defines how sensor data can be multicast in efficient ways. | -
xep-0000-IoT-PubSub | -Defines how efficient publication of sensor data can be made in sensor networks. | -
xep-0000-IoT-Chat | -Defines how human-to-machine interfaces should be constructed using chat messages to be user friendly, automatable and consistent with other IoT extensions and possible underlying architecture. | -
XEP-0322 | -- 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-0323 | -- 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. - | -
XEP-0324 | -Defines how provisioning, the management of access privileges, etc., can be efficiently and easily implemented. | -
XEP-0325 | -Defines how to control actuators and other devices in Internet of Things. | -
XEP-0326 | -This specification. Defines how to handle architectures containing concentrators or servers handling multiple sensors. | -
XEP-0331 | -Defines extensions for how color parameters can be handled, based on &xep0004; | -
XEP-0336 | -Defines extensions for how dynamic forms can be created, based on &xep0004;, &xep0122;, &xep0137; and &xep0141;. | -
- 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 syndication 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: -
-- XEP-0248 defines the concept of node collections and syndication of information from nodes in these collections. But XEP-0248 is not used in this specification. - There are multiple reasons: -
-- &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: -
-The following table lists common terms and corresponding descriptions.
-- 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. + XEP-0248 defines the concept of node collections and syndication of information from nodes in these collections. But XEP-0248 is not used in this specification. + There are multiple reasons:
-- 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. -
-+ &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: +
+The following table lists common terms and corresponding descriptions.
++ 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. +
+- A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows: -
-+ A concentrator without databases, but still contain a rich interface for handling masses of nodes may present itself as follows: +
+- A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems: -
-+ A smaller gateway on the other hand, may have skipped the implementation of the batch commands that are used for larger systems: +
+- But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands: -
-+ But a small PLC, possibly with a fixed set of nodes, might have support for an even more reduced set of commands: +
+- 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. -
-+ 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. -
-+ 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: -
-+ 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: -
-+ 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. -
-+ 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 (nodeAdded, - nodeUpdated, nodeStatusChanged, nodeRemoved, nodeMovedUp and nodeMovedDown), 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 attributes parameters and messages can also be used to specify - if node parameters and node messages respectively should be available in event messages. The default value for the these later attributes is false, implying - that normal events do not include node parameter and node message information. -
-- The following example shows how a client can subscribe to a set of events only: -
-+ The subscribe command has a set of optional attributes, one for each event type available, and with the same names (nodeAdded, + nodeUpdated, nodeStatusChanged, nodeRemoved, nodeMovedUp and nodeMovedDown), 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 attributes parameters and messages can also be used to specify + if node parameters and node messages respectively should be available in event messages. The default value for the these later attributes is false, implying + that normal events do not include node parameter and node message information. +
++ 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: -
-+ 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): -
-+ 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. -
-+ 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. +
+- 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. -
-- If during a subscription request the concentrator is not able to fulfill the request of retrieving previous events using the getEventsSince attribute, - perhaps the attribute stretches too far back, or includes too many records, the concentrator can return an error message using a response code of NotImplemented. - In this case, the subscription must not be made. -
-- When receiving such an error from the concentrator, the client must make a decision if it should download the data source again, or keep the data source as is, and - subscribing again without the getEventsSince attribute. -
-+ 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. +
++ If during a subscription request the concentrator is not able to fulfill the request of retrieving previous events using the getEventsSince attribute, + perhaps the attribute stretches too far back, or includes too many records, the concentrator can return an error message using a response code of NotImplemented. + In this case, the subscription must not be made. +
++ When receiving such an error from the concentrator, the client must make a decision if it should download the data source again, or keep the data source as is, and + subscribing again without the getEventsSince attribute. +
+- This command permits the client to check the existence of a node in the concentrator. -
-+ This command permits the client to check the existence of a node in the concentrator. +
+- If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead: -
-+ If the client wants to check the existence of multiple nodes on the concentrator, it can use this batch command instead: +
+- 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. -
-+ 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 command lets the client get information from multiple nodes at once. -
-+ For more information, see Node Information. +
++ This command 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 command returns basic information about a node in the concentrator, as well as node parameters. +
+- For more information, see Node Information. -
-- This command lets the client get information from multiple nodes at once, including node parameters. -
-+ For more information, see Node Information. +
++ This command 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. -
-+ 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. -
-+ 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. -
-+ This command assumes node types exist in a class hierarchy, and allows the caller to retrieve nodes with similar inheritance. +
+- 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. -
-+ 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. +
+- 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. -
-+ 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. +
+- Note: It is assumed the client already knows the node type of the node, so the response must not contain the type of the node, only - its base classes and any implemented interfaces. -
-- This command returns the root node of a data source (in case the source is a tree-shaped data source) or the nodes of a data source (in case the - source is flat). -
-+ Note: It is assumed the client already knows the node type of the node, so the response must not contain the type of the node, only + its base classes and any implemented interfaces. +
++ This command returns the root node of a data source (in case the source is a tree-shaped data source) or the nodes of a data source (in case the + source is flat). +
+- This command 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 command 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 command returns the child nodes of a node in a data source. -
-+ This command returns the child nodes of a node in a data source. +
+- This command returns the child nodes of a node in a data source, and also returns the parameters for the corresponding nodes. -
-+ This command 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. -
-+ This command returns a list of available indices in a data source. Indices can be used for efficient node look-up. +
+- 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. +
+- 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 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. +
+- 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 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. -
-+ This command can be used to get a list of available index values, given a data source and an index. +
+- 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: -
-+ 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 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 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 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 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. -
-+ 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. +
+- The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal: -
-XEP | -Description | -
---|---|
XEP-0004 | -Describes how basic forms are handled. | -
XEP-0122 | -Makes it possible to add certain client validation rules to form parameters. | -
XEP-0137 | -Makes it possible to publish a file upload parameter. | -
XEP-0141 | -Makes it possible to layout parameters into pages and sections. | -
XEP-0331 | -Defines extensions for how color parameters can be handled. | -
XEP-0336 | -Makes 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-0336. - 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 anymore and must be ignored by the server. -
-+ The following table lists the different XEP's the client should implement to be able to support parameter forms according to this proposal: +
+XEP | +Description | +
---|---|
XEP-0004 | +Describes how basic forms are handled. | +
XEP-0122 | +Makes it possible to add certain client validation rules to form parameters. | +
XEP-0137 | +Makes it possible to publish a file upload parameter. | +
XEP-0141 | +Makes it possible to layout parameters into pages and sections. | +
XEP-0331 | +Defines extensions for how color parameters can be handled. | +
XEP-0336 | +Makes 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-0336. + 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 anymore and must be ignored by the server. +
+- 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. -
-+ 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. +
+
- 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-0336
-
- 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-0336. Clients using this command MUST - support the extensions defined in XEP-0336. -
-
+ 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-0336
+
+ 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-0336. Clients using this command MUST + support the extensions defined in XEP-0336. +
+- 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. -
-+ 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. +
++ 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-0336. 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. +
++ 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-0336 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: +
+State | +Description | +
---|---|
None | +Nothing has been reported on the node. | +
Information | +There are informative events reported on the node. | +
WarningSigned | +There are warnings reported on the node. But these warnings have been viewed by an operator. | +
WarningUnsigned | +There are new or unreviewed warnings reported on the node. | +
ErrorSigned | +There are errors reported on the node. But these errors have been viewed by an operator. | +
ErrorUnsigned | +There 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: +
++ The messages attribute can be combined with the parameters attribute to provide both node parameters and + messages in the response. +
+- 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-0336. 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. -
-+ 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: +
+- 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-0336 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: -
-State | -Description | -
---|---|
None | -Nothing has been reported on the node. | -
Information | -There are informative events reported on the node. | -
WarningSigned | -There are warnings reported on the node. But these warnings have been viewed by an operator. | -
WarningUnsigned | -There are new or unreviewed warnings reported on the node. | -
ErrorSigned | -There are errors reported on the node. But these errors have been viewed by an operator. | -
ErrorUnsigned | -There 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: -
-+ 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: +
+- The messages attribute can be combined with the parameters attribute to provide both node parameters and - messages in the response. -
-- 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: -
-- After editing the form, the client uses the createNewNode command to create the new node using the parameters provided in the form. -
-+ After editing the form, the client uses the createNewNode command to create the new node using the parameters provided in the form. +
+- 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. -
-+ 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. +
+- 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-0336 for more information. -
-- To destroy (remove) a node from the concentrator, the destroyNode command is sent, as is shown in the following example: -
-+ 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-0336 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: -
-+ 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: -
-+ 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 three types of commands available: Simple, Parameterized and Query. 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. Query commands also require a set of parameters to be executed, but return a response after (or during) execution - in an asynchronous fashion. Queries can also be aborted during execution. A Query with an empty parameter set is considered to be a simple query, not requiring a - parameter dialog to be shown. -
-- 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: -
-+ There are three types of commands available: Simple, Parameterized and Query. 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. Query commands also require a set of parameters to be executed, but return a response after (or during) execution + in an asynchronous fashion. Queries can also be aborted during execution. A Query with an empty parameter set is considered to be a simple query, not requiring a + parameter dialog to be shown. +
++ 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 or a query 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: -
-+ To execute a parameterized command or a query 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: +
+- 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: -
-+ 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: +
+- 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-0336 for more information. -
-+ 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-0336 for more information. +
+- Executing a Node Query also requires the client to get a set of parameters for the query. This is done in the same way as for parametrized commands, - as is shown in the following example: -
-+ Executing a Node Query also requires the client to get a set of parameters for the query. This is done in the same way as for parametrized commands, + as is shown in the following example: +
+- Executing the query is then done by sending the executeNodeQuery command to the concentrator, but including the edited form parameters, - as is shown in the following example: -
-+ Executing the query is then done by sending the executeNodeQuery command to the concentrator, but including the edited form parameters, + as is shown in the following example: +
+- After the successful execution of a query command, a sequence of query events will follow. These events will include a queryId - attribute to identify to which query the corresponding events correspond. See section about Query Events - for more information about this. -
-- Note: Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed. - However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before - executing the command. -
-- If an error occurs during the reception of a query or if the server rejects the execution of a query, 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-0336 for more information. -
-+ After the successful execution of a query command, a sequence of query events will follow. These events will include a queryId + attribute to identify to which query the corresponding events correspond. See section about Query Events + for more information about this. +
++ Note: Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed. + However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before + executing the command. +
++ If an error occurs during the reception of a query or if the server rejects the execution of a query, 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-0336 for more information. +
++ One a query has been accepted and started running, the client can abort it using the abortNodeQuery command, as is shown in the + following example. +
++ Note: The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of + query events and the reception of them by a client. A client may thinkt a query is still active when asking + to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this + when receiving NotFound responses from a concentrator, that the query might already have been finished. +
++ 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: +
++ 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: +
+- One a query has been accepted and started running, the client can abort it using the abortNodeQuery command, as is shown in the - following example. -
-- Note: The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of - query events and the reception of them by a client. A client may thinkt a query is still active when asking - to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this - when receiving NotFound responses from a concentrator, that the query might already have been finished. -
-- 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: -
-- 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: -
-- 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: -
-+ 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: +
+- 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-0336 for more information. -
-+ 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-0336 for more information. +
+- 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. Note that - individual error messages can be provided as error attribute messages for each node that fails in the corresponding result - element. -
-+ 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. Note that + individual error messages can be provided as error attribute messages for each node that fails in the corresponding result + element. +
+- Executing a Node Query on multiple nodes also requires the client to get a set of parameters for the query common to all nodes. - This is done in the same way as for parametrized commands, as is shown in the following example: -
-+ Executing a Node Query on multiple nodes also requires the client to get a set of parameters for the query common to all nodes. + This is done in the same way as for parametrized commands, as is shown in the following example: +
+- Executing the query is then done by sending the executeCommonNodeQuery command to the concentrator, but including the edited form parameters, - as is shown in the following example: -
-+ Executing the query is then done by sending the executeCommonNodeQuery command to the concentrator, but including the edited form parameters, + as is shown in the following example: +
+- After the successful execution of a query command, a sequence of query events will follow. These events will include a queryId - attribute to identify to which query the corresponding events correspond. They will also include node reference attributes so the receptor can - distinguish information from different nodes in the query. See section about Query Events - for more information about this. -
-- Note: Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed. - However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before - executing the command. -
-- If an error occurs during the execution of a common query or if the server rejects the execution of a common query, 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-0336 for more information. -
-+ After the successful execution of a query command, a sequence of query events will follow. These events will include a queryId + attribute to identify to which query the corresponding events correspond. They will also include node reference attributes so the receptor can + distinguish information from different nodes in the query. See section about Query Events + for more information about this. +
++ Note: Queries with no visible parameters in the command parameter form need not display a parameter form to the user before being executed. + However, if a confirmation question is defined for the command, such a confirmation question should always be presented to the user (if possible) before + executing the command. +
++ If an error occurs during the execution of a common query or if the server rejects the execution of a common query, 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-0336 for more information. +
+- When executing a query on multiple nodes, it might happen that the query is rejected 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 query on multiple nodes that fail on some nodes but are executed on others. Note that - individual error messages can be provided as error attribute messages for each node that fails in the corresponding result - element. -
-+ When executing a query on multiple nodes, it might happen that the query is rejected 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 query on multiple nodes that fail on some nodes but are executed on others. Note that + individual error messages can be provided as error attribute messages for each node that fails in the corresponding result + element. +
+- To abort a query common to a set of nodes you use the abortCommonNodeQuery command, as is shown in the following example: -
-+ To abort a query common to a set of nodes you use the abortCommonNodeQuery command, as is shown in the following example: +
+- Note: The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of - query events and the reception of them by a client. A client may thinkt a query is still active when asking - to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this - when receiving NotFound responses from a concentrator, that the query might already have been finished. In the case of - aborting queries on multiple nodes, servers must ignore nodes where the query has already finished executing. -
-+ Note: The execution of a query is an asynchronous process, with a small delay between the compilation and transmission of + query events and the reception of them by a client. A client may thinkt a query is still active when asking + to abort it, when the query might actually have been finished and removed on the query side. Therefore, clients should be aware of this + when receiving NotFound responses from a concentrator, that the query might already have been finished. In the case of + aborting queries on multiple nodes, servers must ignore nodes where the query has already finished executing. +
++ Query events are sent as a response to executing queries on nodes. They are reported asynchronously from the concentrator to the client executing the query. Each + event is wrapped in a queryProgress element within a message sent from the concentrator to the client. Each such queryProgress + element can include any number of query events, and the client must process them in the order they appear in the message. +
++ Each queryProgress element contains a queryId attribute identifying the query to which the events correspond. They also contain + sourceId, nodeId and an optional cacheType to identify from which node in a concentrator the events originated. +
++ Note: A queryProgress element can only contain events from a single query executed on a single node. If a query is executed on + multiple nodes, events resulting from different nodes will be sent in different messages. +
++ The following subsections describe each query event in turn. +
+- Query events are sent as a response to executing queries on nodes. They are reported asynchronously from the concentrator to the client executing the query. Each - event is wrapped in a queryProgress element within a message sent from the concentrator to the client. Each such queryProgress - element can include any number of query events, and the client must process them in the order they appear in the message. + This event is sent when the query is started on a node. It is sent using a queryStarted event element. This element does not take any + attributes.
+- Each queryProgress element contains a queryId attribute identifying the query to which the events correspond. They also contain - sourceId, nodeId and an optional cacheType to identify from which node in a concentrator the events originated. + This event is sent when the query is done on a node. It is sent using a queryDone event element. This element does not take any + attributes.
+- Note: A queryProgress element can only contain events from a single query executed on a single node. If a query is executed on - multiple nodes, events resulting from different nodes will be sent in different messages. + This event is sent when the query has been aborted on a node. It is sent using a queryAborted event element. This element does not take any + attributes.
+- The following subsections describe each query event in turn. + A query result can consist of zero or more data tables. Each data table consists of a set of columns and records containing value items for the these + columns. A new table is identified by a query event named newTable. a newTable event contains a sequence of + column events each identifying a column in the table.
-- This event is sent when the query is started on a node. It is sent using a queryStarted event element. This element does not take any - attributes. -
-- This event is sent when the query is done on a node. It is sent using a queryDone event element. This element does not take any - attributes. -
-- This event is sent when the query has been aborted on a node. It is sent using a queryAborted event element. This element does not take any - attributes. -
-- A query result can consist of zero or more data tables. Each data table consists of a set of columns and records containing value items for the these - columns. A new table is identified by a query event named newTable. a newTable event contains a sequence of - column events each identifying a column in the table. -
-- For more information about column definitions, see Table Column definitions in query results. + For more information about column definitions, see Table Column definitions in query results.
-- A set of records in an open table is reported using the newRecords query event. + A set of records in an open table is reported using the newRecords query event.
- For more information about records, see Record Item definitions in query results. + For more information about records, see Record Item definitions in query results.
-- This event is sent when the query is done with a table. It is sent using a tableDone event element. The query must not send any more records - to a table that has been closed using this query event. + This event is sent when the query is done with a table. It is sent using a tableDone event element. The query must not send any more records + to a table that has been closed using this query event.
- Some queries may want to return other types of data than tables, like images, graphs, etc. These may be combined with table information or not. - A query returns such an object using the newObject query event. Each object is MIME encoded, and the MIME Type is sent in the - contentType attribute. The object itself is Base-64 encoded. + Some queries may want to return other types of data than tables, like images, graphs, etc. These may be combined with table information or not. + A query returns such an object using the newObject query event. Each object is MIME encoded, and the MIME Type is sent in the + contentType attribute. The object itself is Base-64 encoded.
- During the processing of a query, the query might want to report a message of some kind. This is done using the queryMessage - query event. + During the processing of a query, the query might want to report a message of some kind. This is done using the queryMessage + query event.
- For more information about query messages, see Message definitions in query results. + For more information about query messages, see Message definitions in query results.
-- Enables the executing process of the query to set a custom title for the result. Note that the result only has one title. + Enables the executing process of the query to set a custom title for the result. Note that the result only has one title.
- Permits the executing process to report the current status. This can change a lot during execution and values should not be persisted, like - query messages. Instead, they can be displayed in a status bar, just to give the end-user feedback of the status of a long-running query. + Permits the executing process to report the current status. This can change a lot during execution and values should not be persisted, like + query messages. Instead, they can be displayed in a status bar, just to give the end-user feedback of the status of a long-running query.
- Starts a new section in the query result. In large query results, sections can be used to format the result using an intuitive disposition - in a visually appealing way. Nested sections should be interepreted as sub-sections. Tables and objects started or reported within a section - belong in that section, and should be listed sequentially in the order they are reported to the client. + Starts a new section in the query result. In large query results, sections can be used to format the result using an intuitive disposition + in a visually appealing way. Nested sections should be interepreted as sub-sections. Tables and objects started or reported within a section + belong in that section, and should be listed sequentially in the order they are reported to the client.
- Note that the use of sections in a query result is optional. Tables and objects received outside the scope of sections should be placed - in a default section by the client. + Note that the use of sections in a query result is optional. Tables and objects received outside the scope of sections should be placed + in a default section by the client.
-- Closes the current section or sub-section. Tables inside closed sections can still be open and receive fields. Tables are closed using the - tableDone query event. + Closes the current section or sub-section. Tables inside closed sections can still be open and receive fields. Tables are closed using the + tableDone query event.
-
+
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: + 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. + 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.
- If a node is added to a parent where order of nodes is important, the attributes afterNodeId and also optionally - afterNodeCacheType used to identify the node after which the new node should be inserted. + If a node is added to a parent where order of nodes is important, the attributes afterNodeId and also optionally + afterNodeCacheType used to identify the node after which the new node should be inserted.
- 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: + 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. + 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 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: + 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. + 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. + 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.
- 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: + 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. + 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: + 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. + 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: + 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: + 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:
- 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 &xep0323;. The only difference is that the - read-out is started with the startDatabaseReadout command instead of the req - command of the sensor data namespace. + 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 &xep0323;. 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 diagram shows the flow of messages when requesting a readout from a database:
- +
- The following example shows a startDatabaseReadout request: + The following example shows a startDatabaseReadout request:
- The following example shows a response when the concentrator rejects the read-out request: + 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: + The error might also be a result of invalid input parameters being sent:
- A client can cancel a database read-out using the cancel read-out command, - as described in Internet of Things - Sensor Data. + A client can cancel a database read-out using the cancel read-out command, + as described in Internet of Things - Sensor Data.
If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:concentrators" 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. -
-If an entity supports the protocol specified herein, it MUST advertise that fact by returning a feature of "urn:xmpp:iot:concentrators" in response to &xep0030; information requests.
+- Several commands return basic node information. The following table lists possible fields with corresponding descriptions. + 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.
-Attribute | -Use | -Default | -Description | +Attribute | +Use | +Default | +Description |
---|---|---|---|---|---|---|---|
nodeId | -required | -- | The ID of the node in the data source. | +nodeId | +required | ++ | The ID of the node in the data source. |
displayName | -optional | -- | If provided, a string presentable to users. If localization is supported and a correct language attribute was provided, this string will be localized. | +displayName | +optional | ++ | If provided, a string presentable to users. If localization is supported and a correct language attribute was provided, this string will be localized. |
nodeType | -optional | -- | A string representing the type of the node. | +nodeType | +optional | ++ | A string representing the type of the node. |
localId | -optional | -- | If provided, an ID for the node, but unique locally between siblings. | +localId | +optional | ++ | If provided, an ID for the node, but unique locally between siblings. |
logId | -optional | -- | If provided, an ID for the node, as it would appear or be used in system logs. | +logId | +optional | ++ | If provided, an ID for the node, as it would appear or be used in system logs. |
cacheType | -optional | -- | 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 + | cacheType | +optional | ++ | 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. *** |
state | -required | -- | Current overall state of the node. | +state | +required | ++ | Current overall state of the node. |
hasChildren | -required | -- | If the node has children or not. | +hasChildren | +required | ++ | If the node has children or not. |
childrenOrdered | -optional | -false | -If 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 + | childrenOrdered | +optional | +false | +If 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. - | +
isReadable | -optional | -false | -If the node can be read. (*) | +isReadable | +optional | +false | +If the node can be read. (*) |
isControllable | -optional | -false | -If the node can be controlled. (**) | +isControllable | +optional | +false | +If the node can be controlled. (**) |
hasCommands | -optional | -false | -If the node has registered commands or not. | +hasCommands | +optional | +false | +If the node has registered commands or not. |
parentId | -optional | -- | The node ID of the parent node. If not available, the node is considered a root node. | +parentId | +optional | ++ | The node ID of the parent node. If not available, the node is considered a root node. |
parentCacheType | -optional | -- | The Cache Type of the parent node. | +parentCacheType | +optional | ++ | The Cache Type of the parent node. |
lastChanged | -optional | -- | When the node was last changed. Can be used by clients to synchronize content between the concentrator and itself. | +lastChanged | +optional | ++ | When the node was last changed. Can be used by clients to synchronize content between the concentrator and itself. |
+
(*) See Internet of Things - Sensor Data for more information about how to read nodes. -
-+
+(**) See Internet of Things - Control for more information about how to control 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 Name | -Parameter Value | +Element Name | +Parameter Value |
---|---|---|---|
boolean | -Boolean values. Can be true or false. | +boolean | +Boolean values. Can be true or false. |
color | -Color values. They are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component. | +color | +Color values. They are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component. |
dateTime | -Date and time value, with possible time zone information. | +dateTime | +Date and time value, with possible time zone information. |
double | -double precision floating point value. | +double | +double precision floating point value. |
duration | -A time duration value. | +duration | +A time duration value. |
int | -A 32-bit integer value. | +int | +A 32-bit integer value. |
long | -A 64-bit integer value. | +long | +A 64-bit integer value. |
string | -A string value. | +string | +A string value. |
time | -A time value using a 24-hour clock. | +time | +A 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 Code | -Description | +Response Code | +Description |
---|---|---|---|
OK | -Request is OK and accepted. | +OK | +Request is OK and accepted. |
NotFound | -Corresponding object, node, etc., was not found. | +NotFound | +Corresponding object, node, etc., was not found. |
InsufficientPrivileges | -Insufficient privileges to perform the corresponding action or execute the corresponding command. Make sure to provide sufficient credentials in the call + | InsufficientPrivileges | +Insufficient 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. |
Locked | -The object/node is locked, and operation could not be performed or completed. | +Locked | +The object/node is locked, and operation could not be performed or completed. |
NotImplemented | -Command is not implemented. | +NotImplemented | +Command is not implemented. |
FormError | -The form send to the concentrator contains errors. The response contains detailed error information. | +FormError | +The form send to the concentrator contains errors. The response contains detailed error information. |
OtherError | -Another error occurred. | +OtherError | +Another 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: -
-+ 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. -
-Attribute | -Use | -Description | +Attribute | +Use | +Description |
---|---|---|---|---|---|
command | -required | -ID of the command. Used to identify the command. | +command | +required | +ID of the command. Used to identify the command. |
name | -required | -A string that can be presented to an end-user. Should be localized if the request contained a language preference. | +name | +required | +A string that can be presented to an end-user. Should be localized if the request contained a language preference. |
type | -required | -If the command is 'Simple' or 'Parameterized'. | +type | +required | +If the command is 'Simple' or 'Parameterized'. |
sortCategory | -optional | -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 + | sortCategory | +optional | +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. |
sortKey | -optional | -- 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. - | +sortKey | +optional | ++ 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. + |
confirmationString | -optional | -Should presented to clients (if available) before letting an end-user execute the command. A delete command might have a confirmationString saying + | confirmationString | +optional | +Should 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. |
failureString | -optional | -- 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. - | +failureString | +optional | ++ 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. + |
successString | -optional | -- 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.'. - | +successString | +optional | ++ 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: -
-State | -Description | +State | +Description |
---|---|---|---|
None | -The node has nothing special to report. | +None | +The node has nothing special to report. |
Information | -The node has informative events reported on it. | +Information | +The node has informative events reported on it. |
WarningSigned | -The node has warnings reported on it. These warnings have been viewed by an operator. | +WarningSigned | +The node has warnings reported on it. These warnings have been viewed by an operator. |
WarningUnsigned | -The node has warnings reported on it that have not been viewed by anybody. | +WarningUnsigned | +The node has warnings reported on it that have not been viewed by anybody. |
ErrorSigned | -The node has errors reported on it. These errors have been viewed by an operator. | +ErrorSigned | +The node has errors reported on it. These errors have been viewed by an operator. |
ErrorUnsigned | -The node has errors reported on it that have not been viewed by anybody. | +ErrorUnsigned | +The 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 Source | -Description | +Data Source | +Description |
---|---|---|---|
MeteringTopology | -Data Source containing the topology of metering devices, including sensors, actuators, meter, infrastructure components, etc. | +MeteringTopology | +Data Source containing the topology of metering devices, including sensors, actuators, meter, infrastructure components, etc. |
+
More information can be found in the
+
+Table columns in query results can have the following attributes: -
-Attribute | -Use | -Description | +Attribute | +Use | +Description |
---|---|---|---|---|---|
columnId | -Required | -ID of column | +columnId | +Required | +ID of column |
header | -Optional | -If provided, a localized name to be displayed instead of the column ID. | +header | +Optional | +If provided, a localized name to be displayed instead of the column ID. |
alignment | -Optional | -Alignment of contents in the column. If provided, the client does not need to guess alignment from the type of data reported. | +alignment | +Optional | +Alignment of contents in the column. If provided, the client does not need to guess alignment from the type of data reported. |
nrDecimals | -Optional | -If floating point data is presented in the column and a fixed number of decimals is desired, this attribute is used to fix the number of decimals used. | +nrDecimals | +Optional | +If floating point data is presented in the column and a fixed number of decimals is desired, this attribute is used to fix the number of decimals used. |
dataSourceId | -Optional | -If contents of columns contains references to nodes in a data source, this attribute defines the data source ID. | +dataSourceId | +Optional | +If contents of columns contains references to nodes in a data source, this attribute defines the data source ID. |
cacheTypeName | -Optional | -If contents of columns contains references to nodes in a data source, this attribute defines the cache type. | +cacheTypeName | +Optional | +If contents of columns contains references to nodes in a data source, this attribute defines the cache type. |
fgColor | -Optional | -If presentation of this column should be done using a specific foreground color. | +fgColor | +Optional | +If presentation of this column should be done using a specific foreground color. |
bgColor | -Optional | -If presentation of this column should be done using a specific background color. | +bgColor | +Optional | +If presentation of this column should be done using a specific background color. |
+
Records contain arrays of items, each item correspond to a specific column with the same ordinal index. Each item is specified together with its type. This, so receptors can integrate the result with type information if necessary. The following different type elements are available: -
-Element | -Contents | +Element | +Contents |
---|---|---|---|
boolean | -A boolean value, corresponding to the xs:boolean data type. | +boolean | +A boolean value, corresponding to the xs:boolean data type. |
color | -A color value. These are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component. | +color | +A color value. These are strings containing 6 case-insensitive hexadecimal digits of the form RRGGBB, where RR=Red component, GG=Green component, BB=Blue component. |
dateTime | -A Date & Time value, corresponding to the xs:dateTime data type. | +dateTime | +A Date & Time value, corresponding to the xs:dateTime data type. |
double | -A floating-point value, corresponding to the xs:double data type. | +double | +A floating-point value, corresponding to the xs:double data type. |
duration | -A duration value, corresponding to the xs:duration data type. | +duration | +A duration value, corresponding to the xs:duration data type. |
int | -A 32-bit integer value, corresponding to the xs:int data type. | +int | +A 32-bit integer value, corresponding to the xs:int data type. |
long | -A 64-bit value, corresponding to the xs:long data type. | +long | +A 64-bit value, corresponding to the xs:long data type. |
string | -A string value, corresponding to the xs:string data type. | +string | +A string value, corresponding to the xs:string data type. |
time | -A time value, corresponding to the xs:time data type. | +time | +A time value, corresponding to the xs:time data type. |
base64 | -A base-64 encoded object. The object is MIME encoded, and the attribute contentType contains the MIME Type which includes information on how to decode the value. | +base64 | +A base-64 encoded object. The object is MIME encoded, and the attribute contentType contains the MIME Type which includes information on how to decode the value. |
void | -Contains no information. This represents a NULL value. | +void | +Contains no information. This represents a NULL value. |
+
Messages in query results contain apart from a message text, also contain some classification on what the message is using two attributes: The type attribute gives a rough idea about the type of message and level the importance of the message. -
-Type | -Description | +Type | +Description |
---|---|---|---|
Information | -Information message | +Information | +Information message |
Warning | -Message contains a warning. The situation could turn into an error if consideration or action is not taken. | +Warning | +Message contains a warning. The situation could turn into an error if consideration or action is not taken. |
Error | -Message contains an error. The error message describes the error, and the error has been handled correctly by the device performing the query. | +Error | +Message contains an error. The error message describes the error, and the error has been handled correctly by the device performing the query. |
Exception | -Message contains an exception message. An unforseen and perhaps an unhandled event has occurred during the execution of the query. | +Exception | +Message contains an exception message. An unforseen and perhaps an unhandled event has occurred during the execution of the query. |
Level | -Description | +Level | +Description |
---|---|---|---|
Minor | -Minor event. Message describes common tasks. | +Minor | +Minor event. Message describes common tasks. |
Medium | -Medium event. Message might describe a state change, something has been updated, or important information. | +Medium | +Medium event. Message might describe a state change, something has been updated, or important information. |
Major | -Major event. Message might describe architectural change or vital information. | +Major | +Major event. Message might describe architectural change or vital information. |
+
Many commands exist in single and batch versions. Large concentrators require efficient ways to manage sets of nodes simultaneously, while for small concentrators, it is sufficient to manage nodes one at a time. -
-+
+A concentrator is not required to implement both sets of commands if not desired. However, it must report which commands it supports in the getCapabilities command. A caller can then adapt its calls based on what commands are supported. -
-+
+If a caller wants to call the single item version of a command, but the concentrator only supports the batch version, it should call the batch version, but only include the single node in the list of nodes. -
-+
+On the other hand, if the caller wants to perform an operation on a set of nodes, but the concentrator only supports the single item version of the command, it needs to manually perform the operation on each node separately, unless failing the request is an option. -
-+
+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-IoT-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 Internet of Things - 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 concentrator only allows access according to rules defined 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: +
++ This section shows how a provisioning server can be used to restrict access to node parameters that users allowed to access and edit. +
++ +
++ 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: +
+This document requires no interaction with &IANA;.
++ The protocol schema needs to be added to the list of XMPP protocol schemas.
-- 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: -
-- This section shows how a provisioning server can be used to restrict access to node parameters that users allowed to access and edit. -
-- -
-- 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: -
-This document requires no interaction with &IANA;.
-- The protocol schema needs to be added to the list of XMPP protocol schemas. -
-
-
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+ xmlns:xs='http://www.w3.org/2001/XMLSchema'
+ targetNamespace='urn:xmpp:iot:concentrators'
+ xmlns='urn:xmpp:iot:concentrators'
+ xmlns:sn='urn:xmpp:iot:sensordata'
+ xmlns:xd="jabber:x:data"
+ xmlns:xdv="http://jabber.org/protocol/xdata-validate"
+ xmlns:xdl="http://jabber.org/protocol/xdata-layout"
+ elementFormDefault='qualified'>
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
-
-
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-
-
-
-
-
-
-
-
-
+
+
+
]]>
-
-
-
-
- For more information, please see the following resources:
-
-
- -
+
+ + For more information, please see the following resources: +
+- The Sensor Network section of the XMPP Wiki contains further information about the - use of the sensor network XEPs, links to implementations, discussions, etc. + The Sensor Network section of the XMPP Wiki contains further information about the + use of the sensor network XEPs, links to implementations, discussions, etc.
-- The XEP's and related projects are also available on github, thanks to Joachim Lindborg. + The XEP's and related projects are also available on github, thanks to Joachim Lindborg.
-- A presentation giving an overview of all extensions related to Internet of Things can be found here: - http://prezi.com/esosntqhewhs/iot-xmpp/. -
-Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Klaudiusz Staniek for all valuable feedback.
-+ A presentation giving an overview of all extensions related to Internet of Things can be found here: + http://prezi.com/esosntqhewhs/iot-xmpp/. +
+Thanks to Joachim Lindborg, Karin Forsell, Tina Beckman and Klaudiusz Staniek for all valuable feedback.
+