Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mattjlewis/pigpioj
Java JNI wrapper around the pigpio C library
https://github.com/mattjlewis/pigpioj
hacktoberfest java pigpio pigpiod raspberry-pi
Last synced: about 2 months ago
JSON representation
Java JNI wrapper around the pigpio C library
- Host: GitHub
- URL: https://github.com/mattjlewis/pigpioj
- Owner: mattjlewis
- Created: 2016-02-01T12:22:59.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2022-03-16T09:21:59.000Z (almost 3 years ago)
- Last Synced: 2024-10-11T11:58:25.523Z (2 months ago)
- Topics: hacktoberfest, java, pigpio, pigpiod, raspberry-pi
- Language: Java
- Homepage:
- Size: 927 KB
- Stars: 22
- Watchers: 4
- Forks: 7
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# About
pigpioj is a Java wrapper around the excellent Raspberry Pi C library [pigpio](http://abyz.me.uk/rpi/pigpio/).
Note that the primary driver for developing pigpioj was to provide an optimised hardware interface
library for the platform and device independent library [diozero](http://www.diozero.com).
Make sure pigpio is installed on your Raspberry Pi:
```shell
sudo apt update && sudo apt -y install pigpio pigpiod pigpio-tools
```
pigpioj has two modes of operation:
1. JNI
1. Remote sockets
## JNI
The JNI mode requires a small system library to be loaded at runtime that allows Java to invoke the
[pigpio C interface](http://abyz.me.uk/rpi/pigpio/cif.html). This library is packaged in the pigpioj
JAR file and is loaded automatically when [uk.pigpioj.PigpioJ.getImplementation()](https://github.com/mattjlewis/pigpioj/blob/3e274d46892d58e4be38d454c031d50a4e31ef81/pigpioj-java/src/main/java/uk/pigpioj/PigpioJ.java#L9)
is invoked.
pigpioj provides native libraries that are compiled for ARMv6, ARMv7 and AArch64 CPU architectures
which are bundled within the pigpioj JAR file itself. At startup, pigpioj will detect the CPU
architecture and dynamically load the appropriate JNI library. It will first look for libpigpioj.so
on the Java library path, if not found it will extract the library from within the JAR file itself
via a temporary file that is automatically deleted once loaded.
The optimisations within pigpio (using `/dev/mem`) unfortunately requires root access.
Because of this all pigpioj applications that use the default JNI mode must be run as root.
In addition, the pigpio shared library must be installed on the Raspberry Pi; it can be installed by
running:
```shell
sudo apt update && sudo apt -y install libpigpio1 libpigpiod-if2-1
```
In addition, the pigpiod daemon process must not be running:
```shell
sudo systemctl stop pigpiod.service
```
The pigpiod daemon process can be disabled from automatically starting on a reboot:
```shell
sudo systemctl disable pigpiod.service
```
### Running on Ubuntu
At the time of writing, the Ubuntu 64-bit operating system for Raspberry Pi didn't include the
pigpio packages, hence must be built and installed from source code.
Clone the [pigpio GitHub repository](https://github.com/joan2937/pigpio), build and install it.
```shell
sudo apt update && sudo apt -y install git make gcc
git clone https://github.com/joan2937/pigpio.git --depth=1
cd pigpio
make
sudo make install
```
### PWM / PCM / I2S / pigpio Conflicts
As per this [pigpio issue](https://github.com/joan2937/pigpio/issues/87), by default pigpio uses the
Pi's PCM hardware to time DMA transfers. pigpio can be configured to use the PWM hardware instead of
the PCM hardware by calling `gpioCfgClock` before `gpioInitialise`. To enable this in pigpioj, the
following variables must be set, either via command line or as environment variables:
* PIGPIO_CLOCK_CFG_MICROS
* PIGPIO_CLOCK_CFG_PERIPHERAL
### Building the Native Library
If you need to compile the JNI library yourself you can do so either using a physical Raspberry Pi,
or via the pigpioj Docker based cross compiler.
#### Building via Docker
Clone pigpioj, build the Docker image and initiate the docker build process:
```shell
git clone [email protected]:mattjlewis/pigpioj.git
cd pigpioj/pigpioj-native/docker
docker build -t diozero/pigpioj-cc .
cd ..
./docker_build.sh
```
Once successful, this will result in the following folder structure:
```
lib
├── linux-aarch64
│ └── libpigpioj.so
├── linux-armv6
│ └── libpigpioj.so
└── linux-armv7
└── libpigpioj.so
```
#### Building on a Raspberry Pi
Make sure that the pigpio development tools are installed:
```shell
sudo apt update && sudo apt -y install libpigpiod-if-dev
```
Unfortunately `pigpio.h` is not included in any of the Raspberry Pi OS packages, first of all run
this command in the Pi user's home directory (the Makefile assumes the header files are in
`/home/pi/pigpio`):
```shell
sudo apt update && sudo apt -y install git make gcc
git clone https://github.com/joan2937/pigpio.git --depth=1
cd pigpio
make
```
Copy the pigpioj-native source files to the Raspberry Pi and compile with `make`.
```shell
git clone [email protected]:mattjlewis/pigpioj.git
cd pigpioj/pigpioj-native/src/main/native
make
```
This will produce a libpigpioj.so shared object library that needs to be made available on the
Java library path at runtime.
## Sockets
By default pigpioj uses JNI mode; to switch to the remote socket mode you must set the `PIGPIOD_HOST`
variable, either via environment property or Java command line property. Examples:
Command line:
```shell
java -DPIGPIOD_HOST=«your-pigpiod-host» -cp pigpioj-2.5.11.jar:«your-app.jar» «your-main-class»
```
Environment variable:
```shell
export PIGPIOD_HOST=