Link Search Menu Expand Document
diozero

Getting Started

Snapshot builds of the library are available in the Nexus Repository Manager. A ZIP file of diozero and all dependencies can also be downloaded via the diozero-distribution artifact on Nexus.

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

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; diozero core has only one dependency - tinylog v2.

To compile a diozero application you will need 3 JAR files - tinylog (both API and Impl), and diozero-core. To run a diozero application, you can also optionally include one of the supported device provider libraries and the corresponding diozero provider wrapper library. Note that the built-in default device provider gives maximum portability but has some limitations such as not supporting hardware PWM on the Raspberry Pi without using the sysfs PWM kernel module. If you need hardware PWM on a Raspberry Pi then you must use the pigpio provider.

Memory Mapped GPIO Control (mmap)

Very high performance GPIO control can be achieved by directly accessing the GPIO registers via the /dev/gpiomem device file. The built-in default provider makes use of this feature, allowing it to achieve GPIO toggle rates as high as 24MHz on the Raspberry Pi 4.

mmap is currently supported on the following SBCs:

  • Raspberry Pi (all variants)
  • FriendlyArm / Allwinner H3 Sun8i CPU (as used in the NanoPi Duo2 / NanoPi Neo amongst others)
  • OrangePi Zero+ (Allwinner H5) / One+ (Allwinner H6)
  • ASUS TinkerBoard
  • Odroid C2
  • Next Think Co CHIP (Allwinner sun4i/sun5i)

Some boards / Operating Systems may require you to run as root to access this file.

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.5.0.jar:tinylog-impl-2.5.0.jar:diozero-core-1.4.1.jar:diozero-sampleapps-1.4.1.jar:diozero-provider-pigpio-1.4.1.jar:pigpioj-java-2.6.1.jar com.diozero.sampleapps.LEDTest 12

For an experience similar to Python where source code is interpreted rather than compiled try Groovy (sudo apt update && sudo apt install groovy). 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.devices.Button
import com.diozero.devices.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.sleepSeconds(5)

To run:

sudo groovy -cp $CLASSPATH test.groovy