Confirmed Service

Confirmed BACnet services can be called directly from the REST API by constructing a message in JSON and posting it to the REST API. The API will convert the JSON text into a BACnet message and send it to the BACnet device using the BACnet protocol. When a confirmed message is sent the REST API will wait until the device responds or a timeout occurs before sending the response back in JSON format.

In some systems a device may need to know that an operator has seen the alarm notification. The AcknowledgeAlarm service is used by a notification-client to acknowledge that a human operator has seen and responded to an event notification with 'AckRequired' = TRUE. Ensuring that the acknowledgment actually comes from a person with appropriate authority is a local matter. This service may be used in conjunction with either the ConfirmedEventNotification service or the UnconfirmedEventNotification service.

post

Executes a BACnet acknowledgeAlarm service and waits for a reply or timeout from the device.

The specification of this service is retained for historical reference so that implementations of client devices have guidance on how to interoperate with older server devices. Otherwise, it is deprecated. The GetAlarmSummary service is used by a client BACnet-user to obtain a summary of "active alarms." The term "active alarm" refers to BACnet standard objects that have an Event_State property whose value is not equal to NORMAL and a Notify_Type property whose value is ALARM.

post

Executes a BACnet getAlarmSummary service and waits for a reply or timeout from the device.

The specification of this service is retained for historical reference so that implementations of client devices have guidance on how to interoperate with older server devices. Otherwise, it is deprecated. The GetEnrollmentSummary service is used by a client BACnet-user to obtain a summary of event-initiating objects. Several different filters may be applied to define the search criteria.

post

Executes a BACnet getEnrolmentSummary service and waits for a reply or timeout from the device.

The SubscribeCOV service is used by a COV-client to subscribe for the receipt of notifications of changes that may occur to the properties of a particular object. Certain BACnet standard objects may optionally support COV reporting. If a standard object provides COV reporting, then changes of value of specific properties of the object, in some cases based on programmable increments, trigger COV notifications to be sent to one or more subscriber clients. Typically, COV notifications are sent to supervisory programs in BACnet client devices or to operators or logging devices. Proprietary objects may support COV reporting at the implementor's option. The subscription establishes a connection between the change of value detection and reporting mechanism within the COVserver device and a "process" within the COV-client device. Notifications of changes are issued by the COV-server device when changes occur after the subscription has been established. The ConfirmedCOVNotification and UnconfirmedCOVNotification services are used by the COV-server device to convey change notifications. The choice of confirmed or unconfirmed service is made at the time the subscription is established.

post

Executes a BACnet subscribeCov service and waits for a reply or timeout from the device.

The AtomicReadFile Service is used by a client BACnet-user to perform an open-read-close operation on the contents of the specified file. The file may be accessed as records or as a stream of octets.

post

Executes a BACnet atomicReadFile service and waits for a reply or timeout from the device.

The AtomicWriteFile Service is used by a client BACnet-user to perform an open-write-close operation of an OCTET STRING into a specified position or a list of OCTET STRINGs into a specified group of records in a file. The file may be accessed as records or as a stream of octets.

post

Executes a BACnet atomicWriteFile service and waits for a reply or timeout from the device.

The AddListElement service is used by a client BACnet-user to add one or more list elements to an object property that is a list.

post

Executes a BACnet addListElement service and waits for a reply or timeout from the device.

The RemoveListElement service is used by a client BACnet-user to remove one or more elements from the property of an object that is a list. If an element is itself a list, the entire element shall be removed. This service does not operate on nested lists.

post

Executes a BACnet removeListElement service and waits for a reply or timeout from the device.

The CreateObject service is used by a client BACnet-user to create a new instance of an object. This service may be used to create instances of both standard and vendor specific objects. The standard object types supported by this service shall be specified in the PICS. The properties of standard objects created with this service may be initialized in two ways: initial values may be provided as part of the CreateObject service request or values may be written to the newly created object using the BACnet WriteProperty services. The initialization of non-standard objects is a local matter. The behavior of objects created by this service that are not supplied, or only partially supplied, with initial property values is dependent upon the device and is a local matter.

