jdk.dio.pwm

Interface PWMChannel

All Superinterfaces:

java.lang.AutoCloseable, BufferAccess<java.nio.IntBuffer>, java.nio.channels.Channel, java.io.Closeable, Device<PWMChannel>

public interface PWMChannel
extends Device<PWMChannel>, BufferAccess<java.nio.IntBuffer>

The PWMChannel interface provides methods for controlling a PWM (Pulse Width Modulation) signal generator channel.

One PWM generator/controller can have several channels. A PWM channel can generate pulses on a digital output line (possibly a GPIO pin).

A PWM channel may be identified by the numerical ID and by the name (if any defined) that correspond to its registered configuration. A PWMChannel instance can be opened by a call to one of the DeviceManager.open(id,...) methods using its ID or by a call to one of the DeviceManager.open(name,...) methods using its name. When a PWMChannel instance is opened with an ad-hoc PWMChannelConfig configuration (which includes its hardware addressing information) using one of the DeviceManager.open(config,...) it is not assigned any ID nor name.

Once opened, an application can set the pulse period using the setPulsePeriod(int) and then generate a certain number of pulses of a specified width by calling one of the generate(int, int) methods.

An application can also asynchronously generate a train of pulses either of a specified width up to a specified maximum count or from widths specified in a buffer by calling one of the startGeneration methods with a GenerationListener instance which will get notified upon completion. Such an asynchronous pulse generation can be stopped or canceled by calling the stopGeneration method.

Only one output/generation operation (synchronous or asynchronous) can be going on at any time.

When an application is no longer using a PWM channel it should call the PWMChannel.close method to close the PWM channel. Any further attempt to use a PWM channel which has been closed will result in a ClosedDeviceException been thrown.

Note that upon opening a PWM channel the default pulse width and duty cycle are always 0 and that the idle state is platform or configuration-specific.

See Also:

GenerationListener, PWMPermission

Field Summary

Fields inherited from interface jdk.dio.Device

BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN

Method Summary

Methods

Modifier and Type	Method and Description
void	generate(java.nio.IntBuffer src) Generates a pulse train containing count pulses of the specified widths.
void	generate(int width, int count) Generates a pulse train containing the specified count of pulses of the specified width.
int	getMaxPulsePeriod() Gets the maximum pulse period of this PWM channel (in microseconds) that can bet set by a call to setPulsePeriod.
int	getMinPulsePeriod() Gets the minimum pulse period of this PWM channel (in microseconds) that can bet set by a call to setPulsePeriod.
int	getPulsePeriod() Gets the pulse period of this PWM channel (in microseconds).
void	setPulsePeriod(int period) Sets the pulse period of this PWM channel.
void	startGeneration(int width) Starts an asynchronous pulse train generation session - continuously generating pulses of the specified width until explicitly stopped.
void	startGeneration(java.nio.IntBuffer src, GenerationRoundListener listener) Starts asynchronous pulse train generation in successive rounds - initially generating pulses of the specified widths up to the specified initial count - as indicated by the number of remaining elements in the provided buffer.
void	startGeneration(java.nio.IntBuffer src1, java.nio.IntBuffer src2, GenerationRoundListener listener) Starts asynchronous pulse train generation in successive rounds.
void	startGeneration(int width, int count, GenerationListener listener) Starts an asynchronous pulse train generation session - generating pulses of the specified width up to the specified count.
void	stopGeneration() Stops (cancels) the currently active pulse generation session.

Methods inherited from interface jdk.dio.Device

close, getDescriptor, isOpen, tryLock, unlock

Methods inherited from interface jdk.dio.BufferAccess

getInputBuffer, getOutputBuffer

Method Detail

setPulsePeriod

void setPulsePeriod(int period)
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Sets the pulse period of this PWM channel.

Parameters:

period - the pulse period as a period in microseconds.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

InvalidPulseRateException - if the resulting pulse rate/frequency (i.e.: 1/period) is either higher than the maximum supported pulse rate/frequency (i.e.: 1/getMinPulsePeriod) or lower than the minimum supported pulse rate/frequency (i.e.: 1/getMaxPulsePeriod)

java.lang.IllegalArgumentException - if period is negative or zero.

getPulsePeriod

int getPulsePeriod()
                   throws java.io.IOException,
                          UnavailableDeviceException,
                          ClosedDeviceException

