This module represents the BACnet Read Property Multiple service.
The Read Property Multiple service is used to read multiple properties of one or multiple objects.
Service Description (ASHRAE 135)
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.
Service Procedure (ASHRAE 135)
After verifying the validity of the request, the responding BACnet-user shall attempt to access the specified properties of the specified objects and shall construct a 'List of Read Access Results' in the order specified in the request. If the 'List of Property References' portion of the 'List of Read Access Specifications' parameter contains the property identifier ALL, REQUIRED, or OPTIONAL, then the 'List of Read Access Results' shall be constructed as if each property being returned had been explicitly referenced. While there is no requirement that the request be carried out "atomically," the responding BACnet-user shall ensure that all readings are taken in the shortest possible time subject only to higher priority processing. The request shall continue to be executed until an attempt has been made to access all specified properties. If none of the specified objects is found or if none of the specified properties of the specified objects can be accessed, either a 'Result(-)' primitive or a Result(+) primitive that returns error codes for all properties shall be issued. If any of the specified properties of the specified objects can be accessed, then a 'Result(+)' primitive shall be issued, which returns all accessed values and error codes for all properties that could not be accessed. When the object-type in the Object Identifier portion of the Read Access Specification parameter contains the value 'Device Object' and the instance of that 'Object Identifier' parameter contains the value 4194303, the responding BACnet-user shall treat the Object Identifier as if it correctly matched the local Device object. This allows the device instance of a device that does not generate I-Am messages to be determined.
Result(+) Response (ASHRAE 135)
On success, the responding BACnet-user returns a 'Result(+)' primitive containing a 'List of Read Access Results'. Each entry corresponds to one 'Read Access Specification' from the request and contains:
- The 'Object Identifier' and 'Property Identifier' (and optional 'Property Array Index').
- Either the successfully read property value(s), or an error code if that specific property could not be read.
The order of results matches the order of the original request. Partial success is allowed - some properties may succeed while others return errors.
Result(-) Errors (ASHRAE 135)
The 'Result(-)' parameter shall indicate that the service request has failed in its entirety. The reason for the failure shall be specified by the 'Error Type' parameter.
The 'Error Class' and 'Error Code' to be returned for specific situations are as follows:
| Situation | Error Class | Error Code |
|---|---|---|
| Specified object does not exist. | OBJECT | UNKNOWN_OBJECT |
| Specified property does not exist. | PROPERTY | UNKNOWN_PROPERTY |
| An array index is provided but the property is not an array. | PROPERTY | PROPERTY_IS_NOT_AN_ARRAY |
| An array index is provided that is outside the range existing in the property. | PROPERTY | INVALID_ARRAY_INDEX |
| The property is not accessible using this service. | PROPERTY | READ_ACCESS_DENIED |
Summary
Functions
Whether the service is of type confirmed or unconfirmed.
Converts the given Confirmed Service Request into a Read Property Multiple Service.
Get the service name atom.
Get the Confirmed Service request for the given Read Property Multiple Service.
Types
@type t() :: %BACnet.Protocol.Services.ReadPropertyMultiple{ list: [BACnet.Protocol.AccessSpecification.t()] }
Parameters for the Read Property Multiple service.
Contains a list of Access Specifications describing one or more objects and the properties (or property ranges) to be read atomically in a single request. The response is a Read Property Multiple ACK.
Functions
@spec confirmed?() :: true
Whether the service is of type confirmed or unconfirmed.
@spec from_apdu(BACnet.Protocol.APDU.ConfirmedServiceRequest.t()) :: {:ok, t()} | {:error, term()}
Converts the given Confirmed Service Request into a Read Property Multiple Service.
@spec get_name() :: atom()
Get the service name atom.
@spec to_apdu(t(), Keyword.t()) :: {:ok, BACnet.Protocol.APDU.ConfirmedServiceRequest.t()} | {:error, term()}
Get the Confirmed Service request for the given Read Property Multiple Service.
See the BACnet.Protocol.Services.Protocol function documentation for more information.