post

Executes a BACnet createObject service and waits for a reply or timeout from the device.

The DeleteObject service is used by a client BACnet-user to delete an existing object. Although this service is general in the sense that it can be applied to any object type, it is expected that most objects in a control system cannot be deleted by this service because they are protected as a security feature. There are some objects, however, that may be created and deleted dynamically. Group objects and Event Enrollment objects are examples. This service is primarily used to delete objects of these types but may also be used to remove vendor-specific deletable objects.

post

Executes a BACnet deleteObject service and waits for a reply or timeout from the device.

The ReadProperty service is used by a client BACnet-user to request the value of one property of one BACnet Object. This service allows read access to any property of any object, whether a BACnet-defined object or not.

post

Executes a BACnet readProperty service and waits for a reply or timeout from the device.

The ReadPropertyMultiple service is used by a client BACnet-user to request the values of one or more specified properties of one or more BACnet Objects. This service allows read access to any property of any object, whether a BACnet-defined object or not. The user may read a single property of a single object, a list of properties of a single object, or any number of properties of any number of objects. A 'Read Access Specification' with the property identifier ALL can be used to learn the implemented properties of an object along with their values.

post

Executes a BACnet readPropertyMultiple service and waits for a reply or timeout from the device.

The WriteProperty service is used by a client BACnet-user to modify the value of a single specified property of a BACnet object. This service potentially allows write access to any property of any object, whether a BACnet-defined object or not. Some implementors may wish to restrict write access to certain properties of certain objects. In such cases, an attempt to modify a restricted property shall result in the return of an error of 'Error Class' PROPERTY and 'Error Code' WRITE_ACCESS_DENIED. Note that these restricted properties may be accessible through the use of Virtual Terminal services or other means at the discretion of the implementor.

post

Executes a BACnet writeProperty service and waits for a reply or timeout from the device.

The WritePropertyMultiple service is used by a client BACnet-user to modify the value of one or more specified properties of a BACnet object. This service potentially allows write access to any property of any object, whether a BACnet-defined object or not. Properties shall be modified by the WritePropertyMultiple service in the order specified in the 'List of Write Access Specifications' parameter, and execution of the service shall continue until all of the specified properties have been written to or a property is encountered that for some reason cannot be modified as requested. Some implementors may wish to restrict write access to certain properties of certain objects. In such cases, an attempt to modify a restricted property shall result in the return of an error of 'Error Class' PROPERTY and 'Error Code' WRITE_ACCESS_DENIED. Note that these restricted properties may be accessible through the use of Virtual Terminal services or other means at the discretion of the implementor.

post

Executes a BACnet writePropertyMultiple service and waits for a reply or timeout from the device.

The DeviceCommunicationControl service is used by a client BACnet-user to instruct a remote device to stop initiating and optionally stop responding to all APDUs (except DeviceCommunicationControl or, if supported, ReinitializeDevice) on the communication network or internetwork for a specified duration of time. This service is primarily used by a human operator for diagnostic purposes. A password may be required from the client BACnet-user prior to executing the service. The time duration can be set to "indefinite," meaning communication must be re-enabled by a DeviceCommunicationControl or, if supported, ReinitializeDevice service, not by time.

post

Executes a BACnet deviceCommunicationControl service and waits for a reply or timeout from the device.

The ConfirmedPrivateTransfer is used by a client BACnet-user to invoke proprietary or non-standard services in a remote device. The specific proprietary services that may be provided by a given device are not defined by this standard. The PrivateTransfer services provide a mechanism for specifying a particular proprietary service in a standardized manner. The only required parameters for these services are a vendor identification code and a service number. Additional parameters may be supplied for each service if required. The form and content of these additional parameters, if any, are not defined by this standard. The vendor identification code and service number together serve to unambiguously identify the intended purpose of the information conveyed by the remainder of the APDU or the service to be performed by the remote device based on parameters in the remainder of the APDU. The vendor identification code is a unique code assigned to the vendor by ASHRAE. The mechanism for administering these codes is not defined in this standard. See Clause 23.

