diozero

A device I/O library implemented in Java that is portable across Single Board Computers and micro-controllers to provide an intuitive and frictionless way to get started with physical computing.

Example:

try (LED led = new LED(18)) {
  led.on();
  SleepUtil.sleepSeconds(1);
  led.off();
  SleepUtil.sleepSeconds(1);
  led.toggle();
}

Components can easily be connected together, e.g.:

try (Button button = new Button(12); LED led = new LED(18)) {
  button.whenPressed(nanoTime -> led.on();
  button.whenReleased(nanoTime -> led.off());
  SleepUtil.sleepSeconds(20);
}

As well as providing APIs for interfacing directly with physical hardware (i.e. GPIO, I²C, SPI and Serial), diozero also provides support for simple devices including LDRs, Buttons, and Motors through to complex environmental sensors such as the Bosch Sensortec Gas Sensor BME60.

This library makes use of modern Java features such as automatic resource management, Lambda Expressions and Method References to simplify development and improve code readability.

Supported Boards

diozero has built-in support for the following Single Board Computers and micro-controllers. Its adoption of common userspace APIs means that it should work on all SBCs that can run Linux and all micro-controllers that can support the Firmata protocol.

Raspberry Pi (all versions + tested on Raspberry Pi OS 32-bit and 64-bit as well as Ubuntu Server 64-bit).
Odroid C2 (Armbian 64-bit) - Amlogic S905 SoC.
Odroid N2 (Armbian 64-bit) - Amlogic S922X SoC.
BeagleBone Green / Black.
ASUS TinkerBoard (ASUS TinkerOS/Linaro as well as Armbian 64-bit) - Rockchip RK3288 SoC.
Radxa Rock 4C+ - Rockchip RK3299/RK3299T SoC.
Allwinner H3 boards, including NanoPi Neo and NanoPi Duo 2 (Armbian 32-bit).
Allwinner H5 boards, e.g. OrangePi Zero+.
Allwinner H6 boards, e.g. OrangePi One+, Orange Pi 3 LTS
The Next Thing Co CHIP - Allwinner R8 SoC.
Arduino compatible (any device that can run Firmata).
Raspberry Pi Pico (Firmata over serial).
ESP8266 (via Firmata over Serial, Bluetooth or WiFi).
ESP32 (Firmata).
Particle Spark (using Voodoo Spark).

Usage

diozero requires Java 11 or later - it has been tested on all JDK versions from Java 11 through to 17. Most use cases will only require the diozero-core JAR file which has just one other dependency - tinylog.

The best way to use diozero is via a Maven dependency:

<dependency>
    <groupId>com.diozero</groupId>
    <artifactId>diozero-core</artifactId>
    <version>1.4.2</version>
</dependency>

You can initialise your own application using the diozero-application Maven archetype:

mvn archetype:generate -DinteractiveMode=false \
  -DarchetypeGroupId=com.diozero \
  -DarchetypeArtifactId=diozero-application \
  -DarchetypeVersion=1.4.2 \
  -DgroupId=com.mycompany \
  -DartifactId=mydiozeroproject \
  -Dversion=1.0-SNAPSHOT

A full distribution ZIP file containing all JARs and associated dependencies is also available from Maven Central - locate com.diozero:diozero-distribution, select a version and click the “bin.zip” option in the Downloads link top right. It is also available in mvnrepository by locating diozero-distribution, selecting a version and clicking the Files View All link.

Java 24 or later

Due to the low-level system access that is current implemented using JNI, the following error will be reported on start-up:

WARNING: A restricted method in java.lang.Runtime has been called
WARNING: java.lang.Runtime::load has been called by com.diozero.util.LibraryLoader in an unnamed module (file:diozero-core-1.4.2.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

To remove this warning, add --enable-native-access=ALL-UNNAMED to your application start-up script, e.g.

java --enable-native-access=ALL-UNNAMED -jar /home/blah/blah.jar

Articles

Development

Created by Matt Lewis (email deviceiozero@gmail.com) (blog), inspired by GPIO Zero and Johnny Five. If you have any issues, comments or suggestions please use the GitHub issues page.

This project is hosted on GitHub, please feel free to join in:

Make suggestions for fixes and enhancements
Provide sample applications and device implementation classes
Contribute to development

Release History

This work is provided under the MIT License.