diff --git a/README.md b/README.md index 5e57ad8..77a271a 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,130 @@ This project contains both example applications and ready-made component classes [CrowPi](https://www.elecrow.com/crowpi-compact-raspberry-pi-educational-kit.html) using the Pi4J (V2) library. You can easily get started with electronics programming by testing and modifying the bundled examples or even write your own application. +## COMPONENTS + +The provided component classes as part of this library provide an implementation for every available component of the CrowPi. The following +table provides an overview of all supported components with a link to their implementation and example app: + +| **Component** | **Example App** | **Implementation** | +|---|---|---| +| Button | [ButtonApp.java](src/main/java/com/pi4j/crowpi/applications/ButtonApp.java) | [ButtonComponent.java](src/main/java/com/pi4j/crowpi/components/ButtonComponent.java) | +| ButtonMatrix | [ButtonApp.java](src/main/java/com/pi4j/crowpi/applications/ButtonApp.java) | [ButtonComponent.java](src/main/java/com/pi4j/crowpi/components/ButtonMatrixComponent.java) | +| Buzzer | [BuzzerApp.java](src/main/java/com/pi4j/crowpi/applications/BuzzerApp.java) | [BuzzerComponent.java](src/main/java/com/pi4j/crowpi/components/BuzzerComponent.java) | +| Humidity/Temperature Sensor | [HumiTempApp.java](src/main/java/com/pi4j/crowpi/applications/HumiTempApp.java) | [HumiTempComponent.java](src/main/java/com/pi4j/crowpi/components/HumiTempComponent.java) | +| IR Receiver | [IrReceiverApp.java](src/main/java/com/pi4j/crowpi/applications/IrReceiverApp.java) | [IrReceiverComponent.java](src/main/java/com/pi4j/crowpi/components/IrReceiverComponent.java) | +| LCD Display | [IrReceiverApp.java](src/main/java/com/pi4j/crowpi/applications/IrReceiverApp.java) | [IrReceiverComponent.java](src/main/java/com/pi4j/crowpi/components/LcdDisplayComponent.java) | +| LED Matrix | [IrReceiverApp.java](src/main/java/com/pi4j/crowpi/applications/IrReceiverApp.java) | [IrReceiverComponent.java](src/main/java/com/pi4j/crowpi/components/LcdDisplayComponent.java) | +| Light Sensor | [LightSensorApp.java](src/main/java/com/pi4j/crowpi/applications/LightSensorApp.java) | [LightSensorComponent.java](src/main/java/com/pi4j/crowpi/components/LightSensorComponent.java) | +| PIR Motion Sensor | [PirMotionSensorApp.java](src/main/java/com/pi4j/crowpi/applications/PirMotionSensorApp.java) | [PirMotionSensorComponent.java](src/main/java/com/pi4j/crowpi/components/PirMotionSensorComponent.java) | +| Relay | [RelayApp.java](src/main/java/com/pi4j/crowpi/applications/RelayApp.java) | [RelayComponent.java](src/main/java/com/pi4j/crowpi/components/RelayComponent.java) | +| RFID | [RfidApp.java](src/main/java/com/pi4j/crowpi/applications/RfidApp.java) | [RfidComponent.java](src/main/java/com/pi4j/crowpi/components/RfidComponent.java) | +| Servo Motor | [ServoMotorApp.java](src/main/java/com/pi4j/crowpi/applications/ServoMotorApp.java) | [ServoMotorComponent.java](src/main/java/com/pi4j/crowpi/components/ServoMotorComponent.java) | +| Seven Segment Display | [SevenSegmentApp.java](src/main/java/com/pi4j/crowpi/applications/SevenSegmentApp.java) | [SevenSegmentComponent.java](src/main/java/com/pi4j/crowpi/components/SevenSegmentComponent.java) | +| Step Motor | [StepMotorApp.java](src/main/java/com/pi4j/crowpi/applications/StepMotorApp.java) | [StepMotorComponent.java](src/main/java/com/pi4j/crowpi/components/StepMotorComponent.java) | +| Tilt Sensor | [StepMotorApp.java](src/main/java/com/pi4j/crowpi/applications/StepMotorApp.java) | [StepMotorComponent.java](src/main/java/com/pi4j/crowpi/components/TiltSensorComponent.java) | +| Touch Sensor | [TouchSensorApp.java](src/main/java/com/pi4j/crowpi/applications/TouchSensorApp.java) | [TouchSensorComponent.java](src/main/java/com/pi4j/crowpi/components/TouchSensorComponent.java) | +| Ultrasonic Distance Sensor | [UltrasonicDistanceSensorApp.java](src/main/java/com/pi4j/crowpi/applications/UltrasonicDistanceSensorApp.java) | [UltrasonicDistanceSensorComponent.java](src/main/java/com/pi4j/crowpi/components/UltrasonicDistanceSensorComponent.java) | +| Vibration Motor | [VibrationMotorApp.java](src/main/java/com/pi4j/crowpi/applications/VibrationMotorApp.java) | [VibrationMotorComponent.java](src/main/java/com/pi4j/crowpi/components/VibrationMotorComponent.java) | + +Due to very tight timing constraints, two of the components had to use an alternative implementation without relying on Java. This could be +improved in the future by moving this logic into native code using JNI or putting these components behind a dedicated microcontroller: + +- **IR Receiver:** This component relies on the `mode2` binary for retrieving the signal pulses, provided as part of the LIRC software + bundle. While all parsing and logic has been implemented in Java, measuring the pulses accurately enough was not possible. +- **Humidity/Temperature Sensor:** Due to being based on a DHT11 sensor, this component requires an extreme amount of precision in terms of + timing, resulting in measurement failures even when running as native code on a Raspberry Pi. To still provide some support for this + component, it requires setting up the `dht11` [kernel module](https://github.com/torvalds/linux/blob/master/drivers/iio/humidity/dht11.c) + which is part of Linux Industrial I/O. + +The CrowPi OS image mentioned further down below supports both workarounds out of the box without further configuration. + +## CUSTOM OS IMAGE + +Each [tagged GitHub release](https://github.com/Pi4J/pi4j-example-crowpi/releases/latest) provides a pre-built version of the custom OS +image called "CrowPi OS". It is based on the official "Raspberry Pi OS 2021-03-25" and automatically built using Packer. Using this image +provides the following set of benefits: + +- Preconfigured locale (en_US), keyboard (US) and timezone (Europe/Zurich) +- Preconfigured wireless country (Switzerland) by default +- Remote management via SSH and VNC possible without configuration +- Preinstalled OpenJDK 11 with Gluon JavaFX to get quickly started +- Preconfigured `/boot/config.txt` which supports all components out of the box +- Dynamic wallpaper which shows Ethernet/WLAN address and hostname +- Comes with `lirc` preinstalled to run the IR receiver component + +You may download the zip-compressed archive `crowpi.img.zip`, extract it and flash it with the imaging tool of your choice to get started. +The default installation provides an user account `pi` with the password `crowpi` and sudo privileges. + +## FRAMEWORK + +To simplify adding and launching new applications, a custom launcher has been built using PicoCLI. +The [Launcher.java](src/main/java/com/pi4j/crowpi/Launcher.java) +class contains a static list of available targets called `APPLICATIONS` which has to be adjusted when adding new applications to the +project. + +By default, an interactive menu gets shown which allows selecting a single target to launch. After executing this target, the application +will automatically end. You may optionally specify the name of an application as the first argument, i.e. `BuzzerApp`, to directly launch +this specific application. + +If you want to comfortably test all supported components at once, you may specify the flag `--demo` which will return to the interactive +launcher menu once a target has been executed. + +Creating your own applications is as simple as implementing the provided [Application.java](src/main/java/com/pi4j/crowpi/Application.java) +interface, which only requires a single `void execute(Context pi4j)` method. + +## BUILD SYSTEM + +This project uses Maven for building, testing and running the various applications. While it can be used directly on a Raspberry Pi / +CrowPi, it also supports compiling everything together locally, then pushing the artifacts to the device and running them remotely. The +build system defaults to local deployments, but the following set of Maven properties can be set for remote deployments: + +- **`crowpi.remote.host` (required):** Current IP address of the CrowPi, e.g. `192.168.1.2`, used for SCP/SSH +- **`crowpi.remote.port` (optional):** Port to use for SCP/SSH communication, defaults to `22` +- **`crowpi.remote.username` (optional):** Username to use for SCP/SSH, defaults to `pi` +- **`crowpi.remote.password` (optional):** Password to use for SCP/SSH, defaults to `crowpi` +- **`crowpi.remote.target` (optional):** Default directory to temporarily store built artifacts, defaults to `/home/pi/deploy` +- **`crowpi.remote.jvmOptions` (optional):** Additional JVM options, defaults to an empty string + +In case of a remote deployment, the artifacts get pushed via SCP and will be automatically executed using SSH. Please note that any existing +files in the deployment folder are being automatically overwritten. + +Regardless of which deployment mode you have chosen, the property `crowpi.launcher.args` can be set to specify which arguments should be +passed as-is when running the launcher. This can be used for launching demo mode or directly executing a single application. + +## SYSTEM REQUIREMENTS + +You may skip this section when using the pre-built CrowPi OS image. Should you choose to run your own image instead, you will need to ensure +that the following lines are present in your `/boot/config.txt`: + +```ini +[all] +# Enable X with 128MB GPU memory and support the custom resolution of the CrowPi LCD panel +start_x = 1 +gpu_mem = 128 +hdmi_cvt 1024 600 60 6 0 0 0 + +# Enable I2C and SPI +dtparam = i2c_arm=on +dtparam = spi=on + +# Enable audio +dtparam = auto=on + +# Enable GPIO-IR +dtoverlay = gpio-ir,gpio_pin=20 + +# Enable DHT11 +dtoverlay = dht11,gpiopin=4 + +# Enable DRM VC4 V3D with up to 2 frame buffers +dtoverlay = vc4-fkms-v3d +max_framebuffers = 2 +``` + +If you want to use the IR receiver and/or humidity/temperature sensor component, you will have to ensure that the required dependencies +mentioned in the "COMPONENTS" section of this README have also been fulfilled. + ## RUNTIME DEPENDENCIES This project has the following runtime dependency requirements: