Add documentation for 4-digit 7-segment display

components/src/main/java/com/opensourcewithslu/components/controllers/FourDigitSevenSegmentDisplayController.java

@@ -0,0 +1,40 @@
+package com.opensourcewithslu.components.controllers;
+
+import com.opensourcewithslu.outputdevices.FourDigitSevenSegmentDisplayHelper;
+import com.pi4j.context.Context;
+import com.pi4j.io.i2c.I2CConfig;
+import io.micronaut.http.annotation.Controller;
+import io.micronaut.http.annotation.Get;
+import jakarta.inject.Named;
+
+//tag::ex[]
+@Controller("/four-digit-seven-segment")
+public class FourDigitSevenSegmentDisplayController {
+    private final FourDigitSevenSegmentDisplayHelper fourDigitSevenSegmentDisplayHelper;
+
+    public FourDigitSevenSegmentDisplayController(@Named("four-digit-seven-segment") I2CConfig fourdigsevenseg, Context pi4jContext
+    ) {
+        this.fourDigitSevenSegmentDisplayHelper = new FourDigitSevenSegmentDisplayHelper(fourdigsevenseg, pi4jContext);
+    }
+
+    @Get("/enable")
+    public void enable() {
+        fourDigitSevenSegmentDisplayHelper.setEnabled(true);
+    }
+
+    @Get("/displayValue/{value}")
+    public void displayValue(String value) {
+        fourDigitSevenSegmentDisplayHelper.displayValue(value);
+    }
+
+    @Get("/disable")
+    public void disable() {
+        fourDigitSevenSegmentDisplayHelper.setEnabled(false);
+    }
+
+    @Get("/clear")
+    public void clear() {
+        fourDigitSevenSegmentDisplayHelper.clear();
+    }
+}
+//end::ex[]

components/src/main/resources/application.yml

@@ -62,6 +62,10 @@ pi4j:
       name: lcd                           # <2>
       bus: 1                              # <3>
       device: 0x27                        # <4>
+    four-digit-seven-segment:
+      name: 4 Digit 7 Segment Display
+      bus: 1
+      device: 0x27
   # end::i2c[]
 
   # tag::digitalInput[]

pi4micronaut-utils/src/docs/asciidoc/components/outputComponents/fourDigitSevenSegment.adoc

@@ -0,0 +1,118 @@
+:imagesdir: img/
+
+ifndef::rootpath[]
+:rootpath: ../../
+endif::rootpath[]
+
+ifdef::rootpath[]
+:imagesdir: {rootpath}{imagesdir}
+endif::rootpath[]
+
+==== 4-Digit 7-Segment Display
+
+[.text-right]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/outputComponents/fourDigitSevenSegment.adoc[Improve this doc]
+
+===== Overview
+
+This section provides details of the 4-digit 7-segment display, including its components and assembly instructions.
+
+===== Components
+
+* 1 x Raspberry Pi
+* 1 x Breadboard
+* 1 x T-Extension Board
+* 25 x Jumper Wire
+* 4 x Resistor (220Ω)
+* 1 x 4-Digit 7-Segment Display
+* 1 x 74HC595
+* Power source (appropriate voltage, typically 3.3V)
+
+===== Assembly Instructions
+
+* Connect the ground (GND) pins of the Raspberry Pi to the ground rails on the breadboard.
+* Connect the two ground rails of the breadboard with a jumper wire.
+* Place the 74HC595 on the breadboard.
+* Place the four resistors on the breadboard.
+* Place the 4-digit 7-segment display on the breadboard.
+* Connect a jumper wire from each "digit" pin of the 4-digit 7-segment to one of the resistors.
+* Connect the other end of the resistors to the Raspberry Pi's pins:
+
+- Digit 1 to GPIO17 (BCM pin 18)
+- Digit 2 to GPIO27 (BCM pin 27)
+- Digit 3 to GPIO22 (BCM pin 22)
+- Digit 4 to SPIMOSI (BCM pin 10)
+
+// TODO: Describe connections to 74HC595
+
+===== Circuit Diagram
+
+image::four_digit_circuit.webp[]
+
+===== Schematic Diagram
+
+image::four_digit_schematic.webp[]
+
+===== Functionality
+
+The display can be enabled/disabled, display a custom value, or cleared.
+
+Each digit of the display can display a digit 0 to 9, an uppercase letter A to F, a hypen (-), or a blank space.
+Each of the four decimal points can also be turned on or off.
+
+Example possible values include:
+
+* "1" (displayed with the 1 in the first digit and the others blank)
+* "8.8.8.8." (displayed with all segments enabled as `8.8.8.8.`)
+* "A.-.42" (displayed as ```A.-.42```)
+
+===== Testing
+
+Use the below commands to test the component.
+This will cause the display to turn on and display the value `1234`.
+
+[source,bash]
+----
+$ curl http://localhost:8080/four-digit-seven-segment/enable
+$ curl http://localhost:8080/four-digit-seven-segment/displayValue/1234
+----
+
+* `/enable` - Enables the display.
+* `/disable` - Disables the display.
+* `/displayValue/{value}` - Displays a custom value on the display.
+* `/clear` - Clears the display.
+
+===== Troubleshooting
+
+* Display does not turn on
+- Ensure all connections are secure and correct.
+- Check the 74HC595 for proper orientation and placement.
+- Ensure the software configuration matches the hardware setup.
+- Look for any error messages in the console or logs.
+
+* Display turns on but does not respond to commands
+- Check the software configuration for any discrepancies.
+- Ensure the 74HC595 is functioning properly.
+
+===== YAML Configuration
+
+[source,yaml]
+----
+i2c:
+four-digit-seven-segment:
+  name: 4 Digit 7 Segment Display
+  bus: 1
+  device: 0x27
+----
+
+===== Constructor and Methods
+
+To see the constructor and methods of our FourDigitSevenSegmentHelper class see our javadoc link:https://oss-slu.github.io/Pi4Micronaut/javadoc/com/opensourcewithslu/outputdevices/FourDigitSevenSegmentHelper.html[here]
+for more details.
+
+===== An Example Controller
+
+[source,java]
+----
+include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/FourDigitSevenSegmentDisplayController.java[tag=ex]
+----