post

Executes a BACnet confirmedPrivateTransfer service and waits for a reply or timeout from the device.

The ConfirmedTextMessage service is used by a client BACnet-user to send a text message to another BACnet device. This service is not a broadcast or multicast service. This service may be used in cases when confirmation that the text message was received is required. The confirmation does not guarantee that a human operator has seen the message. Messages may be prioritized into normal or urgent categories. In addition, a given text message may be optionally classified by a numeric class code or class identification string. This classification may be used by the receiving BACnet device to determine how to handle the text message. For example, the message class might indicate a particular output device on which to print text or a set of actions to take when the text is received. In any case, the interpretation of the class is a local matter.

post

Executes a BACnet confirmedTextMessage service and waits for a reply or timeout from the device.

The ReinitializeDevice service is used by a client BACnet-user to instruct a remote device to reboot itself (cold start), reset itself to some predefined initial state (warm start), to activate network port object changes, or to control the backup or restore procedure. Resetting or rebooting a device is primarily initiated by a human operator for diagnostic purposes. Use of this service during the backup or restore procedure is usually initiated on behalf of the user by the device controlling the backup or restore. Due to the sensitive nature of this service, a password may be required by the responding BACnet-user prior to executing the service. A BACnet device may support the ReinitializeDevice service by supporting only the restart choices COLDSTART and WARMSTART. Support for the backup and restore features of this service is claimed separately. If the device supports a Network Port Object using the pending changes functionality, then the restart choice ACTIVATE_CHANGES shall also be supported.

post

Executes a BACnet reinitializeDevice service and waits for a reply or timeout from the device.

The ReadRange service is used by a client BACnet-user to read a specific range of data items representing a subset of data available within a specified object property. The service may be used with any list or array of lists property.

post

Executes a BACnet readRange service and waits for a reply or timeout from the device.

The LifeSafetyOperation service is intended for use in fire, life safety and security systems to provide a mechanism for conveying specific instructions from a human operator to accomplish any of the following objectives:

  • silence audible or visual notification appliances,
  • reset latched notification appliances, or
  • unsilence previously silenced audible or visual notification appliances. Ensuring that the LifeSafetyOperation request actually comes from a person with appropriate authority is a local matter.
post

Executes a BACnet lifeSafetyOperation service and waits for a reply or timeout from the device.

The SubscribeCOVProperty service is used by a COV-client to subscribe for the receipt of notifications of changes that may occur to the properties of a particular object. Any object may optionally support COV reporting. If a standard object provides COV reporting, then changes of value of subscribed-to properties of the object, in some cases based on programmable increments, trigger COV notifications to be sent to one or more subscriber clients. Typically, COV notifications are sent to supervisory programs in BACnet client devices or to operators or logging devices. The subscription establishes a connection between the change of value detection and reporting mechanism within the COVserver device and a "process" within the COV-client device. Notifications of changes are issued by the COV-server device when changes occur after the subscription has been established. The ConfirmedCOVNotification and UnconfirmedCOVNotification services are used by the COV-server device to convey change notifications. The choice of confirmed or unconfirmed service is made at the time the subscription is established. Any object, proprietary or standard, may support COV reporting for any property at the implementor's option.

post

Executes a BACnet subscribeCovProperty service and waits for a reply or timeout from the device.

The GetEventInformation service is used by a client BACnet-user to obtain a summary of all "active event states". The term "active event states" refers to all event-initiating objects that

  • have an Event_State property whose value is not equal to NORMAL, or
  • have an Acked_Transitions property, which has at least one of the bits (TO_OFFNORMAL, TO_FAULT, TO_NORMAL) set to FALSE.

This service is intended to be implemented in all devices that generate event notifications.

post

Executes a BACnet getEventInformation service and waits for a reply or timeout from the device.

