BACnetStack_AddTrendLogObject

bool BACnetStack_AddTrendLogObject(
  const uint32_t deviceInstance,
  const uint32_t objectInstance,
  const uint16_t logObjectType,
  const uint32_t logObjectInstance,
  const uint32_t logPropertyIdentifier,
  const bool useLogPropertyArrayIndex,
  const uint32_t logPropertyArrayIndex,
  const uint32_t maxBufferSize,
  const bool isLoggedObjectInRemoteDevice,
  const uint32_t logDeviceInstance);

Adds a BACnet Trend Log Object.

The device must be added first before this function can be called. The Trend Log Object references a logged device, object, and property and when enabled, will log the values of the property based on the logging type. The logging type for this log object is set by calling one of the following functions after calling this function:

SetTrendLogTypeToPolled
SetTrendLogTypeToCOV
SetTrendLogTypeToTriggered

Users must also pass in the max buffer size which represents the maximum number of records to store.

The Trend Log properties that are handled and stored by the CAS BACnet Stack are:

Enable, Stop_When_Full, Trigger, Logging_Type
Start_Time, Stop_Time, Log_Interval
Buffer_Size, Record_Count, Total_Record_Count
Log_DeviceObjectProperty (set by this function), Client_COV_Increment
Log_Buffer, Object_Identifier, Object_Type, Status_Flags, Property_List These are answered from stack storage BEFORE any callback is consulted, so a registered Get callback CANNOT override them. Writes to the writable ones land in the same storage, not in a Set callback - and a WriteProperty to ANY Trend Log property Aborts unless BACnetStack_RegisterCallbackGetSystemTime() has been called. Log_Buffer is readable only with ReadRange; a ReadProperty of it returns Error(PROPERTY, READ_ACCESS_DENIED).

Callbacks are used to handle the remaining required properties. The following list contains those properties and the Callbacks that are used to get the required data:

    --------------------------------------------------------------------------------
    Property            Datatype            Callback
    --------------------------------------------------------------------------------
    ObjectName          CharacterString     CallbackGetPropertyCharacterString
                                            CallbackSetPropertyCharacterString
                                            (only if made writable)
    EventState*         Enumerated          CallbackGetPropertyEnumerated
        (*) Served by the stack's intrinsic alarm engine instead, if intrinsic reporting has been
        enabled for this object.  With neither an alarm engine nor a callback the stack
        answers NORMAL.
    --------------------------------------------------------------------------------

BACnet reference: ANSI/ASHRAE 135-2024 clause 12.25 (Trend Log Object Type).

Parameters

Parameter	Direction	Description
`deviceInstance`	in	The instance number of the device that owns this Trend Log Object.
`objectInstance`	in	The instance number of this Trend Log Object.
`logObjectType`	in	The BACnet object type of the object to log. See CASBACnetStack::BACnetObjectType for available values. With logObjectInstance, this is one BACnet Object Identifier carried as two parameters.
`logObjectInstance`	in	The instance number of the object to log.
`logPropertyIdentifier`	in	The BACnet Property Identifier of the object to log. See BACnetPropertyIdentifier for available values.
`useLogPropertyArrayIndex`	in	Flag that determines whether to use logPropertyArrayIndex (true) or log the whole property (false). Lets a Trend Log record one array element - e.g. Priority_Array[8] of a commandable object, or one element of a Multi-state object’s State_Text - instead of only ever the whole property.
`logPropertyArrayIndex`	in	The property array index to use; ignored when useLogPropertyArrayIndex is false. logObjectType, logObjectInstance, logPropertyIdentifier and this index together set Log_DeviceObjectProperty, a BACnetDeviceObjectPropertyReference (cl. 12.25, cl. 21).
`maxBufferSize`	in	The maximum number of logged records held in memory, i.e. the object’s Buffer_Size property. The buffer is circular: once full, the oldest record is overwritten unless Stop_When_Full is set. Each record costs memory proportional to the logged datatype, so size this against the target’s RAM rather than picking a large round number. Must be at least 1.
`isLoggedObjectInRemoteDevice`	in	MUST be false. Passing true ALWAYS fails this call - logging a property held in a remote device is not implemented. Contact Chipkin if you need it.
`logDeviceInstance`	in	Ignored. It is only consulted on the remote-device path, which cannot succeed (see isLoggedObjectInRemoteDevice). Pass 0.

Returns

True if successful, false if failed.

Topic: Objects and properties. Declared in CASBACnetStackDLL.h.