4 Pulse Counters

The com.oracle.deviceaccess.counter package contains interfaces and classes for counting pulses on a digital input line. In order to access and control a specific pulse counter, an application should first obtain an PulseCounter instance for the pulse counter the application wants to access and control, using its numerical ID, name, type (interface) and properties.

The following code is an example of using its ID.

 PulseCounter counter = (PulseCounter) PeripheralManager.open(8);

This is an example of using its name and interface, returned as a PulseCounter object:

 PulseCounter counter = (PulseCounter) PeripheralManager.open("ENCODER",
     PulseCounter.class, null);

Once opened, an application can start a pulse counting session by one of two ways. First, an application can use the startCounting() method and retrieve the current pulse count on-the-fly by calling the PulseCounter.getCount() method. Alternatively, the application can start a pulse counting session with a terminal count value and a counting time interval using the PulseCounter.startCounting(int, long, com.oracle.deviceaccess.counter.CountingListener). The application can then be asynchronously notified once the terminal count value has been reached or the counting time interval has expired. In both cases, the application can retrieve the current pulse count value at any time by calling the PulseCounter.getCount(), as shown in the following example:

 counter.startCounting(); // Start counting pulses   // Perform some task... int count = counter.getCount();
   // Retrieve the number of pulses that occurred while performing the task counter.stopCounting(); // Stop counting pulses

When done, the application should call the PulseCounter.close() method to release PulseCounter.

 counter.close();

Example 4-1 shows how to use the pulse counter API.

Example 4-1 Using the Pulse Counter API

import com.oracle.deviceaccess.PeripheralManager;
import com.oracle.deviceaccess.PeripheralNotAvailableException;
import com.oracle.deviceaccess.PeripheralNotFoundException;
import com.oracle.deviceaccess.counter.CountingEvent;
import com.oracle.deviceaccess.counter.CountingListener;
import com.oracle.deviceaccess.counter.PulseCounter;
import java.io.IOException;
 
 class PulseCounting implements CountingListener {
 
     private PulseCounter counter = null;
 
     public void start(int counterID) throws IOException,
         PeripheralNotAvailableException, PeripheralNotFoundException
 {
         counter = (PulseCounter) PeripheralManager.open(counterID);
         counter.startCounting(-1, 1000, this);
           // Count events occuring during 1 second (without terminal count value)
     }
 
     public void countValueAvailable(CountingEvent event) {
         int count = event.getValue();
         // Handle pulse count...
     }
 
     public void stop() throws IOException, PeripheralNotAvailableException {
         if (counter != null) {
             counter.stopCounting();
             counter.close();
         }
     }
 }

Because of performance issue, procedures handling pulse counting events should be optimized to be as fast as possible.

Pulse counters are opened by invoking one of the com.oracle.deviceaccess.PeripheralManager.open() methods. The com.oracle.deviceaccess.counter permission allows access to be granted to pulse counter devices as a whole. This permission must be requested in the JAD file under MIDlet-Permissions or MIDlet-Permissions-Opt, and the application must be digitally signed by a trusted authority to gain access to the APIs. Alternatively, the permission may be allowed for all applications in the untrusted domain of the security policy file (policy.txt).

The PulseCounter Interface

The PulseCounter interface provides methods for controlling a pulse counter. A pulse counter can count pulses on a digital input line, possibly a GPIO pin.

A PulseCounter instance can be opened by a call to one of the PeripheralManager.open() methods. Once opened, an application can either start a pulse counting session using the startCounting() method and retrieve the current pulse count on-the-fly by calling the getCount() method; alternatively, it can start a pulse counting session with a terminal count value and a counting time interval using the startCounting(int, long, com.oracle.deviceaccess.counter.CountingListener) and get asynchronously notified once the terminal count value has been reached or the counting time interval has expired. In both cases, the application can retrieve the current pulse count at any time (on-the-fly) by calling the getCount() method.

The pulse counting session can be suspended by calling suspendCounting() and later on resumed from its previous count value by calling resumeCounting(). Suspending the pulse counting also suspends the session counting time interval timer if active. The pulse count value can be reset at anytime during counting by calling resetCounting(). This also resets the session counting time interval timer if active. Finally, the pulse counting can be stopped by calling stopCounting().

When an application is no longer using a pulse counter it should call the PulseCounter.close() method to release the pulse counter. Any further attempt to use a pulse counter which has been closed will result in a PeripheralNotAvailableException been thrown. Note that asynchronous notification of pulse counting conditions is only loosely tied to hardware-level interrupt requests. The platform does not guarantee notification in a deterministic or timely manner.

The PulseCounter interface contains seven methods.

