Basic Driver

Overview

Refer to the Basic Driver API.

This package provides some basic classes that may be useful to developers building a new driver (i.e. field bus driver). These classes can be used (or subclassed) to provide some basic driver functionality, such as worker (queue) management, basic poll schedule handling, basic messages and management of these basic messages through request/response transactions (as well as unsolicited message handling), etc. It also provides a serial implementation (com.tridium.basicdriver.serial) which can be subclassed by drivers that use a serial port for communication. Here is an overview of basicDriver's structure:

                BBasicNetwork
               /   /    |    \
              /   /     |     \
  BBasicDevices  /      |   Worker Queues (BBasicWorkers)
                /       |    - dispatcher (used for
               /        |      synchronizing access to Comm)
BBasicPollScheduler     |    - worker (for posting async
                        |      operations, such as learns)
                        |    - write worker (for posting
                        |      async coalescing operations,
                        |      such as writes)
                        |
                      Comm
                     /  |  \
                    /   |   \
       CommReceiver     |   CommTransactionManager
       CommTransmitter  |    - CommTransactions
                        |
                        |
             UnsolicitedMessageListeners
          (registered if needed by network)

The abstract class BBasicNetwork is the root component of basicDriver. It is the base container for BBasicDevice objects, and it provides a basic poll scheduler where objects implementing the BIBasicPollable interface can register to be polled (i.e. points, devices). It also provides three worker threads (queues) for handling asynchonous operations and synchronization of request messages to the Comm for transmission to the output stream (the following outlines the INTENDED use of these worker queues):

Asynchronous operations should be posted onto either the worker queue or write worker queue (coalescing). Write operations should always go to the write worker queue so they will be coalesced. Most other asynchronous operations, such as learns, should be posted to the worker queue to keep the write worker queue free for write operations. As these async operations are processed (dequeued), they should post any necessary message requests to the dispatcher queue, which synchronizes access to the Comm (Comm is ultimately responsible for sending the request message to the output stream via the CommTransmitter and receiving the response message from the input stream via the CommReceiver). Other threads may also post directly to the dispatcher queue (for example, the poll thread can post poll message requests directly to the dispatcher queue).

   
    worker queue           write worker queue   
        ___                       ___
       |___|                     |___|
       |___|                     |___|
       |___|                     |___|
       |___|                     |___|
       |___|                     |___|
         |                         |
         |    dispatcher queue     |
         |          ___            |
         --------+ |___| +----------
   --------------+ |___|
   |               |___| (The dispatcher queue
  poll             |___|  is intended to handle
  requests         |___|  message requests only)
                     |
                     |
                     |
                     ---------+ send a request message
                                to Comm to transmit to
                                the output stream, and
                                wait for and return
                                any response from the
                                input stream.

Supporting Classes

BBasicNetwork also handles initialization, starting, and stopping the Comm, or communication handler. Comm is used to manage request/response message transactions for the network, handles the interaction between the low-level transmitter and receiver, and routes any unsolicited received messages to the appropriate listener. Comm uses the following supporting classes to accomplish its tasks:

Messages

The com.tridium.basicdriver.message package contains classes useful for building driver messages (using the Message abstract class), allowing these Messages to be written to the output stream, and formatting a response received (ReceivedMessage) into a proper Message.

Utility Classes

The com.tridium.basicdriver.util package contains utility classes useful to most drivers.

Serial Driver

The com.tridium.basicdriver.serial package contains classes useful to most serial drivers (with the communication handler, Comm, at the network level).