The SubscribeCOVPropertyMultiple service is used by a COV-client to subscribe for the receipt of notifications of changes that may occur to multiple properties of multiple objects. Any object may optionally support COV reporting. If an object provides COV reporting, then changes of value of subscribed-to properties of the object, in some cases based on programmable increments, trigger COV notifications to be sent to one or more subscriber clients. Typically, COV notifications are sent to supervisory programs in BACnet client devices or to operators or logging devices.

The subscription establishes a connection between the change of value detection and reporting mechanism within the COVserver device and a "process" within the COV-client device. Notifications of changes are issued by the COV-server device when changes occur after the subscription has been established. The ConfirmedCOVNotificationMultiple and UnconfirmedCOVNotificationMultiple services are used by the COV-server device to convey change notifications. The choice of confirmed or unconfirmed service is made by the COV-client at the time the subscription is established.

The SubscribeCOVPropertyMultiple service differs from the SubscribeCOVProperty service in that the former allows multiple properties to be monitored via a single subscription request. For establishing or cancelling subscriptions, the effect of the SubscribeCOVPropertyMultiple service is similar to a series of independent SubscribeCOVProperty requests, one difference being that subscription via SubscribeCOVPropertyMultiple results in the use of the ConfirmedCOVNotificationMultiple and UnconfirmedCOVNotificationMultiple services to convey COV notifications of only those properties whose values changed.

The SubscribeCOVPropertyMultiple service also supports requests for timestamped data, for situations where the client requires the time associated with the value change.

post

Executes a BACnet subscribeCovPropertyMultiple service and waits for a reply or timeout from the device.

Unconfirmed Service

Unconfirmed BACnet services can be called directly from the REST API by constructing a message in JSON and posting it to the REST API. The API will convert the JSON text into a BACnet message and send it to the BACnet device using the BACnet protocol. When an unconfirmed message is sent, the REST API will return immediately without waiting for a response.

The UnconfirmedPrivateTransfer is used by a client BACnet-user to invoke proprietary or non-standard services in a remote device. The specific proprietary services that may be provided by a given device are not defined by this standard. The PrivateTransfer services provide a mechanism for specifying a particular proprietary service in a standardized manner. The only required parameters for these services are a vendor identification code and a service number. Additional parameters may be supplied for each service if required. The form and content of these additional parameters, if any, are not defined by this standard. The vendor identification code and service number together serve to unambiguously identify the intended purpose of the information conveyed by the remainder of the APDU or the service to be performed by the remote device based on parameters in the remainder of the APDU.

The vendor identification code is a unique code assigned to the vendor by ASHRAE

post

Executes a BACnet privateTransfer service and returns immediately.

The UnconfirmedTextMessage service is used by a client BACnet-user to send a text message to one or more BACnet devices. This service may be broadcast, multicast, or addressed to a single recipient. This service may be used in cases where confirmation that the text message was received is not required. Messages may be prioritized into normal or urgent categories. In addition, a given text message may optionally be classified by a numeric class code or class identification string. This classification may be used by receiving BACnet devices to determine how to handle the text message. For example, the message class might indicate a particular output device on which to print text or a set of actions to take when the text message is received. In any case, the interpretation of the class is a local matter.

post

Executes a BACnet textMessage service and returns immediately.

The TimeSynchronization service is used by a requesting BACnet-user to notify a remote device of the correct current time. This service may be broadcast, multicast, or addressed to a single recipient. Its purpose is to notify recipients of the correct current time so that devices may synchronize their internal clocks with one another.

post

Executes a BACnet timeSynchronization service and returns immediately.

The Who-Has service is used by a sending BACnet-user to identify the Device object identifiers and network addresses of other BACnet devices whose local databases contain an object with a given Object_Name or a given Object_Identifier. The IHave service is used to respond to Who-Has service requests or to advertise the existence of an object with a given Object_Name or Object_Identifier. The I-Have service request may be issued at any time and does not need to be preceded by the receipt of a Who-Has service request. The Who-Has and I-Have services are unconfirmed services.

post

Executes a BACnet whoHas service and returns immediately.

