Appendix 1 - Driver Actions

This appendix describes how to add an action to your driver's device or proxy extension in Niagara AX such that when the action is invoked, either by a Niagara-AX user or by some Niagara-AX logic, your driver instructs the field device to perform a special function.

For example, some driver protocols feature a reboot message that when sent to a field-device over the field-bus, the field-device will reboot. If your protocol features such a message then you can add a reboot action to your driver's device class. By following these steps, when the reboot action is invoked from Niagara-AX, your driver will transmit a reboot request to corresponding field-device causing the field-device to reboot.

Please note that the reboot example is just one of many possibilities. Your driver's protocol might not necessarily support reboot but it might support some other special behavior. Another somewhat typical example is a change time feature. In any event, the procedure for implementing this in your driver is as follows:

Add an action to your device.
- Add an action to the slotomatic statement in the java file for your driver's device.
- Save the java file.
- Run the slotomatic utility against your driver
- Add an empty do... method to your device's java file. For example, if you called the action something in the slotomatic statement, then add a Java method called doSomething to your device's java file. The method needs to be defined with the public identifier.
Define a request and a response to tell the field-device what to do.

Create a request class and a response class.
Make the request class extend BDdfResponse.
Call getDeviceId in the toByteArray method for the request.
Cast the result as an instance of your device's device id class.
Following your equipment's protocol, construct the byte array to instruct the appropriate field-device to do something.
Make the response extend BDdfResponse.
From the processReceive method of the request, return a BDdfResponse if the given data frame is as expected.

Have your do... method (for the new action that you added to your device) place an instance of the request onto the device's communicator.

Call getDdfCommunicator().communicate( new BYourDriverDoSomethingRequest() ); from the do... method that defines the action's behavior.
Note that the call to communicate is a non-blocking call. Please read further for an explanation of how to perform special processing on the response.

To update your device after receiving the response to the Do Something request:
- Give the request a constructor that takes the device as a parameter.
- In your device's do... method, pass an instance of the device (using the Java this keyword) to the request.
- Make the request class implement the BIDdfCustomResponse interface from the com.tridium.ddf.comm.rsp package in the devDriver jar.
- Declare a processResponse method on the request. The developer driver framework will automatically call this method when the do something response is received for the do something request. The do something response is passed in as a parameter.
- In the processResponse method, you may use the reference to your device (the reference that you passed to the request's constructor) and update your device accordingly.
- Declare a processTimeout method on the response. This method is automatically called if the do something request times out. You may add any Java code here that you wish (or you may leave the method empty).
- Declare a processErrorResponse method on the response. This method is automatically called if the do something request's processRecieve method throws a DdfResponseException. You may add any Java code here that you wish (or you may leave the method empty).
- Declare a processLateResponse method on the response. This method is automatically called if the do something response is received after the request times out. Please note that this can only happen if your driver uses a multiple-transaction-communicator. You may add any Java code here that you wish (or you may leave the method empty).