Merge pull request #218 from oss-slu/issue-201

Fixing Documentation

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

@@ -6,6 +6,7 @@
 import io.micronaut.http.annotation.Get;
 import jakarta.inject.Named;
 
+//tag::ex[]
 @Controller("/led")
 public class LEDController {
     private final LEDHelper ledHelper;
@@ -34,3 +35,4 @@ public void blink(int duration){
         ledHelper.blink(duration);
     }
 }
+//end::ex[]

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

@@ -11,6 +11,7 @@
 /**
  * Controller for managing LCD1602 display operations via HTTP requests.
  */
+//tag::ex[]
 @Controller("/lcd")
 public class lcdController {
     private final LCD1602Helper lcdHelper;
@@ -68,3 +69,4 @@ public String turnOff() {
         return "Display turned off\n";
     }
 }
+//end::ex[]

components/src/main/resources/application.yml

@@ -14,13 +14,13 @@ pi4j:
 
   # tag::pwm[]
   pwm:
-    active-buzzer:
-      name: active-buzzer
-      address: 17
-      pwmType: SOFTWARE
-      provider: pigpio-pwm
-      initial: 0
-      shutdown: 0
+    active-buzzer:               # <1>
+      name: active-buzzer        # <2>
+      address: 17                # <3>
+      pwmType: SOFTWARE          # <4>
+      provider: pigpio-pwm       # <5>
+      initial: 0                 # <6>
+      shutdown: 0                # <7>
     passive-buzzer:
       name: passive-buzzer
       address: 17

pi4micronaut-utils/src/docs/asciidoc/Introduction/buildAndRun.adoc

@@ -74,6 +74,25 @@ Finally, install pigpio
 sudo apt-get install pigpio
 ----
 
+==== Enabling Different Communication Protocols
+. In the Pi4Micronaut library, we have used different communication protocols, such as I2C, SPI, etc.
+. To enable any of these protocols when needed, enter the following command:
++
+[source, bash]
+----
+sudo raspi-config
+----
++
+. Navigate to "*Interfacing Options*"
++
+image::commProtocol1.png[]
++
+. Choose your desired protocol.
++
+image::commProtocol2.png[]
++
+. Reboot when prompted.
+
 ==== Build and Copy Over Jar File
 . Open your terminal of choice
 . Navigate to the project root directory
@@ -104,7 +123,7 @@ scp Demo_Pi4Micronaut-0.1-all.jar test@raspberrypi-test:~
 +
 image:Copying_Jar_File_To_Pi.png[]
 
-==== Almost Done!
+==== Run Jar file on Pi and Test the Application
 . To test if you've set up everything correctly on your raspberry pi, we have some sample commands for you to run.
 . Open a new terminal and ssh into your raspberry pi.
 . Enter the following command to run the jar file:
@@ -133,21 +152,3 @@ curl http://localhost:8080/led/ledOn
 
 . If this command works and the LED has lit up, congratulations! You have successfully built and ran one of our components!
 
-==== Enabling Different Communication Protocols
-. In the Pi4Micronaut library, we have used different communication protocols, such as I2C, SPI, etc.
-. To enable any of these protocols when needed, enter the following command:
-+
-[source, bash]
-----
-sudo raspi-config
-----
-+
-. Navigate to "*Interfacing Options*"
-+
-image::commProtocol1.png[]
-+
-. Choose your desired protocol
-+
-image::commProtocol2.png[]
-+
-. Reboot when prompted to

pi4micronaut-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc

@@ -1,9 +1,12 @@
 
 === Example Applications
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc[Improve this doc]
 
 If you're curious about what Pi4Micronaut is capable of, check out some of the working applications created using our library.
 
-==== Remote Mointoring Check-In System
+==== Remote Monitoring Check-In System
 https://github.com/oss-slu/SLU_OSS_CheckIn
+
+==== Home Automation
+https://github.com/oss-slu/Pi4Micronaut/tree/Home_Automation

pi4micronaut-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc

@@ -1,6 +1,6 @@
 == Currently Supported Hardware
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc[Improve this doc]
 
 If you plan on creating an application using any of the hardware components listed below, then our library is perfect for you!
 
@@ -13,7 +13,7 @@ We plan on offering support for many more hardware components in the future. If
 * LED
 * RGB LED
 * LCD Screen
-* Photosensor
+* Photo Sensor
 * Touch Switch Sensor
 * Active Buzzer
 * Passive Buzzer

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc

