Link Search Menu Expand Document

Concepts

diozero is a multi-faceted “library” for interacting with low-level devices such as environmental sensors and GPIOs. It achieves this via object-oriented APIs that abstract developers from the complexities of low-level device interface code. An initial motivation to developing diozero was to provide a Java equivalent to the excellent Python gpiozero library having found that existing Java libraries didn’t offer such a developer-friendly experience.

TODO - devices (LEDs, buttons, sensors, motors, displays, etc) that can be connected to Single Board Computers like the Raspberry Pi. Actual GPIO / I2C / SPI device communication is delegated to pluggable service providers for maximum compatibility across different boards. This library is known to work on the following boards: all models of the Raspberry Pi, Odroid C2, BeagleBone (Green and Black), C.H.I.P and ASUS Tinker Board. It should be portable to any Single Board computer that runs Linux and Java 8.

The aim of this library is to encapsulate real-world devices as classes with meaningful operation names, for example, LED (on / off), LDR (get luminosity), Button (pressed / released), Motor (forward / backwards / left / right).

Pin Numbering

All pin numbers are device native, i.e. Broadcom for the Raspberry Pi, ASUS for the Tinker Board. Pin layouts:

The library makes use of try-with-resources - all devices implement Closeable hence will get automatically closed by the try (Device d = new Device()) { d.doSomething(); } statement. This is best illustrated by some simple examples.

LED control:

try (LED led = new LED(18)) {
	led.toggle();
	SleepUtil.sleepSeconds(.5);
	led.toggle();
	SleepUtil.sleepSeconds(.5);
}

Turn on an LED when you press a button:

try (Button button = new Button(12); LED led = new LED(18)) {
	button.whenPressed(led::on);
	button.whenReleased(led::off);
	SleepUtil.sleepSeconds(10);
}

Or a random LED flicker effect:

Random random = new Random();
try (PwmLed led = new PwmLed(18)) {
	DioZeroScheduler.getNonDaemonInstance().invokeAtFixedRate(RANDOM::nextFloat, led::setValue, 50, 50, TimeUnit.MILLISECONDS);
}

Getting Started

Snapshot builds of the library are available in the Nexus Repository Manager. For convenience a ZIP of all diozero JARs (currently v1.0.1) will also be available on Google Drive.

Javadoc for the core library is also available via javadoc.io.

Unfortunately Java doesn’t provide a convenient deployment-time dependency manager such as Python’s pip therefore you will need to manually download all dependencies and setup your classpath correctly. You can do this either via setting the CLASSPATH environment variable or as a command-line option (java -cp <jar1>:<jar2>). The dependencies have been deliberately kept to as few libraries as possible, as such this library is only dependent on tinylog v2.1.2.

To compile a diozero application you will need 3 JAR files - tinylog (API and Impl), and diozero-core. To run a diozero application, you can also include one of the supported device provider libraries and the corresponding diozero provider wrapper library. Note that the built-in sysfs device provider gives maximum portability but has some limitations such as not being able to configure internal pull up/down resistors.

Provider Dependency diozero Provider Library SBC
built-in None Built-in All
mmap diozero system-utils-native diozero-provider-mmap-<version>.jar *
pigpio pigpioj-java diozero-provider-pigio Raspberry Pi (all flavours)
bbbiolib bbbiolib diozero-provider-bbiolib BeagleBone Green / Black
firmata firmata4j diozero-provider-firmata Arduino compatible boards
voodoospark None diozero-provider-voodoospark Arduino compatible boards

* MMAP is currently supported on the following SBCs:

  • Raspberry Pi
  • FriendlyArm H3 / Allwinner Sun8i CPU (as used in the NanoPi Duo2 / NanoPi Neo amongst others)
  • ASUS TinkerBoard
  • Odroid C2
  • Next Think Co CHIP (Allwinner sun4i/sun5i)

To get started I recommend first looking at the classes in com.diozero.sampleapps. To run the LEDTest sample application using the pigpioj provider:

sudo java -cp tinylog-api-2.1.2.jar:tinylog-impl-2.1.2.jar:diozero-core-0.13.jar:diozero-sampleapps-0.13.jar:diozero-provider-pigpio-0.13.jar:pigpioj-java-2.4.jar com.diozero.sampleapps.LEDTest 12

For an experience similar to Python where source code is interpreted rather than compiled try Groovy (sudo apt-get update && sudo apt-get install groovy2). With the CLASSPATH environment variable set as per the instructions above, a simple test application can be run via the command groovy <filename>. There is also a Groovy shell environment groovysh.

A Groovy equivalent of the LED controlled button example:

import com.diozero.Button
import com.diozero.LED
import com.diozero.util.SleepUtil

led = new LED(12)
button = new Button(25)

button.whenPressed({ led.on() })
button.whenReleased({ led.off() })

println("Waiting for button presses. Press CTRL-C to quit.")
SleepUtil.pause()

To run:

sudo groovy -cp $CLASSPATH test.groovy

Table of contents