The Who-Is service is used by a sending BACnet-user to determine the Device object identifier, the network address, or both, of other BACnet devices that share the same internetwork. The Who-Is service is an unconfirmed service. The Who-Is service may be used to determine the Device object identifier and network addresses of all devices on the network, or to determine the network address of a specific device whose Device object identifier is known, but whose address is not. The IAm service is also an unconfirmed service. The I-Am service is used to respond to Who-Is service requests. However, the IAm service request may be issued at any time. It does not need to be preceded by the receipt of a Who-Is service request. In particular, a device may wish to broadcast an I-Am service request when it powers up. The network address is derived either from the MAC address associated with the I-Am service request, if the device issuing the request is on the local network, or from the NPCI if the device is on a remote network.

post

Executes a BACnet WhoIs service and returns immediately. Iam responses are stored in the REST Api and can be accessed from the network method.

The UTCTimeSynchronization service is used by a requesting BACnet-user to notify one or more remote devices of the correct Universal Time Coordinated (UTC). This service may be broadcast, multicast, or addressed to a single recipient. Its purpose is to notify recipients of the correct UTC so that devices may synchronize their internal clocks with one another.

post

Executes a BACnet utcTimeSynchronization service and returns immediately.

Executes a BACnet writeGroup service.

post

The purpose of WriteGroup is to facilitate the efficient distribution of values to a large number of devices and objects. WriteGroup provides compact representations for data values that allow rapid transfer of many values.

The WriteGroup service is used by a sending BACnet-user to update arbitrary Channel objects' Present_Value properties for a particular numbered control group. The WriteGroup service is an unconfirmed service. Upon receipt of a WriteGroup service request, all devices that are members of the specified control group shall write to their corresponding Channel objects' Present_Value properties with the value applicable to the Channel Number, if any. A device shall be considered to be a member of a control group if that device has one or more Channel objects for which the 'Group Number' from the service appears in its Control_Groups property. If the receiving device does not contain one or more Channel objects with matching channel numbers, then those values shall be ignored.

The WriteGroup service may be unicast, multicast, broadcast locally, on a particular remote network, or using the global BACnet network address. Since global broadcasts are generally discouraged, the use of multiple directed broadcasts is preferred.

Object Access

The Object Access helper methods provide a simplified approach to accessing BACnet objects and properties from any device on the network. The REST API will determine the appropriate BACnet Service to use when accessing the data. This could be readProperty, writeProperty, readPropertyMultiple, writePropertyMultiple or COV.

The Network object provides a list of currently detected devices in the BACnet network. An application can send use the service method to issue a whoIs request to automatically discover all the devices on the network. When an Iam is received the response will be stored int the REST API and can be retrieved by calling the network method.

get

Returns the Network object as a list of device address binding.

post

The read method can be used to read from 1 or properties from 1 or more devices in the network. This method can be used to perform a batch request for many devices.

post

The write method can be used to write to 1 or properties from 1 or more devices in the network. This method can be used to perform a batch request for many devices.

Access the specified bacnet device.

get

Returns a list of object types found in the device.

get

Returns a list of objects found in the device.

post

The read method can be used to read from 1 or properties from this device. This method can be used to perform a batch request for many properties.

post

The write method can be used to read from 1 or properties from this device. This method can be used to perform a batch request for many properties.

Access the specified object type within a bacnet device.

get

Returns a list of object instance found in the device matching this object type.

get

Returns a list of objects found in the device.

post

The read method can be used to read from 1 or properties from this device. This method can be used to perform a batch request for many properties.

post

The write method can be used to read from 1 or properties from this device. This method can be used to perform a batch request for many properties.

Access the specified object within a bacnet device.

get

Returns a list of values for all properties within this object.

post

The read method can be used to read from 1 or properties from an object. This method can be used to perform a batch request for many properties.

post

The read method can be used to write from 1 or properties from an object. This method can be used to perform a batch request for many properties.

Access an object property within a bacnet device.

get

Read a single property from an object within a bacnet device and return the result as a JSON object.

put

Write to a single property of an object within a bacnet device and return the write result as a JSON object.