Chapter 5 - Create Your Driver's Ping Response

While following the examples in this chapter, please replace the text jarFileName, yourDriver and yourCompany as previously described in the Preparation section):

Make a class named BYourDriverPingResponse that extends BDdfResponse. Create this in a package named com.yourCompany.yourDriver.comm.rsp. Add an empty slotomatic statement too.

To do this, create a text file named BYourDriverPingResponse.java in the jarFileName/src/com/yourCompany/yourDriver/comm/rsp folder. Inside the text file, start with the text that follows.

package com.yourCompany.yourDriver.comm.rsp;

import javax.baja.sys.*;

import com.tridium.ddf.comm.rsp.*;

public class BYourDriverPingResponse
  extends BDdfResponse
{
  /*-
  class BYourDriverPingResponse
  {
  }
  -*/
}

NOTE: The multi-line comment that immediately follows the Java class declaration is an empty Niagara slotomatic declaration.

Run slotomatic and perform a full build on your driver (as described in Chapter 2).

For now, you have been intentionally instructed to create empty response class. Later you will learn about more that you can do with the response class. Fortunately, an empty response class often works sufficiently for pinging in a simple request-response transactions. For now, however, let us not worry about parsing the data that might be in the ping response. It is sufficient to simply know that we received a response because at the very least, we can conclude that the external equipment is online, otherwise, it would not have responded at all.

Next, please open BYourDriverPingRequest.Java in your text editor.
Add the following import statement to the imports of BYourDriverPingRequest.java:

import com.yourCompany.yourDriver.comm.rsp.*;

Update the processReceive method in your ping request class (BYourDriverPingRequest). Return an instance of BYourDriverPingResponse.

  package com.yourCompany.yourDriver.comm.req;

  import javax.baja.sys.*;

  import com.tridium.ddf.comm.req.*;
  import com.tridium.ddf.comm.rsp.*;
  import com.tridium.ddf.comm.*;

  import com.yourCompany.yourDriver.identify.*;
  import com.yourCompany.yourDriver.comm.rsp.*;

  public class BYourDriverPingRequest
    extends BDdfPingRequest
  {
    /*-
    class BYourDriverPingRequest
    {
    }
    -*/

  }

  ...

  /**
   * For this example, we will assume that the mere fact that a data
   * frame was received after transmitting this response means that
   * the equipment must have responded to the request. Since in
   * Niagara AX, the primary purpose of a ping request-response
   * transaction is to determine whether or not the corresponding
   * field-device is online, then this will suffice.
   */
  public BIDdfResponse processReceive(IDdfDataFrame recieveFrame)
    throws DdfResponseException
  {
    return new BYourDriverPingResponse();
  }

}

ADVANCED: After transmitting the bytes for your request (the bytes returned by your request's toByteArray method), the developer driver framework will pass all frames that it receives to your request's processReceive method. This is done until your request returns a BIDdfResponse from this method or throws a DdfResponseException (or a subclass of DdfResponseException).

The processReceive method needs to take one of the following steps:

(ADVANCED) Ignore the frame and return null.

This could happen in more advanced protocols that are not "master-slave" by nature. In this scenario, by returning null, the developer driver framework will continue to pass subsequent data frames that it receives to this method.

(ADVANCED) Collect the frame and return a BIDdfMultiFrameResponse. In which case, you need to implement your own collection mechanism. For example, this could be as simple as putting them all in a Vector in the BIDdfMultiFrameResponse (until the request is considered to have timed-out).

This could happen in more advanced protocols where the equipment might respond by sending multiple frames of data. By returning an instance of BIDdfMultiFrameResponse, the developer driver framework will know that your request is making progress. The developer driver framework will also continue to pass subsequent data frames that it receives to this method (until the request is considered to have timed-out).

(TYPICAL) Return a BIDdfResponse for the data frame (ADVANCED -- and any previously collected frames -- ADVANCED) that you determine together make up a completed response.

By returning a response from your ping request's processReceive method, the developer driver framework will know that the corresponding field-device is online. The particular request-response transaction will be considered to be complete. No subsequent data frames will be passed to this particular request's processReceive method.

(SOMEWHAT TYPICAL) Throw a DdfResponseException or subclass of DdfResponseException to indicate that the frame forms a complete message but indicates an invalid condition within the frame (perhaps a frame that indicates a negative acknowledgement or NACK).

By throwing a DdfResponseException or a subclass of DdfResponseException, the developer driver framework will know that the corresponding field-device is not completely online. The particular request-response transaction will be considered to be complete. No subsequent data frames will be passed to this particular request's processReceive method.

WARNING: In the middle two scenarios, if you need to keep the bytes that are received then it is important that you retain only a copy the frame's bytes. The frame's actual byte array could be a direct reference to an internal buffer in the receiver.

Run slotomatic and perform a full build on your driver (as described in Chapter 2).

At this point, not only have you gained familiarly with your protocol and defined an outgoing request, you have now told Niagara how to parse incoming data frames. You have also defined the incoming response class and associated it with the outgoing request. Next, you will further associate the receiver that you created in Chapter 4 to the device you created in Chapter 3 or to your driver's network class, which you will create in chapter 7.