BSR/ASHRAE Addendum to ANSI/ASHRAE Standard 135-2010 ... · BSR/ASHRAE Addendum am to ANSI/ASHRAE Standard 135-2010 Advisory Public Review Draft _____ ASHRAE Standard Proposed Addendum

BSR/ASHRAE Addendum am to ANSI/ASHRAE Standard 135-2010

Advisory Public Review Draft

_____________________________________

ASHRAE Standard

Proposed Addendum am to Standard 135-2010, BACnet—A Data Communication Protocol for Building Automation and Control Networks

First Advisory Public Review (September 2011) (Draft Shows Proposed Changes to Current Standard) This draft has been recommended for public review by the responsible project committee. To submit a comment on this proposed addendum, go to the ASHRAE website at http://www.ashrae.org/technology/page/331 and access the online comment database. The draft is subject to modification until it is approved for publication by the Board of Directors and ANSI. Until this time, the current edition of the standard (as modified by any published addenda on the ASHRAE web site) remains in effect. The current edition of any standard may be purchased from the ASHRAE Bookstore @ http://www/ashrae.org or by calling 404-636-8400 or 1-800-527-4723 (for orders in the U.S. or Canada). This standard is under continuous maintenance. To propose a change to the current standard, use the change submittal form available on the ASHRAE web site @ http://www/ashrae.org. The appearance of any technical data or editorial material in this public review document does not constitute endorsement, warranty, or guaranty by ASHRAE of any product, service, process, procedure, or design, and ASHRAE expressly disclaims such. © 2011. This draft is covered under ASHRAE copyright. Permission to reproduce or redistribute all or any part of this document must be obtained from the ASHRAE Manager of Standards, 1791 Tullie Circle, NE, Atlanta, GA 30329-2305. Phone: 404-636-8400, Ext1125. Fax: 404-321-5478. E-mail: [email protected]. AMERICAN SOCIETY OF HEATING, REFRIGERATING AND AIR-CONDITIONING ENGINEERS, INC. 1791 Tullie Circle, NE · Atlanta GA 30329-230

© 2011 American Society of Heating, Refrigerating and Air-Conditioning Engineers, Inc. (www.ashrae.org). For personal use only. Additional reproduction, distribution, or transmission in either print or digital form is not permitted without ASHRAE’s prior written permission.

2

[This foreword and the “rationales” on the following pages are not part of this standard. They are merely informative and do not contain requirements necessary for conformance to the standard.]

FOREWORD The purpose of this addendum is to present a proposed change for public review. These modifications are the result of change proposals made pursuant to the ASHRAE continuous maintenance procedures and of deliberations within Standing Standard Project Committee 135. The proposed changes are summarized below. 135-2010am-1 Extend BACnet/WS with RESTful Services for Complex Data Types and Subscriptions, p. 2 In the following document, language to be added to existing clauses of ANSI/ASHRAE 135-2010 and Addenda is indicated through the use of italics, while deletions are indicated by strikethrough. Where entirely new subclauses are proposed to be added, plain type is used throughout. Only this new and deleted text is open to comment at this time. All other material in this addendum is provided for context only and is not open for public review comment except as it relates to the proposed changes.


3

135-2010am-1 Extend BACnet/WS with RESTful Services for Complex Data Types and Subscriptions Rationale The existing ANNEX N, BACnet Web Services, was designed for simple data exchange and simple history retrieval for simple clients. More sophisticated clients and use cases, such as those needed by the Smart Grid, require the addition of more capable services. Proposed Solution: Add new services to provide structured data exchange, full history retrieval, and subscriptions. Requirements: These additions to the BACnet/WS standard are designed to meet the following requirements: 1) Allow the exchange of structured data: The existing services only returned plain text values for primitive, and array of primitive, datatypes. These new services allow the exchange of structured data using XML. Structured data is exchanged using the XML syntax defined in ANNEX Q. The structured data is retrieved and updated using the HTTP GET and PUT methods of the Atom Publishing Protocol. 2) Allow the creation and deletion of server data: The existing services only allow the reading or writing of existing data nodes on the server. These new services provide a means of creating or deleting data on the server, whereever the server allows such operations. The data is created and deleted using the HTTP POST and DELETE methods of the Atom Publishing Protocol. 3) Allow retrieval of non-periodic trend histories: The existing services only allow the retrieval of periodic samples of primitive data in plain text, where the timestamps of the data are implied by its periodicity. The new services return data in XML allowing not only the inclusion of explicit timestamp information, but also error information, log buffer activity information, and even has the possibility of returning non-primitive data structures. 4) Allow current plain text services in REST: The exchange of simple text data, as provided by the existing SOAP messages, has a strong use case and is retained in the new REST interface using a non-Atom "alternative representation." All the Annex N attributes, like "Value," "WritableValues," etc., may be retrieved and set in plain text. 5) Allow items to have globally unique identifiers: Every item has a permanent, globally unique identifier. This identifier is expressed in the Atom <id> element. The identifier is permanent, so for data that can move, it should be in a non-dereferenceable form like "urn:uuid..." style. But for simple nonmoveable data, it can just be constructed on the fly from the URL of the data so no additional storage is needed. It can be searched for using filters that look for attributes with a given value. 6) Allow the creation of subscriptions: These new services allow the creation of subscriptions for change-of-value, trend reporting, and event reporting. The data records generated are available in timestamped Atom feeds to allow for targeted polling by clients that do not want to use, or cannot use, active callbacks. 7) Allow the definitions of active callbacks: For clients that can accept active callbacks, a mechanism is defined to allow them to specify how to the server should send them new records for change of value, trend, or event notification. The callback is accomplished using an HTTP POST method according to the PubSubHubbub procedure. 8) Creation of subscriptions by a third party or setup tool: Subscriptions can be created on the server "on behalf of" the actual recipient by a third device or setup tool. This is made to work in conjunction with


4

PubSubHubbub's verification process by having the final recipient "accept" the verification message sent by the server after recognizing that it was originated by a trusted tool and not itself. 9) Movement of trend history from source to archives: Through the use of subscriptions and active callbacks, trended data can be automatically moved from the source history feed to an archive server. The archive server can record the original source id and source location in Atom <link> elements which can be queried by a client when trying to find the archived records on the archive server. 10) Allow exchange of XML data defined by others (e.g. Smart Grid): The Atom Publishing Protocol supports this "foreign XML" (XML defined by others) as well as our "native XML" (CSML). The difference is that our servers can "drill down" to access only portions of CSML nodes but must treat foreign XML as a whole. Nonetheless, it can be retrieved, updated, created, and deleted. 11) Allow exchange of arbitrary media or bulk data: The Atom Publishing Protocol format also supports arbitrary "media" entries. These can be used to retrieve, update, create, and delete any kind of media type, documents, pictures, etc. 12) Allow client to specify/filter the contents of data: To prevent transmission of redundant or unwanted data, the client can specify what kinds of data it wants returned. This is accomplished by various filters that select the degree of metadata included in the transfer as well as filtering selected entries from large collections. 13) Allow the client to specify the range of data: For handling large sets of data, or to work within limited client or server capabilities, the client can read only a restricted range of the available data. This is accomplished by time ranges and/or index and count restrictions. 14) Allow for chaining the retrieval of large data sets: If the client specifies more records than can be returned by the server, or by the client's count limitation, the server indicates the availability of more data with an Atom 'next' link. The client can continue to follow this 'next' link until all available data is returned. 15) Allow a resource to mirror data for another resource: In the case where an aggregating server has collected data from other servers, either to provide a common place for convenience, or to provide archiving services for trends or alarms, resources that hold data that originated in another location need to have a standard way to point to their source. This is done with a "source-id" and "source-loc" Atom links. The "source-loc" link contains the dereferenceable URL of the source of the data and the "source-id" contains the nondereferenceable Atom <id> of the data. 16) Allow searching for data (like Who-Has or the proposed Who-Has-Property): Metadata like Atom links can be present on all addressable data. To make searching a reasonable thing to implement for servers, by convention, most interesting metadata, like categories and links, are placed at the "object" granularity. "Object is a generic concept and may be BACnet or non-BACnet objects. The server then provides a /.sysinfo/.all-objects feed which can be filtered to find particular objects based on their Atom metadata or object property value. The client specifies the values it is interested in with the 'filter' query parameter and the server populates the results list with the objects matching the query. To control the size of the response, however, the objects are returned by reference, not inline. 17) Allow discovery of data by semantic meaning: The use of standard Atom <category> elements allows a flexible and extensible means to tag objects with meaning and usage information that can be queried with the 'filter' query parameter. 18) Allow discovery of "interfaces:" Interfaces are defined in an abstract manner but are modeled to be compatible with binary realizations of the BACnet Structured View object. Thus, both standard and proprietary, BACnet and non-BACnet interfaces are supported and are commonly discoverable through a dedicated feed.


5

[This Table of contents is provided only for convenience in this addendum. It will not be part of the Standard] Table of Contents

ANNEX N - BACnet/WS WEB SERVICES INTERFACE (NORMATIVE) ........................................................ 7 N.15.1 Representation of Node Attributes .................................................................................... 13

N.15.1.1 Default representation .................................................................................................. 13 N.15.1.2 Alternate representation: 'direct' ................................................................................... 13

N.15.2 Representation of Nodes ..................................................................................................... 13 N.15.2.1 Default representation .................................................................................................. 13 N.15.2.2 Alternative representation: 'direct' ................................................................................ 14 N.15.2.3 Alternative representation: 'feed' .................................................................................. 14

N.15.3 Representation of Time Series Data .................................................................................. 14 N.15.3.1 BACnet Trend Log Records ......................................................................................... 14 N.15.3.2 BACnet Trend Log Multiple Records .......................................................................... 14 N.15.3.3 BACnet Event Log Records ......................................................................................... 15 N.15.3.4 Non-BACnet Records ................................................................................................... 15 N.15.3.5 Retrieving Periodic Samples ........................................................................................ 15