@@ -1,17 +1,21 @@
 
 ==== Digital Input
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc[Improve this doc]
+
+"Digital Input" refers to a type of electronic signal or data that can be read by the Raspberry Pi's GPIO pins. These signals are binary, meaning they can only be in one of two states: HIGH (1) or LOW (0).
+
+To define in application.yaml add digital-input as a field under Pi4J, then add each component under digital-input.
 
-To define in application.yaml add digital-input as a field under pi4j, then add each component under digital-input
 Each component will need
 
 * name: Name of the component
 * address: GPIO pin associated with component
-* debounce:
+* debounce: value that determines the threshold for noise from the component
 * pull: Either PULL_UP or PULL_DOWN depending on component
 * provider: pigpio-digital-input
 
+.Example Digital Input declaration
 [source,yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=digitalInput]

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc

@@ -1,8 +1,13 @@
 ==== Digital Output
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc[Improve this doc]
+
+"Digital Output" refers to a signal sent from the Raspberry Pi's GPIO pins to another device or circuit. Unlike digital input, which the Raspberry Pi reads, digital output is a signal that the Raspberry Pi sends out.
+
+Digital outputs are also binary, meaning they can only have two states: HIGH (1) or LOW (0). These states correspond to different voltage levels, typically 3.3V for high and 0V (ground) for low on a Raspberry Pi.
+
+To define in application.yaml, add digital-output as a field under Pi4J, then add each component under digital-output.
 
-To define in application.yaml add digital-output as a field under pi4j, then add each component under digital-input
 Each component will need
 
 * name: Name of the component
@@ -11,6 +16,7 @@ Each component will need
 * shutdown: State to take when program successfully shuts down properly, either LOW or HIGH
 * provider: pigpio-digital-output
 
+.Example Digital Output declaration
 [source,yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=digitalOutput]

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc

@@ -1,7 +1,26 @@
 ==== I2C
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc[Improve this doc]
 
