API

Base classes

GpioDevice

class com.diozero.api.GpioDevice (gpio) source

Abstract base class for all GPIO related devices.

  • gpio (int) - GPIO to which the device is connected.
int getGpio ()

Get the GPIO for this device.

Input Devices

GpioInputDevice

class com.diozero.api.GpioInputDevice (gpio) source

Common base class for digital and analog input devices, extends GpioDevice.

  • gpio (int) - GPIO to which the device is connected.
addListener (listener)

Add a new listener.

  • listener (InputEventListener<T extends DeviceEvent>) - Callback instance.
removeListener (listener)

Remove a specific listener.

  • listener (InputEventListener<T extends DeviceEvent>) - Callback instance to remove.
removeAllListeners ()

Remove all listeners.

DigitalInputDevice

class com.diozero.api.DigitalInputDevice (gpio, pud=NONE, trigger=BOTH) source

Extends GpioInputDevice to provide common support for digital devices.

  • gpio (int) - GPIO to which the device is connected.

  • pud (GpioPullUpDown) - Pull up/down configuration, values: NONE, PULL_UP, PULL_DOWN. Defaults to NONE.

  • trigger (GpioEventTrigger) - Event trigger configuration, values: NONE, RISING, FALLING, BOTH. Defaults to BOTH.

GpioPullUpDown getPullUpDown ()

Get pull up / down configuration.

GpioEventTrigger getTrigger ()

Get event trigger configuration.

boolean isActiveHigh ()

Returns false if configured as pull-up, true for all other pull up / down options.

boolean getValue ()

Read the current underlying state of the input pin. Does not factor in active high logic.

boolean isActive ()

Read the current on/off state for this device taking into account the pull up / down configuration. If the input is pulled up isActive () will return true when when the value is false.

whenActivated (action)

Action to perform when the device state is active.

  • action (Action) - Action callback object.
whenDectivated (action)

Action to perform when the device state is inactive.

  • action (Action) - Action callback object.

WaitableDigitalInputDevice

class com.diozero.api.WaitableDigitalInputDevice (gpio, pud=NONE, trigger=BOTH) source

Extends DigitalInputDevice to support waiting for state changes.

  • gpio (int) - GPIO to which the device is connected.

  • pud (GpioPullUpDown) - Pull up/down configuration, values: NONE, PULL_UP, PULL_DOWN.. Defaults to NONE.

  • trigger (GpioEventTrigger) - Event trigger configuration, values: NONE, RISING, FALLING, BOTH. Defaults to BOTH.

waitForActive (timeout=0)

Wait for the specified time period (in millieconds) for the device to go active.

  • timeout (int) - Timeout value in milliseconds. Timeout values <= 0 represent an indefinite amount of time.
waitForInactive (timeout=0)

Wait for the specified time period (in millieconds) for the device to go inactive.

  • timeout (int) - Timeout value in milliseconds. Timeout values <= 0 represent an indefinite amount of time.
waitForValue (value, timeout)

Wait for a specific input high / low state.

  • timeout (int) - Timeout value in milliseconds. Timeout values <= 0 represent an indefinite amount of time.

SmoothedInputDevice

class com.diozero.api.SmoothedInputDevice (gpio, pud, threshold, eventAge, eventDetectPeriod) source

Represents a generic input device which takes its value from the number of active events over a specific time period. This class extends WaitableDigitalInputDevice with a queue which is added to whenever the input device is active. The number of the active events in the queue is compared to a threshold which is used to determine the state of the 'active' property. Any active events over the specified eventAge are removed by a background thread. This class is intended for use with devices which exhibit "twitchy" behaviour (such as certain motion sensors).

  • gpio (int) - GPIO to which the device is connected.

  • pud (GpioPullUpDown) - Pull up/down configuration, values: NONE, PULL_UP, PULL_DOWN.

  • threshold (int) - The value above which the device will be considered "on".

  • eventAge (int) - The time in milliseconds to keep items in the queue.

  • eventDetectPeriod (int) - How frequently to check for events.

int getThreshold ()

If the number of on events younger than age exceeds this amount, then isActive will return true.

setThreshold (threshold)

Set the threshold.

  • threshold (int) - New threshold value in terms of number of on events within the specified time period that will trigger an on event to any listeners.
int getEventAge ()

The time in milliseconds to keep items in the queue.

setEventAge (eventAge)

Set the event age (milliseconds).

  • eventAge (int) - New event age value (milliseconds).
int getEventDetectPeriod ()

How frequently (in milliseconds) to check the state of the queue.

AnalogInputDevice

The AnalogInputDevice base class encapsulates logic for interfacing with analog devices. This class provides access to unscaled (-1..1) and scaled (e.g. voltage, temperature, distance) readings. For scaled readings is important to pass the ADC voltage range in the device constructor - all raw analog readings are normalised (i.e. -1..1).

Analog Device Support

Note the Raspberry Pi does not natively support analog input devices, see expansion boards for connecting to analog-to-digital converters.

Example: Temperature readings using an MCP3008 and TMP36:

MCP3008 TMP36

Code taken from TMP36Test:

try (McpAdc adc = new McpAdc(McpAdc.Type.MCP3008, chipSelect);
        TMP36 tmp36 = new TMP36(adc, pin, vRef, tempOffset)) {
    for (int i=0; i<ITERATIONS; i++) {
        double tmp = tmp36.getTemperature();
        Logger.info("Temperature: {}", String.format("%.2f", Double.valueOf(tmp)));
        SleepUtil.sleepSeconds(.5);
    }
}
class com.diozero.api.AnalogInputDevice (gpio, range){: .descname } source

Extends GpioInputDevice to provide common support for analog devices.

  • gpio (int) - GPIO to which the device is connected.

  • range (float) - To be used for taking scaled readings for this device.

float getUnscaledValue ()

Get the unscaled normalised value in the range 0..1 (if unsigned) or -1..1 (if signed).

float getScaledValue ()

Get the scaled value in the range 0..range (if unsigned) or -range..range (if signed).

addListener (listener, percentChange, pollInterval=50)

Register a listener for value changes.

  • listener (InputEventListener<AnalogInputEvent>) - The listener callback.

  • percentChange (float) - Degree of change required to trigger an event.

  • pollInterval (int=50) - Time in milliseconds at which reading should be taken.

DigitalInputOutputDevice

class com.diozero.api.DigitalInputOutputDevice (gpio, mode) source

Extends GpioDevice that allows switching between input and output modes. Note currently only provides basic get/set functionality.

  • gpio (int) - GPIO pin to which the output device is connected.

  • mode (DeviceMode) - Initial input / output mode.

DeviceMode getMode ()

Get the current input / output mode.

setMode (mode)

Change input / output mode.

mode (DeviceMode) - new mode for the device.

boolean getValue ()

Get the current device state.

setValue (value)

Set the output value.

value (boolean) - output on/off state.

Output Devices

DigitalOutputDevice

class com.diozero.api.DigitalOutputDevice (gpio, activeHigh=true, initialValue=false) source

Extends GpioDevice to provide generic digital (on/off) output control.

  • gpio (int) - GPIO pin to which the output device is connected.

  • activeHigh (boolean) - If true then setting the value to true will turn on the connected device.

  • initialValue (boolean) - Initial output value.

on ()

Turn on the device.

off ()

Turn off the device.

toggle ()

Toggle the state of the device.

boolean isOn ()

Returns true if the device is currently on.

setOn (on)

Turn the device on or off.

  • on (boolean) - New on/off value.
setValueUnsafe (value)

Unsafe operation that has no synchronisation checks and doesn't factor in active low logic. Included primarily for performance tests.

  • value (boolean) - New value, true == on, false == off.
onOffLoop (ontime, offTime, n, background)

Toggle the device on-off.

  • onTime (float) - On time in seconds.

  • offtime (float) - Off time in seconds.

  • n (int) - Number of iterations. Set to -1 to blink indefinitely.

  • background (boolean) - If true start a background thread to control the blink and return immediately. If false, only return once the blink iterations have finished.

PwmOutputDevice

class com.diozero.api.PwmOutputDevice (gpio, initialValue=0) source

Extends GpioDevice to provide generic Pulse Width Modulation (PWM) output control.

  • gpio (int) - GPIO pin to which the output device is connected.

  • initialValue (float) - Initial output value (0..1).

float getValue ()

Get the current PWM output value (0..1).

setValue (value)

Set the PWM output value (0..1).

  • value (float) - the new PWM output value (0..1).
on ()

Turn on the device (same as setValue(1)).

off ()

Turn off the device (same as setValue(0)).

toggle ()

Toggle the state of the device (same as setValue(1 - getValue()).

boolean isOn ()

Returns true if the device currently has a value > 0.

I2C Support

class com.diozero.api.I2CDevice (controller, address, addressSize, clockFrequency, byteOrder) source

Class for reading / writing to I2C devices.

  • controller (int) - I2C bus.

  • address (int) - I2C device address.

  • addressSize (int) - I2C device address size. Can be 7 or 10.

  • clockFrequency (int) - I2C clock frequency.

  • byteOrder (int) - The ByteOrder to use when sending data to this device.

SPI Support

class com.diozero.api.SpiDevice (controller, chipSelect, frequency, mode, lsbFirst) source

Class for reading / writing to SPI devices.

  • controller (int) - SPI controller.

  • chipSelect (int) - Chip Select, aka Chip Enable.

  • frequency (int) - SPI frequency in HZ.

  • mode (SpiClockMode) - SPI clock mode to be used, 1 for each combination of Clock Polarity / Clock Phase. See Wikiepedia for further information.

  • lsbFirst (boolean) - Byte order to use in communication.

write (out)

Write data to the device.

  • out (ByteBuffer) - the data to write.
ByteBuffer writeAndRead (out)

Write and then read data to the device in the same transaction. The number of bytes read is the same as that written. Maximum output buffer size is 2048 bytes.

  • out (ByteBuffer) - the data to write.