pi4micronaut-utils/src/main/java/com/opensourcewithslu/outputdevices/FourDigitSevenSegmentDisplayHelper.java

@@ -0,0 +1,122 @@
+package com.opensourcewithslu.outputdevices;
+
+import com.pi4j.context.Context;
+import com.pi4j.io.i2c.I2CConfig;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import com.pi4j.crowpi.components.SevenSegmentComponent;
+
+public class FourDigitSevenSegmentDisplayHelper {
+    private static Logger log = LoggerFactory.getLogger(FourDigitSevenSegmentDisplayHelper.class);
+    private final SevenSegmentComponent display;
+    private String displayValue;
+
+    /**
+     * Constructs a new FourDigitSevenSegmentDisplayHelper.
+     *
+     * @param i2cConfig   the I2C configuration
+     * @param pi4jContext the Pi4J context
+     */
+    //tag::const[]
+    public FourDigitSevenSegmentDisplayHelper(I2CConfig i2cConfig, Context pi4jContext)
+    //end::const[]
+    {
+        this.display = new SevenSegmentComponent(pi4jContext, i2cConfig.getBus(), i2cConfig.getDevice());
+    }
+
+    /**
+     * Enables or disables the display.
+     *
+     * @param enabled True to enable, false to disable
+     */
+    //tag::method[]
+    public void setEnabled(boolean enabled)
+    //end::method[]
+    {
+        display.setEnabled(enabled);
+        this.displayValue = "";
+    }
+
+    /**
+     * Displays a value on the four-digit seven-segment display.
+     *
+     * @param value The value to display. It can include digits 0-9, letters A-F (case-insensitive),
+     *              hyphens, spaces, and decimal points. The value must not have more than 4 non-decimal
+     *              point characters, no consecutive decimal points, and if there are 4 non-decimal
+     *              point characters, decimal points must not appear on the ends.
+     */
+    //tag::method[]
+    public void displayValue(String value)
+    //end::method[]
+    {
+        // Parse out the decimal points
+        String noDecimals = value.replaceAll("\\.", "");
+
+        // Check: No more than 4 non-decimal point characters long
+        if (noDecimals.length() > 4) {
+            log.error("Display value must not have more than 4 non-decimal point characters");
+            return;
+        }
+
+        // Check: No consecutive decimal points
+        if (value.contains("..")) {
+            log.error("Display value cannot have consecutive decimal points");
+            return;
+        }
+
+        // Check: If there are 4 non-decimal point characters, then decimal points must not appear on the ends
+        if (noDecimals.length() == 4 && (value.startsWith(".") || value.endsWith("."))) {
+            log.error("Display value must have decimal points appearing strictly between the digits");
+            return;
+        }
+
+        // Check: Non-decimal point characters must be digits 0 to 1, letters A to F (case-insensitive), -, or space
+        String valid = "1234567890ABCDEFabcdef- ";
+        for (char character : noDecimals.toCharArray()) {
+            if (valid.indexOf(character) == -1) {
+                log.error("Each display value digit must be numeric, a letter A to F (case insensitive), a hyphen, or a space");
+                return;
+            }
+        }
+
+        display.print(value);
+        display.refresh();
+        value = value.toUpperCase();
+        log.info("Displaying value: {}", value);
+        this.displayValue = value;
+    }
+
+    /**
+     * Clears the display.
+     */
+    //tag::method[]
+    public void clear()
+    //end::method[]
+    {
+        for (int i = 0; i < 4; i++) {
+            display.clear();
+            display.setDecimalPoint(i, false);
+        }
+        display.setColon(false);
+        display.refresh();
+        this.displayValue = "";
+    }
+
+    /**
+     * Sets the logger object.
+     *
+     * @param log Logger object to set the logger to.
+     */
+    public void setLog(Logger log) {
+        FourDigitSevenSegmentDisplayHelper.log = log;
+    }
+
+    /**
+     * Gets the display value.
+     *
+     * @return The display value
+     */
+    public String getDisplayValue() {
+        return displayValue;
+    }
+}