+I2C stands for **Inter-Integrated Circuit**. It is a bus interface connection protocol incorporated into devices for serial communication. (https://geeksforgeeks.org/i2c-communication-protocol/[Source: geeksforgeeks.com])
+The I2C protocol uses two wires: SDA (serial data) and SCL (serial clock). This protocol allows for communication between
+multiple devices using only two wires and unique addresses.
+
+The I2C LCD1602 consists of a normal LCD1602 and an I2C module that is attached to the back of the LCD.
+The I2C module is a chip that can expand the I/O ports of the LCD1602 using the I2C protocol.
+It converts the signals from the Raspberry Pi into commands for the LCD.
+
+(https://docs.sunfounder.com/projects/umsk/en/latest/01_components_basic/26-component_i2c_lcd1602.html[Source: docs.sunfounder.com])
+
+To define in application.yaml add i2c as a field under pi4j, then add each component under i2c.
+
+Each component will need:
+
+* name: Name of the component
+* bus: Bus address of device
+* device: Address of device
+
+.Example I2C declaration
 [source,yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=i2c]
@@ -11,4 +30,3 @@ include::../../../../../../components/src/main/resources/application.yml[tags=i2
 <3> Device bus (0 or 1)
 <4> Device address
 
-TODO: add I2C information

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc

@@ -1,32 +1,32 @@
 
-==== Multipin Configurations
+==== MultiPin Configurations
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc[Improve this doc]
 
-Multipin components are unique in that they require several of the same type of pin in order to function properly.
-Each class of multipin component (Digital Input, PWM), is declared slightly differently in the application.yaml file
+MultiPin components are unique in that they require several of the same type of pin in order to function properly.
+Each class of multi-pin component (Digital Input, PWM), is declared slightly differently in the application.yaml file
 
-.Example Multipin Digital Input declaration
+.Example MultiPin Digital Input declaration
 [source, yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=multiInput]
 ----
-<.> Top level field for multipin digital inputs (equivlent of digital-output declaration)
+<.> Top level field for multi-pin digital inputs (equivalent of digital-output declaration)
 <.> Component Identifier (Used in @Named annotations)
 <.> Component Name
 <.> Addresses for each pin (Each component has a specific order outlined in the component description)
 <.> Debounce values for each pin (same order as above)
 <.> Pull values for each pin (same order as above)
 <.> Shutdown value (All pins have the same shut down)
-<.> Startup value (All pins have the same start up)
+<.> Startup value (All pins have the same start-up)
 <.> Provider (All pins have the same provider)
 
-.Example Multipin PWM declaration
+.Example MultiPin PWM declaration
 [source, yaml]
 ----
-include::../../../../../../components/src/main/resources/application.yml[tags=multipwm]
+include::../../../../../../components/src/main/resources/application.yml[tags=multiPWM]
 ----
-<.> Top level field for multipin PWMs (equivlent of digital-output declaration)
+<.> Top level field for multi-pin PWMs
 <.> Component Identifier (Used in @Named annotations)
 <.> Component Name
 <.> Addresses for each pin (Each component has a specific order outlined in the component description)

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc

@@ -1,15 +1,24 @@
 ==== PWM
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc[Improve this doc]
 
-To define in application.yaml add digital-input as a field under pi4j, then add each component under digital-input
-Each component will need
+Pulse width modulation, or PWM, is a technique for getting analog results with digital means. Digital control is used to create a square wave, a signal switched between on and off.
+This on-off pattern can simulate voltages in between full on (5 Volts) and off (0 Volts) by changing the portion of the time the signal spends on versus the time that the signal spends off.
+The duration of “on time” is called the pulse width. To get varying analog values, you change, or modulate, that pulse width (https://learn.sunfounder.com/lesson-2-controlling-led-by-pwm-3/[Source: sunfounder.com]).
+In our library, our Active Buzzer component uses PWM. Once fully activated at 5 Volts, the buzzer will go off, creating a tone.
+
+To define in application.yaml add pwm as a field under pi4j, then add each component under pwm.
+
+Each component will need:
 
 * name: Name of the component
 * address: GPIO pin associated with component
 * pwmType: Either SOFTWARE or HARDWARE based upon which type of PWM you wish to use
 * provider: pigpio-pwm
+* initial: Initial value on startup
+* shutdown: Final value at shut down
 
+.Example PWM declaration
 [source,yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=pwm]

pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc

@@ -1,9 +1,43 @@
 
 ==== SPI
-
 [.text-right]
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc[Improve this doc]
+
+The Serial Peripheral Interface (SPI) is a communication protocol used to transfer data between the Raspberry Pi and peripheral devices. These peripheral devices may be either sensors or actuators.
+
+(https://raspberrypi-aa.github.io/session3/spi.html[Source: raspberrypi-aa.github.io])
+
+Many different devices use the SPI protocol, such as SD card reader modules, RFID card reader modules, and 2.4 GHz wireless transmitter/receivers all use SPI to communicate with the Raspberry Pi.
+
+(https://www.circuitbasics.com/basics-of-the-spi-communication-protocol/[Source: circuitbasics.com])
+
+
+SPI uses 4 separate connections to communicate with the target device:
+
+- COPI (Controller Output/Peripheral Input) – Line for the Controller to send data to the Peripherals.
+
+- CIPO (Controller Input/Peripheral Output) – Line for the Peripherals to send data to the Controller.
+
+- SCLK (Clock) – Line for the clock signal.
+
+- PS/CS (Peripheral Select/Chip Select) – Line for the Controller to select which Peripheral to send data to.
+
+
+====
+*Note:* Controller/Peripheral is formerly referred to as Master/Slave. In order to move away from the use of such terminology, we have opted to use the term Controller in place of Master, and Peripheral in place of Slave.
+====
+
+
+To define in application.yaml add spi as a field under pi4j, then add each component under spi.
+
+Each component will need:
+
+* name: Name of the component
+* address: Address for Controller/Peripheral
+* baud: Baud rate/data rate
+* reset-pin: Address of GPIO reset pin
 
+.Example SPI declaration
 [source,yaml]
 ----
 include::../../../../../../components/src/main/resources/application.yml[tags=spi]
@@ -14,4 +48,3 @@ include::../../../../../../components/src/main/resources/application.yml[tags=sp
 <4> Baud rate
 <5> Address of GPIO Reset pin
 
-TODO: add SPI information

pi4micronaut-utils/src/docs/asciidoc/components/inputComponents.adoc

@@ -1,3 +1,5 @@
 === Input Components
 [.text-right] 
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/inputComponents.adoc[Improve this doc]
+
+The Components that provide input signal or data to the application from Raspberry Pi GPIO pins.

pi4micronaut-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc

@@ -1,5 +1,5 @@
 ==== Photosensor
 [.text-right] 
-https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc[Improve this doc]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/pi4micronaut-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc[Improve this doc]
 
 TODO: add in photosensor support docs