Chapter 1 - Create Your Driver's Ping Request

The first thing you should do to create a driver using the developer driver framework is create your driver's ping request. The ping request represents the data that the platform computer must transmit over the field-bus to a particular unit of the external equipment (the field-device) in order to determine whether or not the particular unit of external equipment (field-device) is currently online and ready to communicate.

Please follow these steps to create your ping request (replacing the text yourDriver and yourCompany as previously described in the Preparation section):

Review your equipment's protocol documentation. If you are working directly for the manufacturer of the equipment, then they should be able to provide you with one or more documents that describes the way in which the equipment communicates, plus the structure of the data that the equipment expects to see on the field-bus. If you have purchased this equipment then you will need to negotiate with the equipment's manufacturer in order to gain access to the equipment's protocol.
Pick a 'ping' message from your protocol. After reviewing the equipment's protocol documentation, choose a message from the protocol that looks like the simplest message to which a unit of the equipment (field-device) will respond.
Make a Java class that extends BDdfPingRequest. Name it BYourDriverPingRequest. Create this in the package named com.yourCompany.yourDriver.comm.req. Also add an empty slotomatic comment immediately after the opening brace for the class declaration.

To do this, create a text file named BYourDriverPingRequest.java in the jarFileName/src/com/yourCompany/yourDriver/comm/req folder. Inside the text file, start with the following text:

Please replace yourCompany and yourDriver in both the file name and the following text, as previously described.

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.*;

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

}

Override the toByteArray method. Build the byte array following your protocol's ping message.
Inside the body of the toByteArray method, you will need to construct a Java byte array and return it. The next step will further describe how to do this.

To add the toByteArray method, add the following lines of text on the line that is immediately above the last, closing brace. A closing brace looks like this: }
public byte[] toByteArray() { }
Assume that any data that you need in order to construct your byte array to return from the toByteArray method/function is the value in a frozen property on another, device Id class that extends BDdfIdParams (we'll further discuss the device Id class in the next chapter). Please do not be overwhelmed at the mention of these. Suffice it to say, you will soon create another class that we will call a device id. On the device id, you will define one or more frozen properties that uniquely identify a particular unit of equipment (field-device) on the field-bus.

Frozen properties are a special kind of Niagara AX property on a Niagara AX component that you can easily access from Java source code. You will make the device id class in subsequent sections of this document. For now, please assume that you have already created it.

However, when you create this device id class (please do not worry about creating it now!!!), you will define some frozen properties on the class. More specifically, you will define the frozen properties whose values you will need in order to construct the byte array that this toByteArray method/function will return. For example, if you need something that your protocol document might call the unit number in order to build a request message, then you will later add a property called unitNumber to your device id.

To do that, you will add a special comment just after the class statement in the Java file. After doing that, you will run a Niagara AX development utility called slotomatic that will parse the comment and add some Java code to your file -- the Java code necessary to add the property to the Niagara AX structure that the Java file defines. More specifically, the slotomatic utility will generate a method (function) called getUnitNumber that will return a Java int, or another type as you would have defined in the special comment. By the way, let's call that special comment a slotomatic statement.

In light of all this discussion, please finish updating the toByteArray method to return a byte array that matches the description that your protocol document defines for the message that you choose to be the ping request. Please follow this example as a guide:

  public byte[] toByteArray()
  {
    // In the developer driver framework, all requests are automatically
    // Assigned a deviceId when they are created. The developer driver
    // Framework calls this method (function) after it creates the
    // Request, therefore this particular request has already been
    // Assigned a deviceId. The deviceId will be an instance of
    // BYourDriverDeviceId - that is how the developer driver works!

    BYourDriverDeviceId deviceId =
      (BYourDriverDeviceId)getDeviceId();

    final byte SOH = 0x01;
    final byte EOT = 0x04;
    // In this hypothetical example, the protocol document would
    // Indicate that all requests start with a hex 01 byte and
    // All requests end with a hex 04 byte.
    // So, after the hex 01, the protocol expects a number between
    // 0 and 255 to identify the device, followed by some ASCII
    // Characters ("ping" in this case), followed by the hex 04
    // Terminator byte.
    return new byte[]{
       SOH,
      (byte)deviceId.getUnitNumber(),
      (byte)'p',
      (byte)'i',
      (byte)'n',
      (byte)'g',
       EOT};
  }

Override the processReceive method but simply return null for now. We will revisit this later. The developer driver framework calls the toByteArray method (function), transmits the resulting byte array onto the field-bus, looks for incoming data frames, and passes them to this method (until this method returns a response (not null), throws an exception, or times out. We'll discuss this in further detail later. For now, please do as follows:

  public BIDdfResponse processReceive(IDdfDataFrame recieveFrame)
    throws DdfResponseException
  {
    return null;
  }