N.15.4 Representing Foreign XML ................................................................................................ 15 N.15.4.1 Default representation .................................................................................................. 15 N.15.4.2 Alternative representation: 'direct' ................................................................................ 15

N.15.5 Extensions to Atom Publishing Protocol ........................................................................... 16 N.15.5.1 Filtering Responses ...................................................................................................... 16 N.15.5.2 Limiting Responses ...................................................................................................... 17 N.15.5.3 Alternate Representations ............................................................................................. 17

N.15.6 Controlling CSML Content ................................................................................................ 18 N.15.6.1 Default Content ............................................................................................................ 18 N.15.6.2 Enhanced Content ......................................................................................................... 18

N.15.7 Semantics ............................................................................................................................. 19 N.15.8 Relationships ........................................................................................................................ 20 N.15.9 Representing Objects .......................................................................................................... 21

N.15.9.1 BACnet Objects ............................................................................................................ 21 N.15.9.2 Non-BACnet Objects. ................................................................................................... 21

N.15.10 Interfaces ......................................................................................................................... 22 N.15.10.1 Representing BACnet Application Interfaces .............................................................. 22 N.15.10.2 Representing Non-BACnet Interfaces. ......................................................................... 22 N.15.10.3 Traversing Interfaces. ................................................................................................... 22

N.15.11 Indirection ....................................................................................................................... 23 N.15.12 Standard feeds ................................................................................................................. 24

N.15.12.1 Feed /.sysinfo/all-objects .............................................................................................. 24 N.15.12.2 Feed /.sysinfo/all-interfaces .......................................................................................... 24 N.15.12.3 Feed .../.value-history ................................................................................................... 24 N.15.12.4 Feed .../.value-changes ................................................................................................. 24 N.15.12.5 Feed .../.event-history ................................................................................................... 24

N.15.13 Working With Optional Data ........................................................................................ 25 N.15.14 Creating Data .................................................................................................................. 26 N.15.15 Setting Data ..................................................................................................................... 26 N.15.16 Deleting Data ................................................................................................................... 26


6

N.15.17 Server Support for Atom Metadata .............................................................................. 27 N.15.18 Subscriptions ................................................................................................................... 28

N.15.18.1 Subscriber Initiates Subscription Request .................................................................... 28 N.15.18.2 Server Verifies the Intent of the Subscriber ................................................................. 29 N.15.18.3 Automatic Subscription Refresing ................................................................................ 30 N.15.18.4 Distribution ................................................................................................................... 31

N.15.19 Examples .......................................................................................................................... 32 N.15.19.1 Getting a Scalar Attribute in the Default Representation (Atom) ................................ 32 N.15.19.2 Getting an Array Attribute in the Default Representation (Atom) ............................... 32 N.15.19.3 Getting a Scalar Attribute with Alternate Representation alt=direct ............................ 32 N.15.19.4 Getting an Array Attribute with Alternate Representation alt=direct .......................... 32 N.15.19.5 Getting a Localized Value ............................................................................................ 32 N.15.19.6 Getting a Primitive Node in the Default Representation (Atom) ................................. 33 N.15.19.7 Getting a Constructed Node in the Default Representation (Atom) ............................. 33 N.15.19.8 Getting a Primitive Node in the Alternate Representation alt=direct ........................... 33 N.15.19.9 Getting a Constructed Node in the Alternate Representation alt=direct ...................... 34 N.15.19.10 Getting a Constructed Node in the Alternative Representation alt=feed ................. 34 N.15.19.11 Getting Time Series Records From a BACnet Trend Log ....................................... 35 N.15.19.12 Getting Time Series Records From a BACnet Trend Log Multiple ........................ 35 N.15.19.13 Getting Foreign XML in the Default Representation (Atom) .................................. 36 N.15.19.14 Getting Foreign XML in the Alternative Representation alt=direct ........................ 37 N.15.19.15 Getting CMSL Metadata with the 'csmlmetadata' Parameter ................................... 37 N.15.19.16 Getting a Filtered List of Objects ............................................................................. 38 N.15.19.17 Working with Optional Data .................................................................................... 39 N.15.19.18 Creating Data ........................................................................................................... 40 N.15.19.19 Putting a Scalar Attribute in the Default Representation (Atom) ............................ 40 N.15.19.20 Deleting Data ........................................................................................................... 41


7

[Change ANNEX N p. 886]

ANNEX N - BACnet/WS WEB SERVICES INTERFACE (NORMATIVE)

(This annex is part of this standard and is required for its use.) This annex defines a data model and Web service interface interfaces (both SOAP and REST) for integrating facility data from disparate data sources with a variety of business management applications. The data model and access services are generic and can be used to model and access data from any source, whether the server owns the data locally or is acting as a gateway to other standard or proprietary protocols. Implementations of the SOAP services described in this standard shall conform to the Web Services Interoperability Organization (WS-I) Basic Profile 1.0, which specifies the use of Simple Object Access Protocol (SOAP) 1.1 over Hypertext Transfer Protocol -- HTTP/1.1 (RFC 2616) and encodes the data for transport using Extensible Markup Language (XML) 1.0 (Second Edition), which uses the datatypes and the lexical and canonical representations defined by the World Wide Web Consortium XML Schema. Implementations of the REST services described in this standard shall conform to the Atom Publishing Protocol (RFC 5023) using data formatted in the Atom Syndication Format (RFC 4287), except as noted in "Extensions to Atom". Clients may determine the version of the BACnet/WS standard that a server implements by querying a specific numerical value as defined in Clause N.9. The numerical value for the version described in this document is 1 2. [Change Clause N.1, p. 886]

N.1 Data Model

... Any node may either have a value or be a data structure or collection. The possible types for a node's value are limited to the primitive datatypes "String", "BitString", "OctetString", "Real", "Double", "Integer", "Unsigned", "Multistate", "Enumerated", "Null", "Boolean", "Date", "DatePattern", "Time", "TimePattern", "DateTime", "DateTimePattern", "ObjectIdentifier", "ObjectIdentifierPattern", "WeekNDay", and "Duration". Nodes that have a value may also have other attributes related to that value, such as minimum, writable, etc. Nodes that are data structures or collections have possible types of "Sequence", "SequenceOf", "Object", "List", "Array", and "Feed". [Change Clause N.8, p. 889]

N.8 Attributes

A node is exposed to Web services as a collection of named attributes. There are two forms of attributes: those that are a primitive datatype, and those that are an array of primitive datatypes. Only the Value attribute is writable with the SOAP services defined by this standard. [Change Clause N.8.3, p.890] N.8.3 Array Attributes ... When array attributes are accessed with a service that returns an array, such as SOAP getArray, the array elements are returned as individual strings. However, when accessed with a service that returns a single string, such as SOAP getValue, or a REST GET, the array values are concatenated into a single string by separating the array elements with a ';' (semicolon) character, for example, "high;medium;low". The values of the individual array elements are not permitted to contain semicolons. [Change Clause N.8.5, p.891]


8

