ioio.lib.api
Interface PwmOutput

All Superinterfaces:
Closeable
All Known Implementing Classes:
PwmImpl

public interface PwmOutput
extends Closeable

A pin used for PWM (Pulse-Width Modulation) output.

A PWM pin produces a logic-level PWM signal. These signals are typically used for simulating analog outputs for controlling the intensity of LEDs, the rotation speed of motors, etc. They are also frequently used for controlling hobby servo motors. PwmOutput instances are obtained by calling IOIO.openPwmOutput(ioio.lib.api.DigitalOutput.Spec, int).

When used for motors and LEDs, a frequency of several KHz is typically used, where there is a trade-off between switching power-loses and smoothness of operation. The pulse width is typically set by specifying the duty cycle, with the setDutyCycle(float) method. A duty cycle of 0 is "off", a duty cycle of 1 is "on", and every intermediate value produces an intermediate intensity. Please note that any devices consuming more than 20mA of current (e.g. motors) should not by directly connected the the IOIO pins, but rather through an amplification circuit suited for the specific load.

When used for hobby servos, the PWM signal is rather used for encoding of the desired angle the motor should go to. By standard, a 100Hz signal is used and the pulse width is varied between 1ms and 2ms (corresponding to both extremes of the shaft angle), using setPulseWidth(int).

The instance is alive since its creation. If the connection with the IOIO drops at any point, the instance transitions to a disconnected state, in which every attempt to use the pin (except Closeable.close()) will throw a ConnectionLostException. Whenever Closeable.close() is invoked the instance may no longer be used. Any resources associated with it are freed and can be reused.

Typical usage (fading LED):

 PwmOutput servo = ioio.openPwmOutput(12, 1000);  // LED anode on pin 12
 ...
 servo.setDutyCycle(0.0f);  // LED off
 ... 
 servo.setDutyCycle(0.5f);  // 50% intensity
 ... 
 servo.setDutyCycle(1.0f);  // 100% intensity
 ... 
 servo.close();  // pin 12 can now be used for something else.
 

Typical usage (servo):

 PwmOutput servo = ioio.openPwmOutput(12, 100);
 ...
 servo.setPulseWidth(1000);  // 1000us = 1ms = one extreme
 ... 
 servo.setPulseWidth(1500);  // 1500us = 1.5ms = center
 ... 
 servo.setPulseWidth(2000);  // 2000us = 2ms = other extreme
 ... 
 servo.close();  // pin 12 can now be used for something else.
 

See Also:
IOIO.openPwmOutput(ioio.lib.api.DigitalOutput.Spec, int)

Method Summary
 void setDutyCycle(float dutyCycle)
          Sets the duty cycle of the PWM output.
 void setPulseWidth(float pulseWidthUs)
          The same as setPulseWidth(int), but with sub-microsecond precision.
 void setPulseWidth(int pulseWidthUs)
          Sets the pulse width of the PWM output.
 
Methods inherited from interface ioio.lib.api.Closeable
close
 

Method Detail

setDutyCycle

void setDutyCycle(float dutyCycle)
                  throws ConnectionLostException
Sets the duty cycle of the PWM output. The duty cycle is defined to be the pulse width divided by the total cycle period. For absolute control of the pulse with, consider using setPulseWidth(int).

Parameters:
dutyCycle - The duty cycle, as a real value from 0.0 to 1.0.
Throws:
ConnectionLostException - The connection to the IOIO has been lost.
See Also:
setPulseWidth(int)

setPulseWidth

void setPulseWidth(int pulseWidthUs)
                   throws ConnectionLostException
Sets the pulse width of the PWM output. The pulse width is duration of the high-time within a single period of the signal. For relative control of the pulse with, consider using setDutyCycle(float).

Parameters:
pulseWidthUs - The pulse width, in microsecond units.
Throws:
ConnectionLostException - The connection to the IOIO has been lost.
See Also:
setDutyCycle(float)

setPulseWidth

void setPulseWidth(float pulseWidthUs)
                   throws ConnectionLostException
The same as setPulseWidth(int), but with sub-microsecond precision.

Throws:
ConnectionLostException