diff --git a/content/about/release-notes.md b/content/about/release-notes.md index d38ec6c2dc..260bdd7344 100644 --- a/content/about/release-notes.md +++ b/content/about/release-notes.md @@ -151,7 +151,7 @@ All changes: https://github.com/Pi4J/pi4j/compare/2.6.0...2.6.1 * New hardware PWM provider added to the GpioD plugin, see: * [Blog: PWM Hardware Support on RPi5](https://pi4j.com/blog/2024/20240423_pwm_rpi5/). - * [Documentation: I/O Examples: Pulse Width Modulation (PWM)](https://pi4j.com/documentation/io-examples/pwm/). + * [Documentation: I/O Examples: Pulse Width Modulation (PWM)](https://pi4j.com/documentation/io-types/pwm/). * Various improvements in the I2C implementation in both core and plugins, see: * [Blog: Ongoing I2C Improvements](https://pi4j.com/blog/2024/20240418_i2c_improvements/). * Dependency bumps in the pom file, see [pull request #337](https://github.com/Pi4J/pi4j/pull/337). diff --git a/content/documentation/io-examples/1-wire.md b/content/documentation/io-types/1-wire.md similarity index 96% rename from content/documentation/io-examples/1-wire.md rename to content/documentation/io-types/1-wire.md index 28fbd0f657..00d9da7341 100644 --- a/content/documentation/io-examples/1-wire.md +++ b/content/documentation/io-types/1-wire.md @@ -2,6 +2,8 @@ title: 1-Wire weight: 270 tags: ["1-Wire"] +aliases: + - /documentation/io-examples/1-wire/ --- ## What is it? diff --git a/content/documentation/io-examples/_index.md b/content/documentation/io-types/_index.md similarity index 87% rename from content/documentation/io-examples/_index.md rename to content/documentation/io-types/_index.md index 03d91f995d..6675ae48e7 100644 --- a/content/documentation/io-examples/_index.md +++ b/content/documentation/io-types/_index.md @@ -1,9 +1,11 @@ --- -title: I/O Examples +title: I/O Types weight: 120 +aliases: + - /documentation/io-examples --- -Here you can find detailed examples for the different functionalities of Pi4J per I/O type. +Here you can find detailed info and examples for the different functionalities of Pi4J per I/O type. {{% children %}} diff --git a/content/documentation/io-examples/digital-input.md b/content/documentation/io-types/digital-input.md similarity index 97% rename from content/documentation/io-examples/digital-input.md rename to content/documentation/io-types/digital-input.md index 9bc2a5b09a..182f8c3697 100644 --- a/content/documentation/io-examples/digital-input.md +++ b/content/documentation/io-types/digital-input.md @@ -2,6 +2,8 @@ title: Digital Input (GPIO) weight: 210 tags: ["Digital Input"] +aliases: + - /documentation/io-examples/digital-input/ --- Similar to a digital output pin, a digital input translates an input value of 0V or 3.3V to the value false/true. This diff --git a/content/documentation/io-examples/digital-output.md b/content/documentation/io-types/digital-output.md similarity index 97% rename from content/documentation/io-examples/digital-output.md rename to content/documentation/io-types/digital-output.md index c7983709d9..db62cf518d 100644 --- a/content/documentation/io-examples/digital-output.md +++ b/content/documentation/io-types/digital-output.md @@ -2,6 +2,8 @@ title: Digital Output (GPIO) weight: 200 tags: ["Digital Output"] +aliases: + - /documentation/io-examples/digital-output/ --- A digital output translates a false/true (or 0/1) to an output value of 0V or 3.3V. This diff --git a/content/documentation/io-examples/i2c/_index.md b/content/documentation/io-types/i2c/_index.md similarity index 80% rename from content/documentation/io-examples/i2c/_index.md rename to content/documentation/io-types/i2c/_index.md index d04036f313..9799611809 100644 --- a/content/documentation/io-examples/i2c/_index.md +++ b/content/documentation/io-types/i2c/_index.md @@ -2,6 +2,8 @@ title: Inter-Integrated Circuit (I²C) weight: 230 tags: ["I2C"] +aliases: + - /documentation/io-examples/i2c/ --- ## What is it? @@ -64,6 +66,52 @@ root@rp5:~# i2cdetect -y 1 ``` 1 device found with address of 0x3f. +## Checking I2C Configuration + +You can check the I2C configuration of your Raspberry Pi with the following command, using [JBang](/prepare/install-java/#install-sdkman-maven-and-jbang) and a checker tool available in the [GitHub Pi4J OS repository](https://github.com/pi4J/pi4j-os). One or more checks are performed depending on the IO type checked by the tool. You will get a result like this, indicating if the check passed or failed, with more info about the expected and found result: + +```shell +$ jbang https://github.com/pi4j/pi4j-os/blob/main/iochecks/IOChecker.java i2c + +Results from I2C Detection + + Configuration check for I2C in config.txt + Status: PASS + Expected: + dtparam=i2c_arm=on + Result: + Found in /boot/firmware/config.txt: dtparam=i2c_arm=on + + Search for I2C in /proc/device-tree + Status: PASS + Expected: + i2c device-tree entries with status=okay + Result: + ✗ i2c@7d005600 (status: disabled) + ✓ i2c@7d508200 (status: okay) + ✓ i2c@7d508280 (status: okay) + ✗ i2c3_m4_agpio0_pins (status: unknown) + + i2cdetect -l + Status: PASS + Expected: + One or more devices, e.g. 'i2c-1' (I2C bus adapters detected by 'i2cdetect -l') + Result: + 1: Synopsys, DesignWare I2C adapter I2C adapter + 13: 107d508200.i2c, I2C adapter + 14: 107d508280.i2c, I2C adapter + + i2cdetect -y 1 + Status: PASS + Expected: + One or more I2C used addresses detected on bus 1 + Result: + Found 3 used addres(ses) on bus 1: 0x21, 0x5C, 0x70 + + i2cdetect -y 13 + ... # Truncated for brevity +``` + ## Transfer rates | Mode | Max. transfer rate | Direction | diff --git a/content/documentation/io-examples/i2c/clock-stretching.md b/content/documentation/io-types/i2c/clock-stretching.md similarity index 97% rename from content/documentation/io-examples/i2c/clock-stretching.md rename to content/documentation/io-types/i2c/clock-stretching.md index 74ce6145ab..c7a03cb10f 100644 --- a/content/documentation/io-examples/i2c/clock-stretching.md +++ b/content/documentation/io-types/i2c/clock-stretching.md @@ -2,6 +2,8 @@ title: I²C Clock Stretching weight: 231 tags: ["I2C"] +aliases: + - /documentation/io-examples/i2c/clock-stretching/ --- ## Clock Stretching diff --git a/content/documentation/io-examples/pwm.md b/content/documentation/io-types/pwm.md similarity index 89% rename from content/documentation/io-examples/pwm.md rename to content/documentation/io-types/pwm.md index 765eb5b3ea..218749410c 100644 --- a/content/documentation/io-examples/pwm.md +++ b/content/documentation/io-types/pwm.md @@ -2,6 +2,8 @@ title: Pulse Width Modulation (PWM) weight: 220 tags: ["PWM", "CrowPi"] +aliases: + - /documentation/io-examples/pwm/ --- ## What is it? @@ -69,6 +71,38 @@ If you need more than 2 PWM pins, use the software PWM functionality, it may be fine for your application. If they are not good enough, then you will probably need a PWM expander board/chip (controlled by I2C/SPI) to provide additional PWM support. +## Checking PWM Configuration + +You can check the PWM configuration of your Raspberry Pi with the following command, using [JBang](/prepare/install-java/#install-sdkman-maven-and-jbang) and a checker tool available in the [GitHub Pi4J OS repository](https://github.com/pi4J/pi4j-os). One or more checks are performed depending on the IO type checked by the tool. You will get a result like this, indicating if the check passed or failed, with more info about the expected and found result: + +```shell +$ jbang https://github.com/pi4j/pi4j-os/blob/main/iochecks/IOChecker.java pwm + +Results from PWM Detection + + Configuration check for PWM in config.txt + Status: PASS + Expected: + dtoverlay=pwm (or dtoverlay=pwm-2chan for 2-channel PWM) + Result: + Found in /boot/firmware/config.txt: dtoverlay=pwm-2chan + + ls -l /sys/class/pwm/ + Status: PASS + Expected: + One or more pwmchipX (X = number) + Result: + pwmchip0 + + pinctrl | grep PWM + Status: PASS + Expected: + GPIO line(s) with PWM function (e.g., GPIO18 = PWM0_CHAN2) + Result: + 18: a3 pd | lo // GPIO18 = PWM0_CHAN2 + 19: a3 pd | lo // GPIO19 = PWM0_CHAN3 + 45: op dh pd | hi // FAN_PWM/GPIO45 = output +``` ## Linuxfs Provider (linuxfs-pwm) @@ -198,7 +232,6 @@ a component to control a buzzer with PWM. Of importance, this example executes on a Raspberry Pi4, the buildPwmConfig(Context pi4j, int address) example code uses pigpio-pwm and the value passed for 'address' is the BCM pin number. - ```java public class BuzzerComponent extends Component { @@ -312,6 +345,5 @@ public class BuzzerComponent extends Component { .shutdown(0) .build(); } - } ``` diff --git a/content/documentation/io-examples/serial.md b/content/documentation/io-types/serial.md similarity index 89% rename from content/documentation/io-examples/serial.md rename to content/documentation/io-types/serial.md index ff9e144611..20a3add096 100644 --- a/content/documentation/io-examples/serial.md +++ b/content/documentation/io-types/serial.md @@ -2,6 +2,8 @@ title: Serial (UART/RS232) weight: 250 tags: ["Serial"] +aliases: + - /documentation/io-examples/serial/ --- {{% notice warning %}} @@ -69,6 +71,33 @@ See Pi command `raspi-gpio funcs`. At the present time the PiGpio library supports only Parity *None* on any/all uarts. Any future additional UART functionality within the PiGpio library will require changes within the Pi4J code base. +## Checking Serial Configuration + +You can check the Serial configuration of your Raspberry Pi with the following command, using [JBang](/prepare/install-java/#install-sdkman-maven-and-jbang) and a checker tool available in the [GitHub Pi4J OS repository](https://github.com/pi4J/pi4j-os). One or more checks are performed depending on the IO type checked by the tool. You will get a result like this, indicating if the check passed or failed, with more info about the expected and found result: + +```shell +$ jbang https://github.com/pi4j/pi4j-os/blob/main/iochecks/IOChecker.java serial +[jbang] Building jar for IOChecker.java... +Results from Serial Detection + + Configuration check for UART in config.txt + Status: PASS + Expected: + dtparam=uart0=on + Result: + Found in /boot/firmware/config.txt: dtparam=uart0=on + + Checking serial device availability + Status: PASS + Expected: + /dev/ttyS0 exists (readable, writable) + Result: + /dev/ttyS0 not available + /dev/ttyAMA0 exists (readable, writable) + /dev/ttyUSB0 exists (readable, writable) + /dev/ttyACM0 not available +``` + ## Code example The following example demonstrates how you can connect to a GPS module to read the data. This example is based on an diff --git a/content/documentation/io-examples/spi.md b/content/documentation/io-types/spi.md similarity index 88% rename from content/documentation/io-examples/spi.md rename to content/documentation/io-types/spi.md index 117f328804..c9ef1315ee 100644 --- a/content/documentation/io-examples/spi.md +++ b/content/documentation/io-types/spi.md @@ -2,6 +2,8 @@ title: Serial Peripheral Interface (SPI) weight: 240 tags: ["SPI", "MAX7219"] +aliases: + - /documentation/io-examples/spi/ --- ## What is it? @@ -64,6 +66,40 @@ There is one interface that can be accessed in two ways: /dev/spidev0.1 drives CE1 Low ``` +## Checking SPI Configuration + +You can check the SPI configuration of your Raspberry Pi with the following command, using [JBang](/prepare/install-java/#install-sdkman-maven-and-jbang) and a checker tool available in the [GitHub Pi4J OS repository](https://github.com/pi4J/pi4j-os). One or more checks are performed depending on the IO type checked by the tool. You will get a result like this, indicating if the check passed or failed, with more info about the expected and found result: + +```shell +$ jbang https://github.com/pi4j/pi4j-os/blob/main/iochecks/IOChecker.java spi + +Results from SPI Detection + + Configuration check for SPI in config.txt + Status: PASS + Expected: + dtparam=spi=on + Result: + Found in /boot/firmware/config.txt: dtparam=spi=on + + Search for SPI in /proc/device-tree + Status: PASS + Expected: + spi device-tree entries with status=okay + Result: + ✗ spi10_cs_gpio1 (status: unknown) + ✗ spi10_gpio2 (status: unknown) + ✓ spi@7d004000 (status: okay) + ✓ spidev@0 (status: okay) + + ls -l /sys/bus/spi/devices + Status: PASS + Expected: + One or more spiX.Y (X and Y = numbers) + Result: + spi0.0 spi0.1 spi10.0 +``` + ## Additional Information - [Wikipedia SPI](https://en.wikipedia.org/wiki/Serial_Peripheral_Interface) diff --git a/content/documentation/providers/linuxfs.md b/content/documentation/providers/linuxfs.md index 713de325a9..41267f3d3a 100644 --- a/content/documentation/providers/linuxfs.md +++ b/content/documentation/providers/linuxfs.md @@ -90,7 +90,7 @@ To use PWM with the LinuxFS provider, it's important to understand the config bu For instance, on a Raspberry Pi 5 with the `dtoverlay=pwm-2chan` setting in `config.txt`, a PWM connection on BCM 19 must be configured as `channel=3`. -See the [Pulse Width Modulation (PWM)](/documentation/io-examples/pwm/#linuxfs-provider-linuxfs-pwm) page on how to configure hardware PWM and which channels are available per board. +See the [Pulse Width Modulation (PWM)](/documentation/io-types/pwm/#linuxfs-provider-linuxfs-pwm) page on how to configure hardware PWM and which channels are available per board. Example on how to use PWM with LinuxFS: diff --git a/content/examples/communityImplementation/bmp280.md b/content/examples/communityImplementation/bmp280.md index 8a55f5f8f9..748322a6fa 100644 --- a/content/examples/communityImplementation/bmp280.md +++ b/content/examples/communityImplementation/bmp280.md @@ -4,185 +4,4 @@ weight: 102 tags: ["BMP280"] --- -### Description - -The BMP280 is a Pressure and temperature sensor accessed via I2C or SPI. The BMP280 -is a simple device that requires the connection of few wires to operate. -Because of this simplicity the device can serve as a very easy project for initial Pi and -Pi4j usage. This document will explain the more simple means to connect the sensor and -access the device with existing software requiring no coding. The document will -also explain minimal coding required to allow greater flexibility. - -A later section explains creating a more robust proto-type environment to better -support using various integrated circuits, see [Prototype board](/examples/communityimplementation/prototype-board/). - -### Connecting Adafruit BMP280 - -After soldering the pins to the PCB you can use female-female jumpers to connect -directly to the Pi GPIO pins. - -{{% notice note %}} -Power off the Pi with `sudo shutdown` prior to making connections. -Or if you complete these connections with power applied, connect CS to -3.3v before connecting Vin. This is required to ensure the I2C interface is -enabled, else the chip enables SPI communication protocol. -{{% /notice %}} - -### Component and wiring - -#### BMP280 module - -The following shot is the Adafruit BMP280 module. The BMP280 chip is mounted -on a small circuit board with pins to solder in for connections. - -{{< gallery >}} -{{< figure link="/assets/examples/community/BMP280/BMP280_Module.png" caption="BMP280 module" caption-position="center" caption-effect="fade" >}} -{{< /gallery >}} -{{< load-photoswipe >}} - -#### 40 pin identification - -This shot is the Pi with an easy to read card that identifies the 40 pin -connector. - -{{< gallery >}} -{{< figure link="/assets/examples/community/BMP280/BMP280_pi_cana_card.png" caption="BMP280 pi_canca_card" caption-position="center" caption-effect="fade" >}} -{{< /gallery >}} - -#### 40 pin connection - -This is the BMP280 module connected to the Pi 40 pin connector. - -{{< gallery >}} -{{< figure link="/assets/examples/community/BMP280/BMP280_pi_module_cmpl.png" caption="BMP280 wire_cmpl" caption-position="center" caption-effect="fade" >}} -{{< /gallery >}} - -#### Header Pin/Colors – Pi 40 pin connector - -| Pin | Color | Description | -| :--- | :--- | :--- | -| Vin | Red | to Pi 3.3 pin 1 | -| 3v | N/C | | -| Gnd | Brown | to Pi pin 6 | -| SCK | Green | to Pi pin 5 | -| SDO | N/C | | -| SDI | Blue | to Pi pin 3 | -| CS | Orange | to Pi pin 17 | - -#### Validate Connections - -Power on the Pi. Log in as usual. -Run the command `i2cdetect -y 1`. This command will display all I2C devices -connected to I2C bus 1. In this case only the BMP280 is connected so the table -should include a device 77, 0x77 being the device address of the BMP280. - -{{< gallery >}} -{{< figure link="/assets/examples/community/BMP280/BMP280_i2cdetect.png" caption="BMP280 i2cdetect" caption-position="center" caption-effect="fade" >}} -{{< /gallery >}} - -### Build via Maven - -The Pi4j project uses git via github for the source code repository. The -main Pi4J documentation provides details of the repository and maven build process. - -The project [Example Devices](https://github.com/taartspi/pi4j-example-devices) -uses the prescribed Maven build process. It is easiest to git clone the -[Example Devices](https://github.com/taartspi/pi4j-example-devices) directory -and use these steps to build. Note: each device within this directory -contains a README.md that explains the expected Hardware connections, -build process, and how to use the device via these modules. - -```bash -$ mvn clean package -$ cd target/distribution -$ sudo ./runBMP280.sh -``` - -### Program output - -```bash -[main] INFO com.pi4j.util.Console - I2C detail : com.pi4j.plugin.linuxfs.provider.i2c.LinuxFsI2C@45018215 bus : 1 address : 119 -[main] INFO com.pi4j.util.Console - Temperatue C = 32.37366343149915 -[main] INFO com.pi4j.util.Console - Temperatue F = 90.27259417669848 -[main] INFO com.pi4j.util.Console - Pressure Pa = 97930.29684231618 -[main] INFO com.pi4j.util.Console - Pressure InHg = 28.91894505802476 -[main] INFO com.pi4j.util.Console - Pressure mb = 979.2223518169782 -``` - -### Supporting BMP280 Source Code - -[BMP280 source files](https://github.com/taartspi/pi4j-example-devices/blob/master/src/main/java/com/pi4j/devices/bmp280) - -This is part of a larger project -[Example Devices](https://github.com/taartspi/pi4j-example-devices) - -### Code - -A simple example on how to use the BMP280 sensor. This requires -[Example Devices](https://github.com/taartspi/pi4j-example-devices) was built. - -```java -package com.pi4j.test.devices.bmp280; - -import com.pi4j.Pi4J; -import com.pi4j.devices.bmp280.BMP280Device; -import com.pi4j.plugin.linuxfs.provider.i2c.LinuxFsI2CProvider; -import com.pi4j.util.Console; - -public class BMP280 { - - public static void main(String[] args) throws Exception { - // ------------------------------------------------------------ - // Initialize the Pi4J Runtime Context - // ------------------------------------------------------------ - // Before you can use Pi4J you must initialize a new runtime - // context. - // - // The 'Pi4J' static class includes a few helper context - // creators for the most common use cases. The 'newAutoContext()' - // method will automatically load all available Pi4J - // extensions found in the application's classpath which - // may include 'Platforms' and 'I/O Providers' - - var pi4j = Pi4J.newContextBuilder().add( - LinuxFsI2CProvider.newInstance()).build(); - - // print installed providers - System.out.println("----------------------------------------------------------"); - System.out.println("PI4J PROVIDERS"); - System.out.println("----------------------------------------------------------"); - pi4j.providers().describe().print(System.out); - System.out.println("----------------------------------------------------------"); - - final Console console = new Console(); - console.print("=============================================================="); - console.print("startup BMP280 "); - console.print("=============================================================="); - - var bmpDev = new BMP280Device(pi4j, console, 1, 0x77, "info"); - bmpDev.initSensor(); - console.println(" Dev I2C detail " + bmpDev.i2cDetail()); - console.println(" Setup ----------------------------------------------------------"); - - console.println(" I2C detail : " + bmpDev.i2cDetail()); - - double reading1 = bmpDev.temperatureC(); - console.println(" Temperatue C = " + reading1); - - double reading2 = bmpDev.temperatureF(); - console.println(" Temperatue F = " + reading2); - - double press1 = bmpDev.pressurePa(); - console.println(" Pressure Pa = " + press1); - - double press2 = bmpDev.pressureIn(); - console.println(" Pressure InHg = " + press2); - - double press3 = bmpDev.pressureMb(); - console.println(" Pressure mb = " + press3); - - // Shutdown Pi4J - pi4j.shutdown(); - } -} -``` +{{< github-readme "https://github.com/Pi4J/pi4j-example-devices/blob/67c85e0ce2fc2ef62899bd669f029062c7139667/src/main/java/com/pi4j/devices/bmp280/README.md" >}} diff --git a/themes/hugo-theme-learn/layouts/shortcodes/github-readme.html b/themes/hugo-theme-learn/layouts/shortcodes/github-readme.html new file mode 100644 index 0000000000..bb6c3a8691 --- /dev/null +++ b/themes/hugo-theme-learn/layouts/shortcodes/github-readme.html @@ -0,0 +1,19 @@ +{{- $url := .Get 0 -}} +{{- $rawURL := "" -}} + +{{- if strings.Contains $url "github.com" -}} + {{- $rawURL = replace $url "github.com" "raw.githubusercontent.com" -}} + {{- $rawURL = replace $rawURL "/blob/" "/" -}} +{{- else -}} + {{- errorf "Invalid GitHub URL provided to github-readme shortcode: %s" $url -}} +{{- end -}} + +{{- with try (resources.GetRemote $rawURL) -}} + {{- with .Err -}} + {{- errorf "Unable to fetch README from %s: %s" $rawURL . -}} + {{- else with .Value -}} + {{- .Content | markdownify -}} + {{- else -}} + {{- errorf "Unable to get remote resource %q" $rawURL -}} + {{- end -}} +{{- end -}} \ No newline at end of file