N.8.5 NodeType ... {"Unknown", "System", "Network", "Device", "Functional", "Organizational", "Area", "Equipment", "Point", "Collection", "Object", "Property", "Data", "Other"} ...A "Collection" is just a generic container used to group things together such as a collection of references to all space temperatures in a building. An "Object" is a generic concept that may or may not represent data from a BACnet object. "Object" is generic, where "Point" or "Equipment" may be used to represent more specialized kinds of objects. The "Property" type is intended to model data that is logically part of the a parent node, like an Object. The "Data" type is used to hold miscellaneous data, often as a sub-part of a Property. The "Other" type is used for everything that does not fit into one of these broad categories. [Change Clause N.8.9, p.892] N.8.9 ValueType This required attribute indicates the datatype of the node. For nodes that have a value, this specifies the datatype of the Value attribute and attributes restricting the Value attribute. If the node has no value and is not a data structure or collection, then this attribute shall have the value "None". The list of values for this attribute is not extensible. The allowable values for this attribute are: {"None", "String", "BitString", "OctetString", "Real", "Double", "Integer", "Unsigned", "Multistate", "Enumerated", "Null, "Boolean", "Date", "DataPattern", "Time", "TimePattern", "DateTime", "DateTimePattern", "ObjectIdentifier", "ObjectIdentifierPattern", "WeekNDay", "Feed", "Duration"}

"Multistate" is a synonym for "Enumerated". The "None" type is used when the node does not have a value and is not a data structure or collection. The "String" type is used for nodes that have character string values that are intended to be human readable. An "OctetString" is used to contain arbitrary binary data that is typically not human readable. A "Real" is a floating point value, for example 75.6. An "Integer" is for values that that are expressed in whole numbers, for example, 1234. A "Multistate" "Enumerated" is a value that is a choice from a set of named states, for example, {"high", "medium", "low"}. A "Boolean" is a choice between exactly two named states, such as "on" and "off", one of which is considered true and the other false. A "Date" is used to represent values that are calendar dates. A "Time" is used to represent a time of day. A "DateTime" is used to represent an exact moment in time, specifying both a date and a time. A "Duration" represents a time span, such as "5 seconds." The representation of all some value types other than "None" and "OctetString" may be affected by the "locale" service option if the server supports localization for a particular locale or locales. See Clauses N.5 and N.11.4. The effect of this attribute on the datatype of Value and related attributes is summarized in the following table. The datatypes referred to in the table are XML Schema datatype names. See Clause N.10 for more information on encoding of Web services. Attributes whose datatype is listed as n/a in the table shall not be present in the node.

Table N-2. Effect of ValueType Attribute

ValueType Attribute Value

Value Attribute Datatype

Minimum Attribute Datatype

Maximum Attribute Datatype

Resolution Attribute Datatype

"None" n/a n/a n/a n/a "String" string n/a n/a n/a "BitString" string n/a n/a n/a "OctetString" base64Binary n/a n/a n/a "Real" double double double double "Double" double double double double "Integer" integer integer integer integer "Unsigned" nonNegativeInteger nonNegativeInteger nonNegativeInteger nonNegativeInteger


9

[Change Clause N.8.28, p. 895] N.8.28 HasHistory This optional attribute indicates that there are historical records for this node. Clients may use this to determine if the SOAP getHistoryPeriodic service or the REST .value-history feed is applicable to this node. [Change Table N-3, p. 896]

Table N-3. Standard Nodes

Node Path ValueType NodeType Presence Meaning of the Value ... ... … … ... /.sysinfo/.standard-version "Integer" "Other" Required The version of the standard that the

server is implementing, as defined in the prolog to this Annex.

/.sysinfo/.default-locale "String" "Data" Required The same value that would be returned from the SOAP getDefaultLocale service

/.sysinfo/.support-locales "Array" (of "String")

"Data" Required An array of strings containing the same values that would be returned from the SOAP getSupportedLocales service

/.sysinfo/.all-objects "Feed" "Collection" Required for REST

An Atom feed of all objects in the server. See Clause N.15.12.1.

[Change Clause N.10.2, p. 897] N.10.2 SOAP Service Parameters This clause applies to the SOAP services only. Web service toolkits (software libraries) typically provide "language bindings" ... [Change Clause N.11, p. 897]

N.11 Service Options

Some services accept service options that modify their behavior or their return values.

"Multistate" string n/a n/a n/a "Enumerated" string n/a n/a n/a "Boolean" boolean n/a n/a n/a "Date" date date date integer (days) "DatePattern" string n/a n/a n/a "Time" time time time double (seconds) "TimePattern" string n/a n/a n/a "DateTime" dateTime dateTime dateTime double (seconds) "DateTimePattern" string n/a n/a n/a "ObjectIdentifier" string n/a n/a n/a "ObjectIdentifierPattern" string n/a n/a n/a "WeekNDay" string n/a n/a n/a "Duration" double (seconds) double (seconds) double (seconds) double (seconds)


10

For SOAP services, individual Individual options are specified in string form as simply "option-name" or "option-name=option-value". For example, "readback", or "locale=en-UK". When multiple options are combined into a single string, they are separated by a semicolon, such as "readback;locale=en-UK". White space is significant and shall not be stripped during parsing. The option-value is not constrained with the exception that it shall not contain a semicolon. For REST services, the service options are expressed as query parameters and are URL-encoded as part of a standard HTTP query string. All parameters are in the form "option-name=option-value". For example, "locale=en-UK". For SOAP services, the The '=' character and option-value may be omitted for boolean options. If a boolean option name is present without an option-value, then it assumes the value "true". Options with a default value of "true" will have to be explicitly set to "false". If an option-name is specified more than once in the string, the last one takes precedence. The strings used for option-name and option-value are not subject to the effects of the "locale" and "canonical" options. The option names are from the fixed set defined in this standard. The "Datatype" referred to in the following table is the XML Schema datatype name. This datatype defines the canonical format for the option value when represented as a string.

Table N-5. Service Options Option Name Service Type Datatype Default if Not Specified

"readback" SOAP boolean false "errorString" SOAP string (see Clause N.13) "errorPrefix" SOAP string empty string "locale" SOAP and REST string varies based on server configuration "writeSingleLocale" SOAP and REST boolean false "canonical" SOAP and REST boolean false "precision" SOAP and REST nonNegativeInteger 6 "noEmptyArrays" SOAP boolean false "alt" REST string empty string (See Clause 0) "resample-interval" REST double none (no resampling) "resample-method" REST string "default" "filter" REST string none (no filtering) "start-index" REST nonNegativeInteger 1 "max-results" REST nonNegativeInteger none (unlimited) "published-min" REST date beginning of time "published-max" REST date end of time "updated-min" REST date beginning of time "updated-max" REST date end of time

[Change Clause N.11.4, p. 898] N.11.4 locale This option specifies the locale that shall be used for formatting of plain text date/time values, units, numbers and string values by the server. The format of the locale option is: "locale=language-tag", where language-tag is in the form described by RFC 3066. For example, the locale string for US English is "en-US", and Canadian French is "fr-CA", and the corresponding service options would be formatted as "locale=en-US" and "locale=fr-CA". The value of the locale service option must match exactly one of the strings returned from the SOAP getSupportedLocales service or read from /.sysinfo/.supported-locales. There is no language fallback or hierarchical matching mechanism.


11

In services which read data from a node such as the SOAP getValue, getValues, or getArray services or a REST GET service which returns plain text values, the server is required to accept all values for the "locale" option which are returned by the SOAP getSupportedLocales service or read from /.sysinfo/.supported-locales. When writing data to a node with services such as the SOAP setValue or setValues services or a REST PUT or POST service which accepts plain text values, the server shall accept all values for the "locale" option which are returned in the WritableLocales attribute of the node. The error WS_ERR_LOCALE_NOT_SUPPORTED shall be returned if a locale is specified that the server does not support. [Add new Clauses N.11.X1-X5, p. 899]

N.11.X1 alt

Affects the representation of an Atom element's content in the HTTP body. See Clauses N.15.1 and N.15.2.

N.11.X2 resample-interval, resample-method

Cause time series records to be aligned to periodic intervals and possible resampled as needed. See Clause N.15.3.5.

N.11.X3 filter

Selects which entries are to be included in an Atom feed. See Clause N.15.5.1.

N.11.X4 start-index, max-results

Controls the starting point and count of entries included in an Atom feed. See Clause N.15.5.2.

N.11.X5 published-min, published-max, updated-min, updated-max

Selects which entries are to be included in an Atom feed based on time. . See Clause N.15.5.2. [Change Clause N.12, p. 900]

N.12 SOAP Services

For the definition of REST services, see Clause N.15. This clause defines the SOAP Web services that provide the means to access and manipulate the data in the server. [Change Clause N.13, p. 898] N.13 Errors For maximum interoperability with a wide range of clients, these Web the SOAP services avoid returning complex (constructed) datatypes by returning both valid data and errors in the same result string, and the REST services use HTTP status codes that best match the error condition. Both SOAP and REST error responses return an error string that is a combination of a number for machine readability and text for human readability. The default error string encoding is "? error-number error-message". More specifically, the string shall be composed of: a question mark character, followed by a single space character, followed by a standardized error number defined in the following table, in decimal form, followed by a single space character, followed by an informative human-readable error message whose content is a local matter. For SOAP services, the The default error encoding can be overridden by the client with the "errorString" service option (see Clause N.11.2 for examples). When the default format is overridden by the "errorString" service option, the string defined for the errorString option shall form the entire string generated for an error.


12

For REST services, the error string constitutes the HTTP body when allowed and appropriate for the specified HTTP status code.

Table N-30. Error Numbers Error Name Error Number HTTP status code Example Error Message

WS_ERR_OTHER 0 400 "Unspecified Error" WS_ERR_NOT_AUTHENTICATED 1 401 "Not Authenticated" WS_ERR_NOT_AUTHORIZED 2 401 "Not Authorized" WS_ERR_OPTIONS_SYNTAX 3 400 "Bad Options Syntax" WS_ERR_OPTION_NOT_SUPPORTED 4 501 "Option Not Supported" WS_ERR_OPTION_VALUE_FORMAT 5 400 "Bad Option Value Format" WS_ERR_OPTION_OUT_OF_RANGE 6 400 "Option Out of Range" WS_ERR_LOCALE_NOT_SUPPORTED 7 400 "Locale Not Supported" WS_ERR_PATH_SYNTAX 8 400 "Bad Path Syntax" WS_ERR_NODE_NOT_FOUND 9 404 "Node Not Found" WS_ERR_ATTRIBUTE_NOT_FOUND 10 404 "Attribute Not Found" WS_ERR_ILLEGAL_ATTRIBUTE 11 403 "Illegal Attribute" WS_ERR_VALUE_FORMAT 12 400 "Bad Value Format" WS_ERR_VALUE_OUT_OF_RANGE 13 400 "Value Out of Range" WS_ERR_INDEX_OUT_OF_RANGE 14 400 "Index Out of Range" WS_ERR_NOT_WRITABLE 15 403 "Not Writable" WS_ERR_WRITE_FAILED 16 400 "Write Failed" WS_ERR_LIST_OF_PATHS_IS_EMPTY 17 n/a "No Paths Provided " WS_ERR_COUNT_IS_ZERO 18 400 "Requested Count is Zero" WS_ERR_INTERVAL_IS_ZERO 19 400 "Requested Interval is Zero" WS_ERR_NO_HISTORY 20 404 "No History" WS_ERR_NO_DATA_AVAILABLE 21 404 "No Data Available" WS_ERR_EMPTY_ARRAY 22 n/a "Empty Array" WS_ERR_NOT_AN_ARRAY 23 400 "Not an Array" WS_ERR_COMMUNICATION_FAILED 24 400 "Communication with the

Remote Device Failed" WS_ERR_READBACK_FAILED 25 400 "The Readback Failed"


13

[Add new Clause N.15, p. 919]

N.15 REST Services The services defined in this clause use the HTTP REST (Representation State Transfer) model and are based on the Atom Publishing Protocol, except where noted. Other than the "alternate representation" described below, the data exchange services in this clause use the Atom Publishing Protocol as described in RFC 5023 and exchange XML formatted data in the Atom Syndication Format as defined in RFC 4287. Generally, the full capabilities of those standards are required to be present in implementations of this standard. A few exceptions to allow for minimized implementations are noted in the following clauses. Since the Atom Publishing Protocol does not directly define a mechanism for the pushing of feed data to clients, a related procedure, PubSubHubbub, is used for the publish/subscribe services defined here. These services are also based on HTTP methods and are designed to move Atom feeds from publisher to subscribers using active callbacks. To exchange structured data, the XML formats defined in ANNEX Q are used in these services. Since XML has "attributes" and the data model described in this standard also uses the term "attributes", the terms "XML attributes" and "node attributes" will be used in this section to distinguish between the two. The clients and servers shall be capable of representing data in a variety of formats depending on the client's needs. All default representations are in Atom Syndication Format. The "alternate representations" below are not Atom formatted, so Atom metadata like categories, links, etc., are not available in those forms. However, these alternative representations are available for clients that desire a brief "content-only" format.

N.15.1 Representation of Node Attributes

Node attributes, like Value, Minimum, Units, etc., are represented as plain text. Attribute values, in all representations, are subject to localization, as defined by Clause N.5.

N.15.1.1 Default representation

Be default, node attributes shall be represented as plain text in the <content> element of an Atom <entry> formatted as described in Clause N.8.3. The value of Atom elements other than <content> is a local matter. See Examples N.15.19.1 and N.15.19.2.

N.15.1.2 Alternate representation: 'direct'

When the alt=direct query parameter is used, the HTTP Content-Type shall be set to text/plain, and the contents of the <content> element as described for the default case above shall be placed directly in the HTTP body. See Examples N.15.19.3 and N.15.19.4.

N.15.2 Representation of Nodes

Nodes shall be represented as their corresponding CSML elements, such as <Real>, <Sequence>, <Array>, <Object>, etc.


A node shall be represented as a CSML element in the <content> element of an Atom <entry>. The <content> element's 'type' attribute shall be set to "application/xml," and the CMSL namespace shall be set as the default namespace on the top CSML element. The value of the Atom <title> element shall be the node's displayName if it exists; else the value is a local matter. For <Object> nodes, Atom <category> elements shall be used to represent any semantic tags that are present for the object. The values of other Atom elements are a local matter. See Examples N.15.19.6 and N.15.19.7.


14

N.15.2.2 Alternative representation: 'direct'

When the alt=direct query parameter is used, the HTTP Content-Type shall be set to application/xml, and the contents of the <content> element as described for the default case above shall be placed directly in the HTTP body. See Examples N.15.19.8 and N.15.19.9.

N.15.2.3 Alternative representation: 'feed'

A constructed node is normally represented as a single constructed CSML element; however, to allow chaining of large data sets or for other client data handling reasons, the members of a constructed node can also be represented as individual Atom entries in an Atom feed by using the alt=feed query parameter. This representation shall be available for all types of constructed CSML elements, i.e, <Object>, <List>, <Array>, <Sequence>, and <SequenceOf> and shall not be applicable to primitive elements. The alt=feed parameter is only applicable to GET operations. Nodes represented by <List> and <SequenceOf> elements have an inherent ability to accept a POST operation to add a new member, so alt=feed is not needed for that operation. When represented in this format, the value of the <content> element of each <entry> in the <feed> shall be a single CSML element representing a single member of the constructed node. The <content> element's 'type' attribute shall be set to "application/xml," and the CMSL namespace shall be set as the default namespace on the top CSML element in each <content>. The value of the <feed> element's <title> shall be the node's displayName if it exists, and the value of each <entry> element's <title> shall be the corresponding member's displayName if it exists; else the values are a local matter. For <Object> nodes, Atom <category> elements shall be used on the <feed> to represent any semantic tags that are present for the object. The values of other Atom elements are a local matter.

N.15.3 Representation of Time Series Data

Data records in a time series shall be represented as Atom entries, and the series itself shall be represented as an Atom feed. The timestamp of a record is always returned in the Atom <published> element, and the value portion of a record is always returned in the entry's <content> element; however, the format of the value varies based on its type as defined in the following clauses. The value of other Atom elements is a local matter.

N.15.3.1 BACnet Trend Log Records

The representation for the values of a time series originating from a BACnet Trend Log object shall use the simplest possible representation for each record, as follows: If the record contains a normal sample value (a 'logDatum' choice of 'boolean-value', 'real-value', 'enum-value', 'unsigned-value', 'signed-value', or 'bitstring-value'), then the sample value shall be represented in plain text, e.g. <content>75.5</content>. If status flags are present and at least one flag is true, then the value of the status flags shall appended after a semicolon to the sample value, e.g. <content>75.5;fault,overridden</content>. If the record contains anything other than a normal sample value, then the full BACnetLogRecord shall be formatted in CSML and placed in the <content> element. See example N.15.19.11.

N.15.3.2 BACnet Trend Log Multiple Records

The representation for the values of a time series originating from a BACnet Trend Log object shall use the simplest possible representation for each record, as follows: If the record contains nothing but normal sample values (it contains a 'logData' choice of 'log-data' and the 'log-data' Sequence-Of members are all 'boolean-value', 'real-value', 'enum-value', 'unsigned-value', 'signed-value', or 'bitstring-value'), then the sample values shall be represented in plain text separated by semicolons, e.g. <content>75.5;12345;100.0</content>.


15

If the record contains anything other than normal sample values, then the full BACnetLogMultipleRecord shall be formatted in CSML and placed in the <content> element. See example N.15.19.12.

N.15.3.3 BACnet Event Log Records

The representation for value of a time series originating from a BACnet Event Log Object shall always be represented by formatting the full BACnetEventLogRecord in CSML and placing it in the <content> element.

N.15.3.4 Non-BACnet Records

For maximum interoperability, if time series data records from a source other than a BACnet log object can be represented as if it originated from a BACnet Trend Log or Trend Log Multiple (i.e., the data is a subset of what is available with one of those two formats), then the data shall be represented according to the appropriate BACnet format defined in the preceding clauses. If the data is not a subset of those formats, then the representation of the data records is a local matter.

N.15.3.5 Retrieving Periodic Samples

If the client desires a periodic sampling rather than the raw time series records, it shall specify the 'resample-interval' query parameter, and optionally, the 'resample-method' query parameter. In this case, the server shall use the method described in Clause N.12.9 to select or synthesize a set of periodic records to return (where 'resample-interval' and 'resample-method' query parameters correspond to the "Interval" and "Resample Method" service parameters in Clause N.12.9). The resultant synthesized records shall be presented in the same format as they normally would be for the given trend data source, with appropriately constructed errors for records where the resampling algorithm in N.12.9 says to use WS_ERR_NO_DATA_AVAILABLE.

N.15.4 Representing Foreign XML

XML resources that are not represented in CSML are considered "foreign XML" but are handled in much the same way as CSML resources for basic GET, PUT, POST, and DELETE operations. The difference is that foreign XML is not required to be "understood" by the server, and the server is not required to be able to descend into foreign XML with an implied URL hierarchy that extends beyond the start of the foreign XML resource. For example, if /foo/bar refers to a foreign XML resource, the server is not required to be able to process a request for /foo/bar/baz, even though there may indeed be a "baz" member in the foreign XML. Likewise, the server is also not required to support filtering based on any such descent into the foreign XML. Note that the preceding is only a non-requirement, not a prohibition. Some servers may in fact understand some foreign XML dialects, so support for features like hierarchical descent or filtering into foreign XML remains a local matter.


XML from other namespaces is hosted inside a <content> element of an Atom <entry> by default. The placement of the namespace designator for the Foreign XML is a local matter; however, it is recommended that, if possible, it be placed as the default namespace on the top-level element of the foreign XML under <content>. This allows the foreign content to be separated from its Atom wrapper and maintain its namespace designator. The values of the other Atom elements are a local matter. See example N.15.19.13

N.15.4.2 Alternative representation: 'direct'

Foreign XML can be retrieved without the Atom wrapper using the alt='direct' query parameter. When this option is used, the server shall return the content, unwrapped, in its own namespace. See Example N.15.19.14


16

N.15.5 Extensions to Atom Publishing Protocol

Beyond the capabilities defined by the Atom Publishing Protocol, BACnet clients and servers can take advantage of extensions defined by this specification.

N.15.5.1 Filtering Responses

The entries returned from a feed can be filtered with the query parameters 'filter'. The 'filter' query parameter uses a subset of XPath to define which entries in a feed shall be returned. Only those entries matching the filter criteria shall be returned in the feed. [Reviewer note: 'filter' is very similar, but not identical to '$filter,' in OData] Filtering is very useful with large feeds (for example, "/objects") which might be too large to handle if not filtered. For example, this query returns all objects with a category of "meter". GET /objects?filter=category[@term='meter' and @scheme="http://example.com/cats"]

The 'filter' parameter can be used for any attribute of any descendent of the Atom entry. In this example, filtering is used to find data in an archive of data gathered from other sources by looking for references to the original source’s 'id'. This example will find all entries in the feed with an Atom <link> containing the 'id' of the source data. GET /log-archives/?filter=link[@rel='http://bacnet.org/rel/source-id' and @href='urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a']

The server shall apply the 'filter' parameter to all child elements of the Atom entry (as shown in the examples above) and to any entry content of type CSML (as shown in the next example). Support for filtering based on other content types (e.g., traversing into Foreign XML) is a local matter. In this example, the filter applies to elements and attributes inside CSML content. This filter selects that only entries in the /objects feed which have content containing <Object ...><Unsigned name='group-id' value='14373'/>...</Object> will be returned. GET /objects/?filter=content/Object/Unsigned[@name='group-number' and @value='14373']

The 'filter' parameter shall apply to run-time persistent data, i.e., data that does not change during the normal operation of the device, such as constant or configuration data. It is not expected to function for dynamic data, and support for filtering based on dynamic data is a local matter. The 'filter' query parameters uses a subset of the XPath syntax. Only the forms specified here are required. Support for further capabilities of XPath is a local matter. The required forms are:

TypeName

Selects all immediate children of type TypeName. (A TypeName of '*' matches all element types)

TypeName[predicate]

Selects all immediate children of type TypeName that match the conditions in the predicate.

//TypeName

Selects all descendants at any depth of type TypeName.


17

//TypeName[predicate]

Selects all descendants at any depth of type TypeName that match the conditions in the predicate.

The required predicate forms are:

The required conditions are:

@attribute-nameOP'attribute-value'

Evaluates the contents of the identified attribute against the given value, where OP is one of: '=', '!=', '>', '>=', '<', and '<='.

contains(@attribute-name,'sub-string')

Determines whether the string form of the identified attribute contains the given non-zero-length sub-string value.

N.15.5.2 Limiting Responses

The entries returned from a feed can be limited with the query parameters 'start-index', and 'max-results', 'published-min', 'published-max', 'updated-min', and 'updated-max' . [Reviewer note: 'start-index', and 'max-results', 'published-min', 'published-max', 'updated-min', 'updated-max' are identical in name and function to GData.]

N.15.5.2.1 start-index

The 'start-index' and 'max-results' query parameters allow the retrieval of blocks of entries from any feed. The 'start-index' is 1-based, so the first member is at index 1.

N.15.5.2.2 max-results

The 'max-results' query parameter limits the number of entries returned for a feed. If the feed, after filtering, contains more than 'max-results' entries, then only the first 'max-results' entries are returned, and a <link rel="next" ...> element is included in the feed for clients to use to obtain the next set of entries.

N.15.5.2.3 published-min, published-max, updated-min, updated-max

The <published> and <updated> datetimes can be tested using the 'published-min,', 'published-max', 'updates-min', and 'updated-max' query parameters. All datetimes are in RFC 3339 timestamp format. For example: "2008-02-28T18:47:02.303Z". To allow proper chaining, the lower bound is inclusive, whereas the upper bound is exclusive.

N.15.5.3 Alternate Representations

The <content> of any Atom entry can be manipulated (GET, PUT, POST) separately from the rest of the Atom entry by use of the alt=direct query parameter, as described in Clauses N.15.1 and N.15.2. The allowed operations, and paths on which they operate, shall be identical for the two formats, excepting of course that the Atom metadata in the wrapper is not available in the alt=direct format. (Note that the creation of a new resource with a POST uses the HTTP Location header to return the new resource location and is thus also not dependent on the Atom wrapper). See Clauses N.15.1 and N.15.2 for more information and references to examples. Atom feeds have no alt=direct form.

[condition]

Selects all nodes that match condition.

[condition1 and condition2]

Selects all nodes that match condition1 and condition2.

[condition1 and condition2 … and conditionN]

Selects all nodes that match all conditions, condition1through conditionN.


18

N.15.6 Controlling CSML Content

During run-time, a client typically only needs to work with the "values" of the data it is querying or updating. However, during discovery, the client needs to know much more about the data, including all the CSML metadata like datatypes, display names, writability, units, limits, volatility, named values, etc.

N.15.6.1 Default Content

By default, the server shall return the name and all value-related items of the CSML data it returns. The value-related items consist of the 'value' attribute and all related attributes and elements when applicable, i.e., the 'valueAge', 'error', 'charset', 'codepage', 'unspecifiedValue' and 'length' attributes, and the <Error> and <Value> child elements.

N.15.6.2 Enhanced Content

The number of XML attributes and sub-elements returned as part of CSML data can be controlled by the query parameter, 'csmlmetadata'. Setting this query parameter as csmlmetadata=types shall cause the server to return the 'type' and 'memberType' attribute on all CSML elements for which it knows the type information. Setting this query parameter as csmlmetadata=all shall cause the server to return all the CSML metadata it knows for all CSML elements. Note that this standard requires the server to return all the metadata "that it knows." This means that the server is not required to know all possible CSML metadata for all the data that it serves; however, it is highly recommended that the server at least knows the 'type' and 'member' of the data it returns. This will allow the client to look that type up by some out-of-band means to retrieve more metadata. See example N.15.19.15.


19

N.15.7 Semantics

Nodes that are represented by CSML <Object> elements are special in one way. They are the expected home of semantic tagging. Semantic tags are represented as Atom <category> elements. An object can have multiple semantic tags from multiple tagging schemes applied to it. BACnet objects that contain the Categories property shall have the data from that property reflected into one or more Atom <category> elements. [Reviewer note: the Categories property is in a separate change proposal.] One important benefit of semantic tagging is to find data based on its tags. Therefore, it is required that all servers support the feeds /.sysinfo/all-objects and /.sysinfo/bacnet-objects and support filtering with the 'filter' query parameter to find objects with particular Atom <category> values. For example, this query returns all objects with semantic tag of "meter" from the tag scheme maintained by example.org. GET /.sysinfo/all-objects?filter=category[@term='meter' and @scheme="http://example.org/cats"] It is expected that multiple organizations will define tagging schemes, and reference to any in particular is beyond the scope of this specification.


20

N.15.8 Relationships

Expressing Relationships between Atom entries and feeds is accomplished with the Atom <link> element. Atom defines several standard relationship types, e.g., "self", "next", etc. for these purposes. In addition, for expression of other kinds of relationships, this standard defines several new relationship types. Note that using "http://" as a prefix for custom relation types is a convention only, like that used for namespaces; it does not necessarily imply a dereferenceable resource.

'rel' value Applies to 'href' value Notes http://bacnet.org/csml/rel#device objects URL of the

representation of the device that contains the object.

http://bacnet.org/csml/rel#source-id any Node The Atom <id> of the original source of the data

used by proxies and archives to refer to the identity of the original source of the data.

http://bacnet.org/csml/rel#source-loc any Node URL of the representation of the original source of the data.

used by proxies and archives to point to the location of the original source of the data.


21

N.15.9 Representing Objects

When representing CSML <Object> elements as Atom entries, several promotion rules are established to fulfill Atom client expectations.

N.15.9.1 BACnet Objects

When representing BACnet objects as Atom entries, the following rules apply. The <title> element shall be in plain text. The content of the title shall be a local matter with the exception that it shall not be empty. The following guidance is provided: the server should strive to make a meaningful title out of the object's Description, Object_Name, and Object_Identifier properties, and possibly, the containing device's name if multiple devices are being represented. The purpose, of course, is to make a meaningful and unique name for the benefit of the discovering client. The <author> element shall be the name of the operator or process that last changed the object, if known. The <published> element shall be the time at which the object was created, if known. The <updated> element shall be the time the object was last modified, if known. If any of these is not known, then its value is a local matter. The <category> elements shall be populated from the members of the object's Categories property, if present, plus any other applicable semantic tags that are known to the server. [Reviewer note: the Categories property is in a separate change proposal.] The <link> elements shall be populated with any inter-object relationships that can be expressed by the server. Specifically, if the object's device is modeled on the server, a <link> with rel="http://bacnet.org/rel/device" shall be provided with an href="..." that points to the device representation on the server.

N.15.9.2 Non-BACnet Objects

When representing non-BACnet objects as Atom entries, the following rules apply. The <title> element shall be in plain text. The content of the title shall be a local matter with the exception that it shall not be empty. The following guidance is provided: the server should strive to make a meaningful title out of whatever information it has to uniquely describe the object. The purpose, of course, is to make a meaningful and unique name for the benefit of the discovering client. The <author> element shall be the name of the operator or process that last changed the object, if known. The <published> element shall be the time at which the object was created, if known. The <updated> element shall be the time the object was last modified, if known. If any of these is not known, then its value is a local matter. The <category> elements shall be populated from any semantic tags that are known to the server. The <link> elements shall be populated with any inter-object relationships that can be expressed by the server.


22

N.15.10 Interfaces

Interfaces are a means of grouping data in standard and discoverable ways. The abstract implementation of interfaces in the server is very similar between BACnet Application Interfaces implemented by BACnet Structured View objects and abstract interfaces instantiated only in the server. Interfaces are always modeled in the server as objects. Therefore, when representing interfaces as Atom entries, the promotion rules for Representing Objects in Clause N.15.9 apply. Since all interfaces are modeled as objects, they will all be present in the /.sysinfo/all-objects feed. Interface objects are also present in dedicated feed /.sysinfo/all-interfaces.

N.15.10.1 Representing BACnet Application Interfaces

When representing BACnet Application Interfaces implemented by BACnet Structured View objects, the following rules apply. All the standard BACnet properties present in the Structured View shall all be present as child nodes using their canonical names. This allows clients to query for interfaces based on the "interface-name" property and to access the members using the "subordinates-list" property.

N.15.10.2 Representing Non-BACnet Interfaces

When representing interfaces that are not also represented by a BACnet Structured View object, the following rules apply. To simplify interactions for the client, the following child nodes are required to be present and are required to be in the same format as their BACnet counterparts: "object-name", "interface-name", and "subordinates-list". Other BACnet properties may be emulated as well, but the required set above allows clients to find interfaces and use their references in the same manner. If the interface has proprietary extensions beyond what is represented by "interface-name", it shall use the child node "extended-subordinates-list", and optionally, the "extended-subordinates-annotations" and "extended-interface-name" nodes in the same manner and format as their BACnet counterparts.

N.15.10.3 Traversing Interfaces

Interfaces are structured as an array of references to subordinates. Consulting the definition of the interface gives the client information about the meaning of the subordinates and their ordinal position in the subordinates list. Often, interface subordinates are interfaces themselves, so traversal could be a multistep process. To allow efficient traversal of the indirections created by using interfaces, the ".target" child can be used to skip through one or more indirections in one request. See Clause N.15.11. For example, if the client knows that it wants the value of the third subordinate of the second subordinate of the interface at /foo, it can use /foo/subordinate_list/2/.target/subordinate-list/3/.target:Value to get the results in one request.


23

N.15.11 Indirection

To efficiently traverse nodes that are references or pointers, the ".target" child is defined to be the node referred to by another node when that node is a reference of some kind. The ".target" child is fully resolved to be the target node. Therefore, all the attributes and children of ".target" are equal to those of the target node. When the reference node is representing BACnet data, all of the target inference rules defined for the ReadPropertyIndirect service apply. [Reviewer note: ReadPropertyIndirect is contained in a separate proposal.] For example, if the node at /foo/bar is a representation of a BACnetReference, then /foo/bar/.target is the node that the fields of the BACnetReference are referring to. When the reference node is representing non-BACnet data, then the value of the node is a URL to the target node. If the URL is relative, the base for the URL is the reference node. For example, if the node at /foo/bar is a string containing the absolute path "/blat/blah", then the path /foo/bar/.target is equivalent to the path /blat/blah. If it contains the relative path "../blat/blah" instead, then the path /foo/bar/.target is equivalent to the path /foo/blat/blah.


24

N.15.12 Standard feeds

Several standard feeds are defined for use by clients without prior knowledge of the server data arrangement.

N.15.12.1 Feed /.sysinfo/all-objects

This is an Atom feed of all objects in the server, that is, all Nodes that are represented as CSML <Object> elements. This includes BACnet and non-BACnet objects. Each object is represented as an Atom entry. Since this feed might be very large, the client may wish to use the 'filter' and/or 'max-results' query parameters to control the response. Each Atom entry contains a single <Object>; however, to keep the listing small, the content shall be deferred (not inline). This means that the <content> element shall use the 'src' attribute to point to the location of the object, and that the client must dereference that 'src' to get to the contents of the object. See Example N.15.19.16. Note, however, that filtering is done on the object itself, not the resultant XML. Therefore, filter expressions that descend into the object's children function as expected are not affected by the fact that the children are not returned in the feed.

N.15.12.2 Feed /.sysinfo/all-interfaces

This is an Atom feed of all interfaces in the server. Interfaces are modeled as objects and have a required "interface-name" child node that can be queried to find interfaces of a particular kind. This includes BACnet and non-BACnet interfaces. Since interfaces are also objects, all the rules for /.sysinfo/all-objects also apply to this feed.

N.15.12.3 Feed .../.value-history

A child named ".value-history" shall appear under any node that has associated value history (trends records) in the server. It is a feed that contains the time series data for the value of that Node. This may be data originating from a BACnet Trend Log or BACnet Trend Log Multiple objects, or from a non-BACnet source. See Clause N.15.3 for formatting information.

N.15.12.4 Feed .../.value-changes

A child named ".value-changes" can appear on any node that supports COV subscriptions. It is a feed that contains a single entry for the timestamp of the last change of value for that node. This feed only contains one entry. The purpose of this is to allow subscriptions for COV notifications. To prevent unnecessary overhead, the server is not required to make this node available unless it has an active subscription for it. That means that attempts to read the ".value-changes" child may result in an error, but a client may nonetheless gain a successful subscription to it.

N.15.12.5 Feed .../.event-history

A child named ".event-history" can appear on any Node. It is a feed that contains the time series data for the events reported by that Node. This may or may not be data originating from a BACnet Event Log object. See Clause N.15.3 for formatting information.


25

N.15.13 Working with Optional Data

Many BACnet data structures contain optional fields, and most BACnet objects contain optional properties. The methods for dealing with optional data are detailed in this clause. When performing a GET, PUT, or POST operation that addresses the parent of a missing item, the missing item is simply not present in the XML representation of the parent structure, just as it would be absent when using ASN.1-based services. When performing a GET operation that directly addresses a missing item, an HTTP 404 response is returned. When performing a PUT operation that directly addresses a missing item, the new value is assigned to the item and the item is thus no longer missing. When performing a DELETE operation that directly addresses an optional item: if that item is present, it shall be removed, and the server shall return an HTTP status code of 204 No Content. The POST operation shall not be used to assign values to missing items. See example N.15.19.17.


26

N.15.14 Creating Data

If the server allows it, new members of the collection types <List>, <SequenceOf>, and <Array> shall be creatable by POSTing a fully formed CSML element to the path of the collection. When POSTing to an <Array>, the newly created resource is always added to the end of the array, increasing the size of the array by one. The default representation format (Atom wrapper) shall be used if the client is providing information for <author>, <title>, <subtitle>, <category>, <link>, etc. If the client is providing none of that information, the alt=direct representation may be used. The client may optionally provide a suggested name for the resource in the HTTP Slug header. Handling of that suggestion is a local matter; however, the servers must always ensure that the new resource is given a valid path identifier that is unique among its siblings. The server shall assign the <id> and return the location of the newly created resource in the HTTP Location header. Since the client does not directly control the path name of the created resource, the client shall note the returned Location header to know the URL of the created resource. Note that the server is not required to accept and retain all the Atom metadata provided by the client. The client can check the response to see if any has been removed or modified. See Clause N.15.17. See example N.15.19.18.

N.15.15 Setting Data

Data items that are returned in Atom entries, or directly using alt=direct, are set by simply reversing the flow and using a PUT to set the value in the same format as would be retrieved with a GET. This includes any localizing effect of the 'locale' query parameter. The server may do slight data modifications upon setting the new value and so always returns the resource as if the client had done a subsequent GET. This is standard practice for Atom Publishing Protocol and shall be used for the alt=direct formats as well. See example N.15.19.19.

N.15.16 Deleting Data

If the server allows it, members of the collection types <List>, <SequenceOf>, and <Array> may be deleted by a DELETE operation to the path of the member. How the server handles deleting members of an <Array> is a local matter with the exception that deleting a member of an array other than the end member shall not cause the array to be resized or any members to shift position. See example N.15.19.20.


27

N.15.17 Server Support for Atom Metadata

To allow for minimal implementations, a server is not required to support and retain all the Atom metadata provided to it by a client when creating or modifying data. Support for meaningful and persistent <id> is required. However, note that its format is a local matter and non-movable resources may be able to use parts of their path to make unique references on demand without incurring additional storage penalties. Support for <link> relation types "self", "edit", "next", and those relation types listed in Clause N.15.8 is required. Support for other relation types is a local matter. Required support for <published> and <updated> varies according to usage. Where clauses in this standard require a specific meaning of these for their proper operation (e.g., time series data in Clause N.15.3 requires <published>), then that becomes a requirement if the server supports that operation, else support for these, and the granularity thereof, is a local matter. Support for, and retention of, other Atom metadata, i.e., <author>, <category>, <contributor>, <generator>, <icon>, <logo>, <rights>, <source>, <subtitle>, <summary>, and <title> is a local matter and may vary based on context or usage.


28

N.15.18 Subscriptions

This standard defines a generalized method for clients to subscribe to a feed and receive push notifications when new items are updated in the feed. The subscription process and publication push mechanisms described here match the interactions defined by the PubSubHubbub protocol. The deployment models, however, are slightly different due to the different use scenarios. Here, the hub is built into the server rather than being an external device. As far as the client is concerned, there is no difference, but the publisher-hub interaction is simplified because it takes place in memory of the server. This allows the client to subscribe to any feed in the server (every trend, cov, or event source can be a feed) without prior coordination between the publisher and an external hub and allows the computation of deltas for push updates to be greatly simplified. Because the hub is built into the server/publisher, only the client interaction is described here, and the term "server" is used rather than "hub". All feeds that can be subscribed to shall have an Atom <link> element with rel="hub" and an href pointing to the server's hub endpoint URL. This is likely the same for all feeds in the server, so there is no additional storage requirement for this link. Subscribing to an Atom feed consists of three parts: requesting a subscription, confirming the subscription, and periodically reconfirming to keep it alive. Unsubscribing consists of two parts: requesting an unsubscription and confirming the unsubscription.

N.15.18.1 Subscriber Initiates Subscription Request

To request a subscription, the client shall make an HTTP POST to the hub endpoint URL that was obtained from the feed's rel="hub" link. This POST request shall have a Content-Type of application/x-www-form-urlencoded with the following parameters:

Parameter Name Optionality Contents hub.callback

Required The subscriber's callback URL where notifications should be delivered.

hub.mode

Required The literal string "subscribe" or "unsubscribe", depending on the goal of the request.

hub.topic

Required The topic URL (feed) that the subscriber wishes to subscribe to.

hub.verify

Required Keyword describing verification modes supported by this subscriber, as described below. This parameter may be repeated to indicate multiple supported modes.

hub.lease_seconds

Optional The number of seconds that the subscriber is requesting the subscription to remain active. If not present, or an empty value, the subscription shall remain active until automatic refreshing removes it. Support for this parameter is a local matter. If this parameter is present in an unsubscription request, it shall be ignored.

hub.secret

Optional A subscriber-provided secret string that will be used to compute an HMAC digest for authorized content distribution. If not supplied, the HMAC digest will not be present for content distribution requests. Because of the secret nature of this parameter, it is recommended that deployments use HTTPS (RFC 2818) when conveying this parameter. This parameter shall be less than 200 bytes in length.

hub.verify_token

Optional A subscriber-provided opaque token that will be echoed back in the verification request to assist the subscriber in identifying which subscription request is being verified. If this is not included, no token will be included in


29

the verification request.

The server shall ignore additional request parameters that it does not understand. The keywords defined for the hub.verify parameter are: "sync," meaning that the subscriber supports synchronous verification, where the verification request must occur before the subscription request's HTTP response is returned, and "async," meaning that the subscriber supports asynchronous verification, where the verification request may occur at a later point after the subscription request has returned. When keywords are repeated, their order indicates the subscriber's order of preference. Subscribers shall use at least one of "sync" or "async" but are also permitted to include additional keywords defined by extension specifications. The server shall ignore hub.verify keywords that they do not understand Servers shall allow subscribers to re-request subscriptions that are already activated. Each subsequent request to a server to subscribe or unsubscribe shall override the previous subscription state for a specific topic URL and callback URL combination once the action is verified. Any failures to confirm the subscription action shall leave the subscription state unchanged. This is required so subscribers can renew their subscriptions before the lease seconds period is over without any interruption. The topic and callback URLs shall not contain an anchor fragment. Both HTTP and HTTPS schemes shall be supported for both URLs. The server shall support the use of port numbers; however, servers are allowed to disallow certain ports based on their own policies (e.g., security) and return errors for those requests. The callback URL might contain arbitrary query string parameters (e.g., ?foo=bar&red=fish), so the server shall preserve the query string during subscription verification by appending new parameters to the end of the list using the & (ampersand) character to join. Existing parameters with names that overlap with those used by verification requests shall not be overwritten, and the server shall only append verification parameters to the existing list, if any. For event notification, the callback URL shall be POSTed to include any query-string parameters in the URL portion of the request, not as POST body parameters. The server shall respond to a subscription request with an HTTP 204 "No Content" response to indicate that the request was verified and that the subscription is active. If the subscription has yet to be verified (i.e., the hub is using asynchronous verification), the hub shall respond with a 202 "Accepted" code. If a server finds any errors in the subscription request, an appropriate HTTP error response code (4xx or 5xx) shall be returned. In the event of an error, it is recommended that servers return a description of the error in the response body as plain text. The decision as to which feeds are available for subscription and which will be rejected is a local matter. In synchronous mode, the verification shall be completed before the server returns a response. In asynchronous mode, the verification is allowed to be deferred until a later time.

N.15.18.2 Server Verifies the Intent of the Subscriber

In order to prevent an attacker from creating unwanted subscriptions on behalf of a subscriber (or unsubscribing desired ones), a server must ensure that the subscriber did indeed send the subscription request. This verification between the server and the subscriber does not preclude subscriptions being set up by a third device on behalf of a final subscriber; however, it does require some coordination between the final subscriber and the third device because the third device initiates the subscription request to the server, but the verification message is sent to the final subscriber. If the third device and the final recipient agree on a scheme for the hub.verify_token, then the final subscriber can approve the verification message because it is confident that the subscription was initiated by a trusted third device. The server verifies a subscription request by sending an HTTP GET request to the subscriber's callback URL as given in the subscription request. This request has the following query string parameters appended to the URL:


30

Parameter Name Optionality Contents hub.mode

Required The literal string "subscribe" or "unsubscribe", which matches the original request to the hub from the subscriber.

hub.topic

Required The topic URL given in the corresponding subscription request.

hub.challenge

Required A server-generated, random string that MUST be echoed by the subscriber to verify the subscription

hub.lease_seconds

Required for subscriptions

The server-determined number of seconds that the subscription will stay active before expiring, measured from the time the verification request was made from the hub to the subscriber. Servers shall supply this parameter for subscription requests. If present for unsubscriptions, the subscriber shall ignore it.

hub.verify_token

Optional The opaque token from the corresponding subscription request, if one was provided.

The subscriber shall confirm that the hub.topic and hub.verify_token correspond to a pending subscription or unsubscription that it wishes to carry out. If so, the subscriber shall respond with an HTTP success (2xx) code with a response body equal to the hub.challenge parameter. If the subscriber does not agree with the action, the subscriber shall respond with a 404 "Not Found" response. For synchronous verification, the server shall consider other server response codes (3xx, 4xx, 5xx) to mean that the verification request has immediately failed and no retries should occur. If the subscriber returns an HTTP success (2xx) but the content body does not match the hub.challenge parameter, the server shall also consider verification to have failed. For asynchronous verification, the server shall consider other subscriber response codes (3xx, 4xx, and 5xx) to mean that the subscription action was temporarily not verified. If the subscriber returns an HTTP success (2xx) but the content body does not match the hub.challenge parameter, the server shall consider this to be a temporary failure and retry. The hub shall retry verification a reasonable number of times over the course of a longer time period (e.g., 6 hours) until a definite acknowledgement (positive or negative) is received. If a definite response still cannot be determined after this retry period, the subscription action verification shall be abandoned, leaving the previous subscription state. Servers shall select a value for the hub.lease_seconds that is either equal to the period the subscriber passed in its subscription request, or a value chosen based on the server's policies. To sustain a non-permanent subscription, the subscriber shall re-request the subscription on the server before hub.lease_seconds has elapsed. For permanent subscriptions with no hub.lease_seconds value specified, the behavior is different as described in the section on automatic subscription refreshing.

N.15.18.3 Automatic Subscription Refreshing

Before a subscription expires (i.e., before hub.lease_seconds elapses), servers shall recheck with subscribers to see if a continued subscription is desired. Servers do this by sending the subscriber a verification request with hub.mode equal to "subscribe". This request shall match the original verification request sent to the subscriber (but with a new hub.challenge). The response codes returned by the subscriber shall be interpreted the same way as during a subscriber-initiated verification flow. However, this refresh request shall behave like an initial subscription request; this means that if an auto-refresh response from the subscriber constantly returns an error, the server shall give up on the subscription verification action altogether and remove the subscription. In the case of permanent subscriptions (with no hub.lease_seconds specified in the original request), the hub.lease_seconds value supplied by the server in the verification request to the subscriber can be used to represent


31

how many seconds until the server expects it will next initiate automatic subscription refreshing to ensure that the subscriber is still interested in the topic. This behavior provides the best of both worlds: maximum simplicity of the subscriber through infinitely-long subscriptions, but still garbage collectable subscriptions for the server's benefit.

N.15.18.4 Distribution

A content distribution request is an HTTP POST request from the server to the subscriber's callback URL with the list of new and changed entries. This request shall have a Content-Type of application/atom+xml and shall contain an Atom feed containing the new or changed entries. If the document represents a single feed being replicated for the subscriber, then it is recommended that the feed-level Atom elements be preserved aside from the Atom <entry> elements. All Atom <id> elements shall be reproduced exactly. It is also recommended that the Atom <updated> and Atom <title> elements be present. Each Atom <entry> element in the feed contains the content from an entry in the single topic that the subscriber has an active subscription for. Essentially, in the single feed case, the subscriber will receive a feed document that looks like the original but with old content removed. The successful response from the subscriber's callback URL shall be an HTTP success (2xx) code. The server shall consider all other subscriber response codes as failures; that means subscribers shall not use HTTP redirects for moving subscriptions. The response body from the subscriber shall be ignored by the server. It is recommended that servers retry notifications repeatedly until successful (up to some reasonable maximum over a reasonable time period) and that subscribers respond to notifications as quickly as possible; however, subscriber success response code only indicates receipt of the message, not acknowledgment that it was successfully processed by the subscriber.


32

N.15.19 Examples

Note: these examples are written for human understanding purposes. In most cases, they are not the literal character-for-character exchanges. In all of these examples, the "HTTP/1.1" is left off of requests and responses, most HTTP headers are not shown, many Atom elements are not shown, and all URLs are left unencoded. This concession for readability is not to be taken as a requirement of this specification. All operations shall conform to relevant standards.

N.15.19.1 Getting a Scalar Attribute in the Default Representation (Atom)

GET /path/to/primitive-node:Value 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <content>75.0</content> </entry>

N.15.19.2 Getting an Array Attribute in the Default Representation (Atom)

GET /path/to/list-node:Children 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <content>building-1;building-2;central-plant<content> </entry>

N.15.19.3 Getting a Scalar Attribute with Alternate Representation alt=direct

GET /path/to/primitive-node:Value?alt=direct 200 OK Content-Type: text/plain 75.0

N.15.19.4 Getting an Array Attribute with Alternate Representation alt=direct

GET /path/to/list-node:Children?alt=direct 200 OK Content-Type: text/plain building-1;building-2;central-plant

N.15.19.5 Getting a Localized Value

The client asks for the Value attribute specifying formatting and localization query parameters.


33

GET /foo/bar/usage:Value?alt=direct&locale=de_DE&precision=2 200 OK Content-Type: text/plain 7 500,00

N.15.19.6 Getting a Primitive Node in the Default Representation (Atom)

GET /path/to/primitive-node 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> ... <content type=”application/xml”> <Real name="primitive-node" value="75.0" xmlns="http://bacnet.org/csml/1"/> </content> </entry>

N.15.19.7 Getting a Constructed Node in the Default Representation (Atom)

GET /path/to/array-node 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> ... <content type=”application/xml”> <Array name="array-node" xmlns="http://bacnet.org/csml/1"/> <Real name="1" value="75.0"/> <Real name="2" value="73.5"/> <Real name="3" value="77.5"/> </Array> </content> </entry>

N.15.19.8 Getting a Primitive Node in the Alternate Representation alt=direct

GET /path/to/primitive-node 200 OK Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <Real name="primitive-node" value="75.0" xmlns="http://bacnet.org/csml/1"/>


34

N.15.19.9 Getting a Constructed Node in the Alternate Representation alt=direct

GET /path/to/array-node 200 OK Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <Array name="array-node" xmlns="http://bacnet.org/csml/1"/> <Real name="1" value="75.0"/> <Real name="2" value="73.5"/> <Real name="3" value="77.5"/> </Array>

N.15.19.10 Getting a Constructed Node in the Alternative Representation alt=feed

In this example, consider an array, which, when read in its default form, would look like this: GET /path/to/array-node 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> ... <content type=”application/xml”> <Array name="array-node" xmlns="http://bacnet.org/csml/1"/> <Real name="1" value="75.0"/> <Real name="2" value="73.5"/> <Real name="3" value="77.5"/> ... many more ... </Array> </content> </entry> However, in this example, the client cannot read the entire contents of an array at once, so it changes the representation to a feed and limits the size of the response using the max-results. Because only some of the entries are returned, the server provides a "next" link (per the Atom specification) for the client to be able to chain to the rest of the members. GET /path/to/array-node?alt=feed&max-results=2 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <feed xmlns="http://www.w3.org/2005/Atom"> <link rel="next" href="http://server/path/to/array-node?alt=feed&max-results=2&start-index=3"/> <entry> <content> <Real name="1" value="75.0" xmlns="http://bacnet.org/csml/1"/>


35

</content> </entry> <entry> <content> <Real name="2" value="73.5" xmlns="http://bacnet.org/csml/1"/> </content> </entry> </feed>

N.15.19.11 Getting Time Series Records from a BACnet Trend Log

The following example shows all three formats possible for the three cases: sample value, sample value with status flags, other log record type. GET /path/to/primitive-node/.value-history &published-min=2009-12-03T08:38:00Z &published-max=2009-12-03T08:41:00Z 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <feed xmlns="http://www.w3.org/2005/Atom"> <entry> <published>2009-12-03T08:38:00Z</published> <content>75.0</content> </entry> <entry> <published>2009-12-03T08:39:00Z</published> <content>76.0;fault</content> </entry> <entry> <published>2009-12-03T08:40:00Z</published> <content type="application/xml"> <Sequence type="0-BACnetLogRecord" xmlns="http://bacnet.org/csml/1"> <DateTime name="timestamp" value="2009-12-03T08:40:00Z"/> <Choice name="logDatum"> <Real name=timeChange" value="20.0"/> </Choice> <BitString name="statusFlags" value="fault"/> </content> </entry> </feed>

N.15.19.12 Getting Time Series Records From a BACnet Trend Log Multiple

The following example shows both formats possible for the two cases: sample values, other log record type. GET /path/to/primitive-node/.value-history &published-min=2009-12-03T08:38:00Z &published-max=2009-12-03T08:41:00Z 200 OK


36

Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <feed xmlns="http://www.w3.org/2005/Atom"> <entry> <published>2009-12-03T08:38:00Z</published> <content>75.0;99.4</content> </entry> <entry> <published>2009-12-03T08:39:00Z</published> <content>76.0;99.5</content> </entry> <entry> <published>2009-12-03T08:40:00Z</published> <content type="application/xml"> <Sequence type="0-BACnetLogMultipleRecord" xmlns="http://bacnet.org/csml/1"> <DateTime name="timestamp" value="2009-12-03T08:40:00Z"/> <Choice name="logData"> <Sequence-Of name="log-data"> <Choice name="1"> <Real name="real-value" value="76.0"/> </Choice> <Choice name="2"> <Sequence name="failure"> <Enumerated name="error-class" value="communication"/> <Enumerated name="error-code" value="timeout"/> </Sequence> </Choice> </Sequence-Of> </Choice> </content> </entry> </feed>

N.15.19.13 Getting Foreign XML in the Default Representation (Atom)

GET /path/to/foreign-xml 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <content> <MeterReadings xmlns="http://naesb.org/eui_example/1"> <name>...</name> <IntervalReadings>...</IntervalReadings> <Readings>...</Readings> <ReadingType>...</ReadingType> <valuesInterval>...</valuesInterval> </MeterReadings> <content> </entry>


37

N.15.19.14 Getting Foreign XML in the Alternative Representation alt=direct

GET /path/to/foreign-xml?alt=direct

200 OK Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <MeterReadings xmlns="http://naesb.org/eui_example/1"> <name>...</name> <IntervalReadings>...</IntervalReadings> <Readings>...</Readings> <ReadingType>...</ReadingType> <valuesInterval>...</valuesInterval> </MeterReadings>

N.15.19.15 Getting CMSL Metadata with the 'csmlmetadata' Parameter

Without the 'csmlmetadata' query parameter, the server would return only 'name' and 'value' for the following: GET /path/to/great-thing?alt=direct 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <Sequence name="great-thing" xmlns="http://bacnet.org/csml/1"/> <Real name="foo" value="75.0"/> <Array name="bar"> <Real name="1" value="123.0"/> <Real name="2" value="456.0"/> </Array> <Enumerated name="baz" value="medium"/> </Array> Setting the 'csmlmetadata' parameter to "types" causes the server to return all the type data it knows. GET /path/to/array-node?alt=direct&csmlmetadata=types 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <Sequence name="great-thing" type="555-GreatType" xmlns="http://bacnet.org/csml/1"/> <Real name="foo" value="75.0" /> <Array name="bar" memberType="Real"> <Real name="1" value="123.0"/> <Real name="2" value="456.0"/> </Array> <Enumerated name="baz" value="medium" type="555-EnumLMH"> </Array>


38

Setting the 'csmlmetadata' parameter to "all" causes the server to return all the metadata it knows (only a subset of possible metadata is shown here for brevity). GET /path/to/array-node?alt=direct&csmlmetadata=all 200 OK Content-Type: application/atom+xml <Sequence name="great-thing" displayName="A Really Great Thing" type="555-GreatType" description="blah blah blah" writable="true" writeEffective="immediately" volatility="nonvolatile" xmlns="http://bacnet.org/csml/1"/> <Real name="foo" value="75.0" displayName="Foo, James Foo" maximum="96.0" Minimum="45.0" units="watts-per-square-meter-degree-kelvin"> <Documentation>Some words to show that even "primitives" can have children.</Documentation> </Real> <Array name="bar" memberType="Real" minimumSize="1" maximumSize="20"> <Real name="1" value="23.0" minimum="0.0" maximum="100.0"/> <Real name="2" value="56.0" minimum="0.0" maximum="100.0"/> </Array> <Enumerated name="baz" value="medium" type="555-EnumLMH"> <NamedValues> <Unsigned name="low" value="1"> <Unsigned name="medium" value="2"> <Unsigned name="high" value="3"> </NamedValues> </Enumerated> </Array>

N.15.19.16 Getting a Filtered List of Objects

The /.sysinfo/all-objects feed contains all objects known to the server; therefore, filter is usually applied during discovery. Note that the entries returned are not fully included. They use the 'src' to point to the location of the object. GET /.sysinfo/all-objects?filter=category[@term="meter" and @scheme='example.org/cats'] 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <feed xmlns="http://www.w3.org/2005/Atom"> <entry> <title>East Campus, Building 41, Meter</title> <content type="application/xml" src="/east-campus/bldg41/emeter"/> </entry> <entry> <title>West Campus, Building 12, Meter</title> <content type="application/xml" src="//west-campus/bldg12/emeter"/> </entry> </feed> The client would then follow the 'src' link to get to the object.


39

GET /east-campus/bldg41/emeter 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <title>East Campus, Building 41, Meter</title> <content type="application/xml"> <Object name="emeter" xmlns="http://bacnet.org/csml/1"> <Unsigned name="Object_Type" value="structured-view"/> .... </Object> </content> </entry>

N.15.19.17 Working with Optional Data

When the parent of an optional item is addressed, the missing fields (here, "deviceIdentifier") are simply missing from the XML. GET /path/to/some-address?alt=direct 200 OK Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <Sequence name="some-address" xmlns="http://bacnet.org/csml/1"/> <ObjectIdentifier name="objectIdentifier" value="analog-input,1"/> </Sequence> When the missing item is addressed directly, an error is generated. GET /path/to/some-address/deviceIdentifier 404 Not Found When the missing item is addressed directly with a PUT, the new value is set and shall appear in subsequent GETs. PUT /path/to/some-address/deviceIdentifier@value&alt=direct Content-Type: text/plain device,1234 200 OK Content-Type: text/plain device,1234 When read back, the parent now shows the new value. GET /path/to/some-address?alt=direct


40

200 OK Content-Type: application/xml <?xml version='1.0' encoding='utf-8'?> <Sequence name="some-address" xmlns="http://bacnet.org/csml/1"/> <ObjectIdentifier name="objectIdentifier" value="analog-input,1"/> <ObjectIdentifier name="deviceIdentifier" value="device,1234"/> </Sequence>

N.15.19.18 Creating Data

New resources are added to collection with a POST operation. Note that not all Atom metadata is retained for this object and that the resource name suggested in the Slug: header was modified to fit the server's naming rules. POST /foo/biglist Content-Type: application/atom+xml Slug: EC:b41/meter <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom" > <author><name>Workstation3:Larry</name></author> <title>East Campus, Building 41 Meter"</title> <subtitle>MeterCo model FS342</subtitle> <category term="meter" scheme="http://example.org/cats"/> <content> <Object " xmlns="http://bacnet.org/csml/1"/> ... </Object> </content> </entry> 201 CREATED Content-Type: application/atom+xml Location: http://server/foo/biglist/EC_b41_meter <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom" > <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a'<id> <title>East Campus, Building 41 Meter"</title> <category term="meter" scheme="http://example.org/cats"/> <content> <Object name="EC_b41_meter" xmlns="http://bacnet.org/csml/1"/> ... </Object> </content> </entry>

N.15.19.19 Putting a Scalar Attribute in the Default Representation (Atom)

This example also shows data coercion by the server that is made evident in the returned data. PUT /path/to/primitive-node:Value


41

Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <content>77.000000000000001</content> </entry> 200 OK Content-Type: application/atom+xml <?xml version='1.0' encoding='utf-8'?> <entry xmlns="http://www.w3.org/2005/Atom"> <content>77.0</content> </entry>

N.15.19.20 Deleting Data

Data in collections and optional data items are removed by directly addressing the resource with a DELETE operation. Removing a previously created list member: DELETE /foo/biglist/EC_b41_meter 204 NO CONTENT

Removing an optional data field: DELETE /foo/some-address/deviceIdentifier 204 NO CONTENT

Documents

BSR/ASHRAE Addendum to ANSI/ASHRAE Standard 135-2010 ... · BSR/ASHRAE Addendum am to ANSI/ASHRAE Standard 135-2010 Advisory Public Review Draft _____ ASHRAE Standard Proposed Addendum