int getCount() throws java.io.IOException, PeripheralNotAvailableException

This method returns the pulse count measured so far during the current or previous counting session.
void startCounting() throws java.io.IOException, PeripheralNotAvailableException

This method starts a pulse counting session. The pulse count value is reset to zero (0).
void startCounting(int limit, long interval, CountingListener listener) throws java.io.IOException, PeripheralNotAvailableException

This method starts an asynchronous pulse counting session. The provided CountingListener instance will be asynchronously invoked when the pulse count reaches the provided terminal count value or the specified counting time interval expires, whichever happens first. The pulse count value is first reset to zero (0), and will be reset every time the terminal count value is reached or the counting time interval expires.

If limit is equal or less than 0 then the counting time interval will end only after the time specified by interval has passed. If interval is equal to or less than 0, then the counting time interval will end only after the pulse count has reached the terminal count value specified by limit.

Pulse counting and notification will immediately start and will repeat until it is stopped by a call to stopCounting(). Only one pulse counting session can be going on at any time.
void resetCounting() throws java.io.IOException, PeripheralNotAvailableException

This method resets the current count value.
void stopCounting() throws java.io.IOException, PeripheralNotAvailableException

This method stops the pulse counting and freezes the current count value. The count value will be reset upon the next start.
void suspendCounting() throws java.io.IOException, PeripheralNotAvailableException

This method suspends the pulse counting and freezes the current count value.
void resumeCounting() throws java.io.IOException, PeripheralNotAvailableException

This method resumes the counting starting from the frozen count value.

The CountingEvent Class

The CountingEvent class encapsulates pulse counting conditions such as counter terminal value reached or counting session time interval expired. If counting events for the same pulse counter are coalesced the count value and the type (either the terminal value is reached or the time interval has expired) retained are that of the last occurrence.

The CountingEvent class consists of two constants, which describes the type:

public static final int TERMINAL_VALUE_REACHED

This constant indicates that the pulse count value has reached the defined terminal value.
public static final int INTERVAL_EXPIRED

This constant indicates that the pulse counting time interval has expired.

The CountingEvent class also consists of two constructors and three methods:

public CountingEvent(PulseCounter counter, int type, int value, long interval)

This constructor creates a new CountingEvent with the specified type, pulse count value and actual counting time interval. The event is then time-stamped with the current time.
public CountingEvent(PulseCounter counter, int type, int value, long interval, long timeStamp, int timeStampMicros)

This constructor creates a new CountingEvent with the specified type, pulse count value, actual counting time interval and timestamp.
public int getType()

This method returns the type of counting condition being notified.
public int getValue()

This method returns the pulse count value.
public long getInterval()

This method returns the actual counting time interval, in milliseconds. The actual counting time interval may be smaller than the defined counting time interval if the count terminal value has been reached.

The PulseCounterConfig Class

The PulseCounterConfig class encapsulates the hardware addressing information, as well as the static and dynamic configuration parameters of a pulse counter.

Some hardware addressing parameter, and static and dynamic configuration parameters may be set to PeripheralConfig.DEFAULT. Whether such default settings are supported is both platform-dependent and peripheral driver-dependent.

An instance of PulseCounterConfig can be passed to the PeripheralManager.open(PeripheralConfig) or PeripheralManager.open(Class, PeripheralConfig) method to open the designated counter with the specified configuration. A PeripheralConfigInvalidException is thrown when attempting to open a peripheral device with an invalid or unsupported configuration

There are four constants in this class.

public static final int TYPE_FALLING_EDGE_ONLY

This constants represents a falling pulse edge (counting only falling pulse edges).
public static final int TYPE_RISING_EDGE_ONLY

This constants represents a rising pulse edge (counting only rising pulse edges).
public static final int TYPE_POSITIVE_PULSE

This constants represents a positive edge pulse: measured from rising edge to falling edge (counting well-formed positive edge pulses).
public static final int TYPE_NEGATIVE_PULSE

This constants represents a negative edge pulse: measured from falling edge to rising edge (counting well-formed negative edge pulses).

There are two constructors and three methods in this class.

public PulseCounterConfig(int counterNumber, int type)

This constructor creates a new PulseCounterConfig with the specified hardware addressing information and type. The source of the pulse counter is implicit, such as a dedicated input pin.
public PulseCounterConfig(int counterNumber, int type, GPIOPinConfig source)

This constructor creates a new PulseCounterConfig with the specified hardware addressing information, type and GPIO pin source.
public int getCounterNumber()

This method returns the configured counter number.
public GPIOPinConfig getSource()

This method returns the configured input source on which the pulses are to be counted or measured.
public int getType()

This method returns the configured pulse or pulse edge type.