Gets the pulse period of this PWM channel (in microseconds). If the pulse period was not set previously using setPulsePeriod the device configuration-specific default value is returned.

Returns:

the pulse period (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMaxPulsePeriod

int getMaxPulsePeriod()
                      throws java.io.IOException,
                             UnavailableDeviceException,
                             ClosedDeviceException

Gets the maximum pulse period of this PWM channel (in microseconds) that can bet set by a call to setPulsePeriod.

Returns:

the maximum pulse period (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

getMinPulsePeriod

int getMinPulsePeriod()
                      throws java.io.IOException,
                             UnavailableDeviceException,
                             ClosedDeviceException

Gets the minimum pulse period of this PWM channel (in microseconds) that can bet set by a call to setPulsePeriod.

Returns:

the minimum pulse period (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

generate

void generate(int width,
            int count)
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Generates a pulse train containing the specified count of pulses of the specified width.

To generate pulses of a specific duty cycle dutyCycle, this method may be called as follows:

 float dutyCycle = 0.5f;
 pwmChannel.generate((pwmChannel.getPulsePeriod() * dutyCycle), count);
 

The operation will return only after generating all of the count requested pulses.

The pulses will be generated according to the current pulse period as returned by getPulsePeriod.

This method may be invoked at any time. If another thread has already initiated a synchronous output operation upon this channel then an invocation of this method will block until the first operation is complete.

Only one output operation (synchronous or asynchronous) can be going on at any time.

Parameters:

width - the pulse width (in microseconds).

count - the maximum number of pulses to generate.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if width or count is equal to or less than 0 or if width is greater than the currently set period.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if an asynchronous pulse generation session is already active.

generate

void generate(java.nio.IntBuffer src)
              throws java.io.IOException,
                     UnavailableDeviceException,
                     ClosedDeviceException

Generates a pulse train containing count pulses of the specified widths. The provded buffer contains the widths of the pulses to generate.

r pulses will be generated by this channel, where r is the number of integers (pulse widths) remaining in the buffer, that is, src.remaining(), at the moment this method is invoked.

Suppose that a pulse width integer value sequence of length n is provided, where 0 <= n <= r . The sequence starts at index p, where p is the buffer's position at the moment this method is invoked; the index of the last pulse width integer value written will be p + n - 1. Upon return the buffer's position will be equal to p + n; its limit will not have changed.

The operation will return only after generating all of the r requested pulses.

The pulses will be generated according to the current pulse period as returned by getPulsePeriod.

This method may be invoked at any time. If another thread has already initiated a synchronous pulse generation upon this channel, however, then an invocation of this method will block until the first operation is complete.

Only one pulse generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated pulse width values is greater than the currently set period. If a pulse width value is not within range the actual width of the pulse generated by the PWM device is hardware- or driver-specific: the pulse width may for example be equal to the set period, corresponding to a 100% duty cycle.

Parameters:

src - the buffer from which the pulse width integer values can be retrieved.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.NullPointerException - If src is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if an asynchronous pulse generation is already active.

startGeneration

void startGeneration(int width)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts an asynchronous pulse train generation session - continuously generating pulses of the specified width until explicitly stopped.

The pulses will be generated according to the current pulse period as returned by getPulsePeriod.

Pulse generation will immediately start and proceed asynchronously. It may be stopped prior to completion by a call to stopGeneration.

Only one pulse generation session can be going on at any time.

Parameters:

width - the pulse width (in microseconds).

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if width is equal to or less than 0 or if width is greater than the currently set period.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous generation is already active.

startGeneration

void startGeneration(int width,
                   int count,
                   GenerationListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts an asynchronous pulse train generation session - generating pulses of the specified width up to the specified count. The provided GenerationListener instance will be invoked upon completion, that is when the count of generated pulses reaches the specified count value.

The pulses will be generated according to the current pulse period as returned by getPulsePeriod.

Pulse generation will immediately start and proceed asynchronously. It may be stopped prior to completion by a call to stopGeneration.

Only one pulse generation session can be going on at any time.

Parameters:

width - the pulse width (in microseconds).

count - the maximum number of pulses to generate.

listener - the GenerationListener instance to be notified when the count of generated pulses reaches the specified count value.

Throws:

java.io.IOException - if some other I/O error occurs.

java.lang.IllegalArgumentException - if count is equal to or less than 0 or if width is equal to or less than 0 or if width is greater than the currently set period.

java.lang.NullPointerException - if listener is null.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous generation is already active.

startGeneration

void startGeneration(java.nio.IntBuffer src,
                   GenerationRoundListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts asynchronous pulse train generation in successive rounds - initially generating pulses of the specified widths up to the specified initial count - as indicated by the number of remaining elements in the provided buffer. Additional rounds are asynchronously fetched by notifying the provided GenerationRoundListener instance once the initial count of pulses have been generated. The widths of the initial pulses to be generated are read from the provided buffer; the widths of the pulses to generate during the subsequent rounds are read from that very same buffer upon invocation of the provided GenerationRoundListener instance.

Pulse generation can be stopped by a call to stopGeneration.

r integers will be written to this channel, where r is the number of integers remaining in the buffer (possibly 0), that is, src.remaining(), at the moment this method is initially invoked and then subsequently when the listener is returning.

Suppose that an integer sequence of length n is written, where 0 <= n <= r. This integer sequence will be transferred from the buffer starting at index p, where p is the buffer's position at the moment this method is invoked and then subsequently when the listener is returning; the index of the last integer written will be p + n - 1. Upon invocation of the listener to fetch the widths of more pulses to generate the buffer's position will be equal to p + n; its limit will not have changed.
The buffer's position upon stopping this asynchronous operation by a call to stopGeneration is not predictable unless called from within the listener.

The pulses will be generated according to the current pulse period as returned by getPulsePeriod. The pulse period can be changed by the provided GenerationRoundListener instance upon notification of each pulse train subsequence.

Note that a buffer with 0 integers remaining to be written (that is a buffer already empty), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Interfering with the asynchronous operation by accessing and modifying the provided buffer concurrently may yield unpredictable results.

Only one pulse generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated pulse width values is greater than the currently set period. If a pulse width value is not within range the actual width of the pulse generated by the PWM device is hardware- or driver-specific: the pulse width may for example be equal to the set period, corresponding to a 100% duty cycle.

Parameters:

src - the buffer for the widths (in microseconds) of the pulses to generate.

listener - the GenerationRoundListener instance to be notified when pulses have been geneerated for all the width values remaining in the buffer.

Throws:

java.lang.NullPointerException - If src or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous output generation is already active.

startGeneration

void startGeneration(java.nio.IntBuffer src1,
                   java.nio.IntBuffer src2,
                   GenerationRoundListener listener)
                     throws java.io.IOException,
                            UnavailableDeviceException,
                            ClosedDeviceException

Starts asynchronous pulse train generation in successive rounds.

This method behaves identically to startGeneration(IntBuffer, GenerationRoundListener) excepts that it uses double-buffering. Notification will happen when pulses have been generated for all the width values remaining in the current working buffer (initially src1) and generation will proceed with the alternate buffer (which will become the current working buffer). Generation will only be suspended if the previous event has not yet been handled.

Note that a working buffer with 0 integers remaining to be written (that is a buffer already empty), at the moment this method is initially invoked or then subsequently when the listener is returning will not stop the asynchronous operation; the listener is guaranteed to be called back again at the latest as soon as all other events pending at the time of notification have been dispatched.

Only one pulse generation (synchronous or asynchronous) can be going on at any time.

Note that this method does not throw an IllegalArgumentException if any of the designated pulse width values is greater than the currently set period. If a pulse width value is not within range the actual width of the pulse generated by the PWM device is hardware- or driver-specific: the pulse width may for example be equal to the set period, corresponding to a 100% duty cycle.

Parameters:

src1 - the first buffer for the widths (in microseconds) of the pulses to generate.

src2 - the second buffer for the widths (in microseconds) of the pulses to generate.

listener - the GenerationRoundListener instance to be notified when pulses have been geneerated for all the width values remaining in the working buffer.

Throws:

java.lang.NullPointerException - If src1, src2 or listener is null.

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.

java.lang.IllegalStateException - if another synchronous or asynchronous output generation is already active.

stopGeneration

void stopGeneration()
                    throws java.io.IOException,
                           UnavailableDeviceException,
                           ClosedDeviceException

Stops (cancels) the currently active pulse generation session.

This method return silently if no pulse generation session is currently active.

Throws:

java.io.IOException - if some other I/O error occurs.

UnavailableDeviceException - if this device is not currently available - such as it is locked by another application.

ClosedDeviceException - if the device has been closed.