public interface PWMChannel extends Peripheral<PWMChannel>, BufferAccess<java.nio.IntBuffer>
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
PeripheralManager.open(id,...)
methods using its ID or by a call to one of the
PeripheralManager.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
PeripheralManager.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
ClosedPeripheralException
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.GenerationListener
,
PWMPermission
BIG_ENDIAN, LITTLE_ENDIAN, MIXED_ENDIAN
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) . |
int |
getMinPulsePeriod()
Gets the minimum pulse period of this PWM channel (in microseconds) that can bet set by a call to
setPulsePeriod(int) . |
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 sucessive 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 sucessive 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.
|
close, getDescriptor, isOpen, tryLock, unlock
getInputBuffer, getOutputBuffer
void setPulsePeriod(int period) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
period
- the pulse period as a period in microseconds.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.InvalidPulseRateException
- if the resulting pulse rate/frequency (i.e.: 1/period) is higher than the maximum supported
pulse rate/frequency (i.e.: 1/getMinPulsePeriod()
).java.lang.IllegalArgumentException
- if period
is negative or zero.int getPulsePeriod() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setPulsePeriod(int)
the peripheral configuration-specific default value is returned.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getMaxPulsePeriod() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setPulsePeriod(int)
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.int getMinPulsePeriod() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
setPulsePeriod(int)
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.void generate(int width, int count) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.width
- the pulse width (in microseconds).count
- the maximum number of pulses to generate.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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if an asynchronous pulse generation session is already active.void generate(java.nio.IntBuffer src) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.src
- the buffer from which the pulse width integer values can be retrieved.java.io.IOException
- if some other I/O error occurs.java.lang.NullPointerException
- If src
is null
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if an asynchronous pulse generation is already active.void startGeneration(int width) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.width
- the pulse width (in microseconds).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.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous generation is already active.void startGeneration(int width, int count, GenerationListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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.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.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
.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous generation is already active.void startGeneration(java.nio.IntBuffer src, GenerationRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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
frome that very same buffer upon invocation od the provided GenerationRoundListener
instance.
Pulse generation can be stopped by a call to stopGeneration()
.
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.
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.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.java.lang.NullPointerException
- If src
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output generation is already active.void startGeneration(java.nio.IntBuffer src1, java.nio.IntBuffer src2, GenerationRoundListener listener) throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
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 working buffer and generation will proceed with the alternate buffer (which will become the
working buffer). Generation will only be suspended if the previous event has not yet been handled.
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.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.java.lang.NullPointerException
- If src1
, src2
or listener
is null
.java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.java.lang.IllegalStateException
- if another synchronous or asynchronous output generation is already active.void stopGeneration() throws java.io.IOException, UnavailablePeripheralException, ClosedPeripheralException
java.io.IOException
- if some other I/O error occurs.UnavailablePeripheralException
- if this peripheral is not currently available - such as it is locked by another application.ClosedPeripheralException
- if the peripheral has been closed.Copyright © 2012, 2013, Oracle and/or its affiliates. All rights reserved.
Legal Notices