com.acces.aiousb
Class CounterSubsystem

java.lang.Object
  extended by com.acces.aiousb.CounterSubsystem

public class CounterSubsystem
extends java.lang.Object

Class CounterSubsystem represents the counter/timer subsystem of a device. One accesses this counter/timer subsystem through its parent object, typically through a method such as ctr() (see USB_AI16_Family.ctr()).


Method Summary
 Counter getCounter(int counter)
          Gets a reference to an individual counter.
 int getNumCounterBlocks()
          Gets the number of counter blocks.
 int getNumCounters()
          Gets the number of individual counters, indexed from 0 to n-1.
 USBDevice getParent()
          Gets the parent device that this subsystem is part of.
 java.io.PrintStream print(java.io.PrintStream stream)
          Prints the properties of this subsystem.
 char[] readCounts(boolean oldData)
          Reads the current count values of all the counters, optionally including an "old data" indication.
 CounterSubsystem selectGate(int counter)
          Selects the counter to use as a gate in frequency measurement on other counters.
 double startClock(int counterBlock, double clockHz)
          Selects an output frequency for a counter block and starts the counters.
 CounterSubsystem stopClock(int counterBlock)
          Halts the counter started by startClock()
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

print

public java.io.PrintStream print(java.io.PrintStream stream)
Prints the properties of this subsystem. Mainly useful for diagnostic purposes.

Parameters:
stream - the print stream where properties will be printed.
Returns:
The print stream.

getNumCounterBlocks

public int getNumCounterBlocks()
Gets the number of counter blocks. Typically there are three counters per counter block.

Returns:
The number of counter blocks.

getNumCounters

public int getNumCounters()
Gets the number of individual counters, indexed from 0 to n-1.

Returns:
The number of individual counters.

getCounter

public Counter getCounter(int counter)
Gets a reference to an individual counter. You must obtain a reference to a counter before you can perform counter operations.

Parameters:
counter - the counter for which to obtain a reference (0 to n-1).
Returns:
A reference to the specified counter.
Throws:
java.lang.IllegalArgumentException

readCounts

public char[] readCounts(boolean oldData)
Reads the current count values of all the counters, optionally including an "old data" indication. If oldData is true, then an extra word will be returned (one word for each counter, plus one extra word) that contains an "old data" indication, which is useful for optimizing polling rates. If the value of the final word is zero, then the data is "old data," meaning you are polling the counters faster than your gate signal is running. If oldData is false, then only the count values are returned.

Parameters:
oldData - true includes the "old data" indication in the returned data; false returns just the count values.
Returns:
An array containing the current count values for all the counters plus an optional "old data" indication in the final word.
Throws:
OperationFailedException

selectGate

public CounterSubsystem selectGate(int counter)
Selects the counter to use as a gate in frequency measurement on other counters.

Parameters:
counter - the counter to select as a gate (0 to n-1).
Returns:
This subsystem, useful for chaining together multiple operations.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

startClock

public double startClock(int counterBlock,
                         double clockHz)
Selects an output frequency for a counter block and starts the counters. selectGate() and readCounts( true ) are used in measuring frequency. To measure frequency one must count pulses for a known duration. In simplest terms, the number of pulses that occur for 1 second translates directly to Hertz. In the USB-CTR-15 and other supported devices, you can create a known duration by configuring one counter to act as a "gating" signal for any collection of other counters. The other "measurement" counters will only count during the "high" side of the gate signal, which we can control.

So, to measure frequency you:
1. Create a gate signal of known duration
2. Connect this gating signal to the gate pins of all the "measurement" counters
3. Call selectGate() to tell the board which counter is generating that gate
4. Call readCounts( true ) periodically to read the latched count values from all the "measurement" counters.

In practice, it may not be possible to generate a gating signal of sufficient duration from a single counter. Simply concatenate two or more counters into a series, or daisy-chain, and use the last counter's output as your gating signal. This last counter in the chain should be selected as the "gate source" using selectGate().

Once a value has been read from a counter using the readCounts( true ) call, it can be translated into actual Hz by dividing the count value returned by the high-side-duration of the gating signal, in seconds. For example, if your gate is configured for 10Hz, the high-side lasts 0.05 seconds. If you read 1324 counts via the readCounts( true ) call, the frequency would be "1324 / 0.05", or 26.48 KHz.

Parameters:
counterBlock - the counter block to use to generate the frequency.
clockHz - the desired output frequency (in Hertz).
Returns:
The actual frequency that will be generated, limited by the device's capabilities.
Throws:
java.lang.IllegalArgumentException
OperationFailedException

stopClock

public CounterSubsystem stopClock(int counterBlock)
Halts the counter started by startClock()

Parameters:
counterBlock - the counter block to halt generating a frequency.
Returns:
This subsystem, useful for chaining together multiple operations.

getParent

public USBDevice getParent()
Gets the parent device that this subsystem is part of.

Returns:
The parent device that this subsystem is part of.