You can use Change-of-Value (CoV) functions to implement event-based monitoring in a custom driver. Event-based monitoring requires the driver to automatically forward datapoint updates to IDL. Many protocols such as EnOcean, LoRaWAN, BACnet, and LON provide native support for event-based monitoring. When supported by the protocol, the driver can use the CoV functions to forward unsolicited updates to the driver. Some protocols such as Modbus do not support event-based monitoring. Custom drivers for such protocols do not use the CoV functions. When CoV is not enabled for a driver, IDL simulates event-driven monitoring by issuing round robin read requests for the datapoints every 0.5 seconds.

CoV Callback Functions

The following two callback functions must be defined to support CoV updates. A custom driver must register both callback functions to support CoV updates. If only one is registered, the driver process exits.

DpEnableEvent

IdlErrorCodes DpEnableEvent(int callback_index, IdlDev *dev, IdlDatapoint *dp);

When a datapoint's monitor.event attribute is set to true, the IDL calls the DpEnableEvent() callback function and waits for a timeout of dpEventTimeoutMs to receive a response from the IDL driver instance (IDI). The IDI reports success or failure to the IDL by calling IdlDpEnableEventResult(). If success is received, then the IDL understands that the IDI has successfully started event-based monitoring for that datapoint and expects that the IDI will send frequent updates for that datapoint. If failure is received, the IDL uses round-robin polling for that datapoint. If the IDI does not respond to DpEnableEvent within the timeout dpEventTimeoutMs, the IDL retries by calling DpEnableEvent again. IDL retries up to three times before assuming a failure and then starts polling the datapoint in round-robin.

DpDisableEvent

IdlErrorCodes DpDisableEvent(int callback_index, IdlDev *dev, IdlDatapoint *dp);

When a datapoint's monitor.event attribute is set to false, the IDL calls the DpDisableEvent callback function. The IDL driver instance (IDI) responds to this request by calling IdlDpDisableEventResult.

CoV Related Functions

The following functions support CoV-related activities.

IdlDpEnableEventCallbackSet

void IdlDpEnableEventCallbackSet(Idl *idl, IdlErrorCodes(*DpEnableEvent)(int, IdlDev *, IdlDatapoint *));

IdlDpDisableEventCallbackSet

void IdlDpDisableEventCallbackSet(Idl *idl, IdlErrorCodes(*DpDisableEvent)(int, IdlDev *, IdlDatapoint *));

IdlDpEnableEventResult

void IdlDpEnableEventResult(int callbackIndex, IdlDev *dev, IdlDatapoint *dp, IdlErrorCodes idlError);

This function is called by DpEnableEvent to return an indication of success or failure.

IdlDpDisableEventResult

void IdlDpDisableEventResult(int callbackIndex, IdlDev *dev, IdlDatapoint *dp, IdlErrorCodes idlError);

This function is called by DpDisableEvent to return an indication of failure.

IdlOnDpEvent

void IdlOnDpEvent(IdlDev *dev, IdlDatapoint *dp, char *prioArray, double value);

For all successful CoV subscriptions, the custom driver reports a changed datapoint value using IdlOnDpEvent. IDL passes the value through the fast path algorithm and publishes to ev/data for all other monitoring filters.

Browser not supported