From e12f126276225a1c5423119d40dbd5a9dee6b95d Mon Sep 17 00:00:00 2001 From: Adrian Swindle Date: Mon, 25 Sep 2023 14:17:46 -0500 Subject: [PATCH 1/2] Fixes #56 (#62) * improve this doc button draft * improve this doc feature as a link * Separated sections into individual adocs Each section of the documentation is now in its own adoc file. The index.adoc file acts as the compile point for all sections. This separation will allow the editing of the individual sections, without effecting other sections. * Added improve this doc link Each section now has an improve this doc link. I dont know if the link works without the changes being merged * fixed spacing in index.adoc and fixed link in introduction.adoc --- .../Introduction/exampleApplications.adoc | 9 + .../Introduction/supportedHardware.adoc | 16 ++ .../docs/asciidoc/adding_creating_App.adoc | 7 + .../src/docs/asciidoc/components.adoc | 4 + .../components/commun_WithHardware.adoc | 6 + .../commun_WithHardware/digitalInput.adoc | 25 ++ .../commun_WithHardware/digitalOutput.adoc | 23 ++ .../components/commun_WithHardware/i2c.adoc | 14 ++ .../commun_WithHardware/multipinConfig.adoc | 36 +++ .../components/commun_WithHardware/pwm.adoc | 23 ++ .../components/commun_WithHardware/spi.adoc | 17 ++ .../asciidoc/components/inputComponents.adoc | 3 + .../inputComponents/photosensor.adoc | 5 + .../inputComponents/pushButton.adoc | 26 ++ .../inputComponents/rfidScanner.adoc | 27 ++ .../inputComponents/rotaryEncoder.adoc | 10 +- .../inputComponents/slideSwitch.adoc | 27 ++ .../asciidoc/components/outputComponents.adoc | 4 + .../outputComponents/lcdScreen.adoc | 24 ++ .../components/outputComponents/led.adoc | 24 ++ .../outputComponents}/rgbLed.adoc | 10 +- .../src/docs/asciidoc/howContribute.adoc | 5 + .../asciidoc/i2cComponents/lcdScreen.adoc | 20 -- .../src/docs/asciidoc/index.adoc | 231 +++++------------- .../asciidoc/inputComponents/pushbutton.adoc | 22 -- .../asciidoc/inputComponents/slideSwitch.adoc | 22 -- .../src/docs/asciidoc/introduction.adoc | 17 ++ .../docs/asciidoc/outputComponents/led.adoc | 19 -- .../asciidoc/spiComponents/rfidScanner.adoc | 22 -- .../src/docs/asciidoc/usingLibrary.adoc | 5 + 30 files changed, 416 insertions(+), 287 deletions(-) create mode 100644 micronautpi4j-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/adding_creating_App.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/pushButton.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rfidScanner.adoc rename micronautpi4j-utils/src/docs/asciidoc/{ => components}/inputComponents/rotaryEncoder.adoc (56%) create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/slideSwitch.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/outputComponents.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/lcdScreen.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/led.adoc rename micronautpi4j-utils/src/docs/asciidoc/{pwmComponents => components/outputComponents}/rgbLed.adoc (53%) create mode 100644 micronautpi4j-utils/src/docs/asciidoc/howContribute.adoc delete mode 100644 micronautpi4j-utils/src/docs/asciidoc/i2cComponents/lcdScreen.adoc delete mode 100644 micronautpi4j-utils/src/docs/asciidoc/inputComponents/pushbutton.adoc delete mode 100644 micronautpi4j-utils/src/docs/asciidoc/inputComponents/slideSwitch.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/introduction.adoc delete mode 100644 micronautpi4j-utils/src/docs/asciidoc/outputComponents/led.adoc delete mode 100644 micronautpi4j-utils/src/docs/asciidoc/spiComponents/rfidScanner.adoc create mode 100644 micronautpi4j-utils/src/docs/asciidoc/usingLibrary.adoc diff --git a/micronautpi4j-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc b/micronautpi4j-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc new file mode 100644 index 00000000..5e8dcefa --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/Introduction/exampleApplications.adoc @@ -0,0 +1,9 @@ + +=== Example Applications +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-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 +https://github.com/oss-slu/SLU_OSS_CheckIn diff --git a/micronautpi4j-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc b/micronautpi4j-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc new file mode 100644 index 00000000..ef2d1b2d --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/Introduction/supportedHardware.adoc @@ -0,0 +1,16 @@ +=== Currently Supported Hardware +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-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! + +We plan on offering support for many more hardware components in the future. If you have a hardware component you would like to use but can't find, feel free to checkout how you can add support for it under "Contributing to the Library" + +* Push Button +* Slide Switch +* Rotary Encoder +* RFID Scanner +* LEDs +* RGB LEDs +* LCDs +* Photosensors \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/adding_creating_App.adoc b/micronautpi4j-utils/src/docs/asciidoc/adding_creating_App.adoc new file mode 100644 index 00000000..75f3e049 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/adding_creating_App.adoc @@ -0,0 +1,7 @@ + +== Adding to/Creating an Application +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/adding_creating_App.adoc[Improve this doc] + +TODO: outline how to create a basic applicaton like we did for the start of the check-in system + +TODO: outline how someone should add our jar to their exsisting application \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components.adoc b/micronautpi4j-utils/src/docs/asciidoc/components.adoc new file mode 100644 index 00000000..d0eb206f --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components.adoc @@ -0,0 +1,4 @@ +== Components +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components.adoc[Improve this doc] + diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware.adoc new file mode 100644 index 00000000..a59223e6 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware.adoc @@ -0,0 +1,6 @@ +=== Communicating with a Hardware Component +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware.adoc[Improve this doc] + +TODO: outline the use and access of application.yaml for an app + +TODO: Consolidate the format and include examples of how each comm type is used \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc new file mode 100644 index 00000000..9d405ca8 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalInput.adoc @@ -0,0 +1,25 @@ + +==== 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] + +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: +* pull: Either PULL_UP or PULL_DOWN depending on component +* provider: pigpio-digital-input + +[source,yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=digitalInput] +---- + +<.> Component Identifier (Used in @Named annotations) +<.> Component Name +<.> Address of connected GPIO pin +<.> Debounce value +<.> Pull value (PULL_UP or PULL_DOWN) +<.> Provider (pigpio-digital-input) \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc new file mode 100644 index 00000000..fb9bc074 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/digitalOutput.adoc @@ -0,0 +1,23 @@ +==== 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] + +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 +* address: GPIO pin associated with component +* initial: Initial value, either LOW or HIGH +* shutdown: State to take when program successfully shuts down properly, either LOW or HIGH +* provider: pigpio-digital-output + +[source,yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=digitalOutput] +---- +<1> Component Identifier (Used in @Named annotations) +<2> Component Name +<3> Address of connected GPIO pin +<4> Value to have on shutdown (HIGH = Off, LOW = On) +<5> Value to have on startup +<6> Provider (pigpio-digital-output) \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc new file mode 100644 index 00000000..04e89968 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc @@ -0,0 +1,14 @@ +==== I2C +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/i2c.adoc[Improve this doc] + +[source,yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=i2c] +---- +<1> Component Identifier (Used in @Named annotations) +<2> Component Name +<3> Device bus (0 or 1) +<4> Device address + +TODO: add I2C information \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc new file mode 100644 index 00000000..d85367eb --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/multipinConfig.adoc @@ -0,0 +1,36 @@ + +==== 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] + +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 + +.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) +<.> 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) +<.> Provider (All pins have the same provider) + +.Example Multipin PWM declaration +[source, yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=multipwm] +---- +<.> Top level field for multipin PWMs (equivlent 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) +<.> PWM types for each pin (same order as above) +<.> Provider (All pins have the same provider) +<.> Startup values (Same order as above) +<.> Shutdown values (Same order as above) \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc new file mode 100644 index 00000000..a2652930 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/pwm.adoc @@ -0,0 +1,23 @@ +==== PWM +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-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 + +* 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 + +[source,yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=pwm] +---- +<1> Component Identifier (Used in @Named annotations) +<2> Component Name +<3> Address of connected GPIO pin +<4> PWM Type (HARDWARE or SOFTWARE) +<5> Provider (pigpio-digital-output) +<6> Value to have on start up +<7> Value to have on shut down \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc new file mode 100644 index 00000000..41fb4d14 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc @@ -0,0 +1,17 @@ + +==== SPI + +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/commun_WithHardware/spi.adoc[Improve this doc] + +[source,yaml] +---- +include::../../../../../../components/src/main/resources/application.yml[tags=spi] +---- +<1> Component Identifier (Used in @Named annotations) +<2> Component Name +<3> TO DO: Figure out what this address is +<4> Baud rate +<5> Address of GPIO Reset pin + +TODO: add SPI information \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc new file mode 100644 index 00000000..4d54242b --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc @@ -0,0 +1,3 @@ +=== Input Components +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents.adoc[Improve this doc] diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc new file mode 100644 index 00000000..6772abe5 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/photosensor.adoc @@ -0,0 +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] + +TODO: add in photosensor support docs \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/pushButton.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/pushButton.adoc new file mode 100644 index 00000000..87e87388 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/pushButton.adoc @@ -0,0 +1,26 @@ +==== Push Button +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/pushButton.adoc[Improve this doc] + +===== Constructors + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/PushButtonHelper.java[tag=const] +---- + +===== Methods + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/PushButtonHelper.java[tags=method] +---- + +===== An Example Controller + +====== This controller uses the push button to turn an LED on and off + +[source, java] +---- +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/PushButtonController.java[tag=ex] +---- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rfidScanner.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rfidScanner.adoc new file mode 100644 index 00000000..41bd1c9d --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rfidScanner.adoc @@ -0,0 +1,27 @@ +==== RFID Scanner + +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rfidScanner.adoc[Improve this doc] + +===== Constructors + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/RFidHelper.java[tag=const] +---- + +===== Methods + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/RFidHelper.java[tag=method] +---- + +===== An Example Controller + +====== This controller uses the RFID scanner to write and read to a card + +[source, java] +---- +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/RFidController.java[tag=ex] +---- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/rotaryEncoder.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rotaryEncoder.adoc similarity index 56% rename from micronautpi4j-utils/src/docs/asciidoc/inputComponents/rotaryEncoder.adoc rename to micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rotaryEncoder.adoc index a77b6b33..194e82a8 100644 --- a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/rotaryEncoder.adoc +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rotaryEncoder.adoc @@ -1,3 +1,7 @@ +==== Rotary Encoder +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/rotaryEncoder.adoc[Improve this doc] + ===== YAML Pin Order The order for declaring pins for a Rotary Encoder component in the application.yaml file is as follows @@ -18,14 +22,14 @@ the sw pin would be the one connected to GPIO 17, the clk pin would be connected [source, java] ---- -include::../../../main/java/com/opensourcewithslu/inputDevices/RotaryEncoderHelper.java[tag=const] +include::../../../../main/java/com/opensourcewithslu/inputDevices/RotaryEncoderHelper.java[tag=const] ---- ===== Methods [source, java] ---- -include::../../../main/java/com/opensourcewithslu/inputDevices/RotaryEncoderHelper.java[tags=method] +include::../../../../main/java/com/opensourcewithslu/inputDevices/RotaryEncoderHelper.java[tags=method] ---- ===== An Example Controller @@ -34,5 +38,5 @@ include::../../../main/java/com/opensourcewithslu/inputDevices/RotaryEncoderHelp [source, java] ---- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/RotaryEncoderController.java[tag=ex] +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/RotaryEncoderController.java[tag=ex] ---- diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/slideSwitch.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/slideSwitch.adoc new file mode 100644 index 00000000..8bf29b8e --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/slideSwitch.adoc @@ -0,0 +1,27 @@ +==== Slide Switch + +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/slideSwitch.adoc[Improve this doc] + +===== Constructors + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/SlideSwitchHelper.java[tag=const] +---- + +===== Methods + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/inputDevices/SlideSwitchHelper.java[tags=method] +---- + +===== An Example Controller + +====== This controller sets up two slide switches + +[source, java] +---- +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/SlideSwitchController.java[tag=ex] +---- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents.adoc new file mode 100644 index 00000000..1f7233be --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents.adoc @@ -0,0 +1,4 @@ +=== Output Components + +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents.adoc[Improve this doc] diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/lcdScreen.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/lcdScreen.adoc new file mode 100644 index 00000000..93204604 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/lcdScreen.adoc @@ -0,0 +1,24 @@ +==== LCD +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/lcdScreen.adoc[Improve this doc] + +===== Constructors + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/outputDevices/LCD1602Helper.java[tag=const] +---- + +===== Methods + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/outputDevices/LCD1602Helper.java[tags=method] +---- + +===== An Example Controller + +[source, java] +---- +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/lcdController.java[tag=ex] +---- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/led.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/led.adoc new file mode 100644 index 00000000..60d41e70 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/led.adoc @@ -0,0 +1,24 @@ + +==== LED +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/led.adoc[Improve this doc] + +===== Constructors + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/outputDevices/LEDHelper.java[tag=const] +---- + +===== Methods + +[source, java] +---- +include::../../../../main/java/com/opensourcewithslu/outputDevices/LEDHelper.java[tags=method] +---- + +===== An Example Controller + +====== This controller turns the LED on and off + +TODO: Create an example LED Controller diff --git a/micronautpi4j-utils/src/docs/asciidoc/pwmComponents/rgbLed.adoc b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/rgbLed.adoc similarity index 53% rename from micronautpi4j-utils/src/docs/asciidoc/pwmComponents/rgbLed.adoc rename to micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/rgbLed.adoc index a45389a7..0e98139d 100644 --- a/micronautpi4j-utils/src/docs/asciidoc/pwmComponents/rgbLed.adoc +++ b/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/rgbLed.adoc @@ -1,3 +1,7 @@ +==== RGB LED +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/outputComponents/rgbLed.adoc[Improve this doc] + ===== YAML Pin Order The order for declaring pins for a RGB LED component in the application.yaml file is as follows @@ -18,19 +22,19 @@ the red pin would be the one connected to GPIO 17, green to GPIO 18, and blue to [source, java] ---- -include::../../../main/java/com/opensourcewithslu/outputDevices/RGBLEDHelper.java[tag=const] +include::../../../../main/java/com/opensourcewithslu/outputDevices/RGBLEDHelper.java[tag=const] ---- ===== Methods [source, java] ---- -include::../../../main/java/com/opensourcewithslu/outputDevices/RGBLEDHelper.java[tags=method] +include::../../../../main/java/com/opensourcewithslu/outputDevices/RGBLEDHelper.java[tags=method] ---- ===== An Example Controller [source, java] ---- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/rgbController.java[tag=ex] +include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/rgbController.java[tag=ex] ---- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/howContribute.adoc b/micronautpi4j-utils/src/docs/asciidoc/howContribute.adoc new file mode 100644 index 00000000..4852fd9c --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/howContribute.adoc @@ -0,0 +1,5 @@ +== Contributing to the Library +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/howContribute.adoc[Improve this doc] + +TODO: outline how someone can contribute to our library diff --git a/micronautpi4j-utils/src/docs/asciidoc/i2cComponents/lcdScreen.adoc b/micronautpi4j-utils/src/docs/asciidoc/i2cComponents/lcdScreen.adoc deleted file mode 100644 index daccd078..00000000 --- a/micronautpi4j-utils/src/docs/asciidoc/i2cComponents/lcdScreen.adoc +++ /dev/null @@ -1,20 +0,0 @@ -===== Constructors - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/outputDevices/LCD1602Helper.java[tag=const] ----- - -===== Methods - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/outputDevices/LCD1602Helper.java[tags=method] ----- - -===== An Example Controller - -[source, java] ----- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/lcdController.java[tag=ex] ----- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/index.adoc b/micronautpi4j-utils/src/docs/asciidoc/index.adoc index 3ec3372f..564a8ef0 100644 --- a/micronautpi4j-utils/src/docs/asciidoc/index.adoc +++ b/micronautpi4j-utils/src/docs/asciidoc/index.adoc @@ -13,212 +13,91 @@ toc::[] -== Introduction -Welcome to the **Pi4Micronaut Documentation**! +include::introduction.adoc[] + +include::Introduction/supportedHardware.adoc[] + +include::Introduction/exampleApplications.adoc[] + +include::adding_creating_App.adoc[] + + +include::usingLibrary.adoc[] + +include::components.adoc[] + +include::components/commun_WithHardware.adoc[] + +include::components/commun_WithHardware/digitalInput.adoc[] + +include::components/commun_WithHardware/digitalOutput.adoc[] + +include::components/commun_WithHardware/multipinConfig.adoc[] + +include::components/commun_WithHardware/pwm.adoc[] + +include::components/commun_WithHardware/spi.adoc[] + + +include::components/commun_WithHardware/i2c.adoc[] + +include::components/inputComponents.adoc[] + +include::components/inputComponents/pushButton.adoc[] + +include::components/inputComponents/slideSwitch.adoc[] + +include::components/inputComponents/rotaryEncoder.adoc[] + +include::components/inputComponents/rfidScanner.adoc[] + +include::components/inputComponents/photosensor.adoc[] + + +include::components/outputComponents.adoc[] + +include::components/outputComponents/led.adoc[] + +include::components/outputComponents/rgbLed.adoc[] + +include::components/outputComponents/lcdScreen.adoc[] + +include::howContribute.adoc[] + + + + + -Pi4Micronaut is an Open Source Java library which utilizes the Micronaut Framework and Pi4J to streamline the process of creating custom IoT applications that require hardware connectivity to Raspberry Pi's. -By reading through our documentation, you will learn how to implement our library into your application. -=== Currently Supported Hardware -If you plan on creating an application using any of the hardware components listed below, then our library is perfect for you! -We plan on offering support for many more hardware components in the future. If you have a hardware component you would like to use but can't find, feel free to checkout how you can add support for it under "Contributing to the Library" - -* Push Button -* Slide Switch -* Rotary Encoder -* RFID Scanner -* LEDs -* RGB LEDs -* LCDs -* Photosensors - -=== Example Applications - -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 -https://github.com/oss-slu/SLU_OSS_CheckIn - -== Adding to/Creating an Application - -TODO: outline how to create a basic applicaton like we did for the start of the check-in system + -TODO: outline how someone should add our jar to their exsisting application - -== Using the library - -TODO: outline the most basic use cases of the library, tbh now sure how this differs from the section above - -== Components - -=== Communicating with a Hardware Component - -TODO: outline the use and access of application.yaml for an app + -TODO: Consolidate the format and include examples of how each comm type is used - -==== 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: -* pull: Either PULL_UP or PULL_DOWN depending on component -* provider: pigpio-digital-input - -[source,yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=digitalInput] ----- - -<.> Component Identifier (Used in @Named annotations) -<.> Component Name -<.> Address of connected GPIO pin -<.> Debounce value -<.> Pull value (PULL_UP or PULL_DOWN) -<.> Provider (pigpio-digital-input) - -==== 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 -* address: GPIO pin associated with component -* initial: Initial value, either LOW or HIGH -* shutdown: State to take when program successfully shuts down properly, either LOW or HIGH -* provider: pigpio-digital-output - -[source,yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=digitalOutput] ----- -<1> Component Identifier (Used in @Named annotations) -<2> Component Name -<3> Address of connected GPIO pin -<4> Value to have on shutdown (HIGH = Off, LOW = On) -<5> Value to have on startup -<6> Provider (pigpio-digital-output) - -==== Multipin Configurations -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 -.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) -<.> 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) -<.> Provider (All pins have the same provider) -.Example Multipin PWM declaration -[source, yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=multipwm] ----- -<.> Top level field for multipin PWMs (equivlent 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) -<.> PWM types for each pin (same order as above) -<.> Provider (All pins have the same provider) -<.> Startup values (Same order as above) -<.> Shutdown values (Same order as above) -==== PWM -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 -* pwmType: Either SOFTWARE or HARDWARE based upon which type of PWM you wish to use -* provider: pigpio-pwm -[source,yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=pwm] ----- -<1> Component Identifier (Used in @Named annotations) -<2> Component Name -<3> Address of connected GPIO pin -<4> PWM Type (HARDWARE or SOFTWARE) -<5> Provider (pigpio-digital-output) -<6> Value to have on start up -<7> Value to have on shut down - -==== SPI - -[source,yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=spi] ----- -<1> Component Identifier (Used in @Named annotations) -<2> Component Name -<3> TO DO: Figure out what this address is -<4> Baud rate -<5> Address of GPIO Reset pin - -TODO: add SPI information - -==== I2C -[source,yaml] ----- -include::../../../../components/src/main/resources/application.yml[tags=i2c] ----- -<1> Component Identifier (Used in @Named annotations) -<2> Component Name -<3> Device bus (0 or 1) -<4> Device address -TODO: add I2C information -=== Input Components -==== Push Button -include::inputComponents/pushbutton.adoc[] -==== Slide Switch -include::inputComponents/slideSwitch.adoc[] -==== Rotary Encoder -include::inputComponents/rotaryEncoder.adoc[] -==== RFID Scanner -include::spiComponents/rfidScanner.adoc[] -==== Photosensor -TODO: add in photosensor support docs -=== Output Components -==== LED -include::outputComponents/led.adoc[] -==== RGB LED -include::pwmComponents/rgbLed.adoc[] -==== LCD -include::i2cComponents/lcdScreen.adoc[] -== Contributing to the Library -TODO: outline how someone can contribute to our library diff --git a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/pushbutton.adoc b/micronautpi4j-utils/src/docs/asciidoc/inputComponents/pushbutton.adoc deleted file mode 100644 index 29af9921..00000000 --- a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/pushbutton.adoc +++ /dev/null @@ -1,22 +0,0 @@ -===== Constructors - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/PushButtonHelper.java[tag=const] ----- - -===== Methods - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/PushButtonHelper.java[tags=method] ----- - -===== An Example Controller - -====== This controller uses the push button to turn an LED on and off - -[source, java] ----- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/PushButtonController.java[tag=ex] ----- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/slideSwitch.adoc b/micronautpi4j-utils/src/docs/asciidoc/inputComponents/slideSwitch.adoc deleted file mode 100644 index f796e295..00000000 --- a/micronautpi4j-utils/src/docs/asciidoc/inputComponents/slideSwitch.adoc +++ /dev/null @@ -1,22 +0,0 @@ -===== Constructors - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/SlideSwitchHelper.java[tag=const] ----- - -===== Methods - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/SlideSwitchHelper.java[tags=method] ----- - -===== An Example Controller - -====== This controller sets up two slide switches - -[source, java] ----- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/SlideSwitchController.java[tag=ex] ----- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/introduction.adoc b/micronautpi4j-utils/src/docs/asciidoc/introduction.adoc new file mode 100644 index 00000000..c5fbf5b8 --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/introduction.adoc @@ -0,0 +1,17 @@ +== Introduction + +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/introduction.adoc[Improve this doc] + + + + + +Welcome to the **Pi4Micronaut Documentation**! + +Pi4Micronaut is an Open Source Java library which utilizes the Micronaut Framework and Pi4J to streamline the process of creating custom IoT applications that require hardware connectivity to Raspberry Pi's. + +By reading through our documentation, you will learn how to implement our library into your application. + + + diff --git a/micronautpi4j-utils/src/docs/asciidoc/outputComponents/led.adoc b/micronautpi4j-utils/src/docs/asciidoc/outputComponents/led.adoc deleted file mode 100644 index 5efa4a25..00000000 --- a/micronautpi4j-utils/src/docs/asciidoc/outputComponents/led.adoc +++ /dev/null @@ -1,19 +0,0 @@ -===== Constructors - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/outputDevices/LEDHelper.java[tag=const] ----- - -===== Methods - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/outputDevices/LEDHelper.java[tags=method] ----- - -===== An Example Controller - -====== This controller turns the LED on and off - -TODO: Create an example LED Controller \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/spiComponents/rfidScanner.adoc b/micronautpi4j-utils/src/docs/asciidoc/spiComponents/rfidScanner.adoc deleted file mode 100644 index 95b9b9a1..00000000 --- a/micronautpi4j-utils/src/docs/asciidoc/spiComponents/rfidScanner.adoc +++ /dev/null @@ -1,22 +0,0 @@ -===== Constructors - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/RFidHelper.java[tag=const] ----- - -===== Methods - -[source, java] ----- -include::../../../main/java/com/opensourcewithslu/inputDevices/RFidHelper.java[tag=method] ----- - -===== An Example Controller - -====== This controller uses the RFID scanner to write and read to a card - -[source, java] ----- -include::../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/RFidController.java[tag=ex] ----- \ No newline at end of file diff --git a/micronautpi4j-utils/src/docs/asciidoc/usingLibrary.adoc b/micronautpi4j-utils/src/docs/asciidoc/usingLibrary.adoc new file mode 100644 index 00000000..ebf04b9f --- /dev/null +++ b/micronautpi4j-utils/src/docs/asciidoc/usingLibrary.adoc @@ -0,0 +1,5 @@ +== Using the library +[.text-right] +https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/usingLibrary.adoc[Improve this doc] + +TODO: outline the most basic use cases of the library, tbh now sure how this differs from the section above \ No newline at end of file From 7a7238da2f454c1d2db0fd7a22e79dee01c51480 Mon Sep 17 00:00:00 2001 From: Joe Folen <96354144+joefol@users.noreply.github.com> Date: Mon, 25 Sep 2023 16:10:51 -0500 Subject: [PATCH 2/2] added community guidelines issue 57 (#68) * added community guidelines (copied from micronaut's) issue 57 * Added information about Pi4Micronaut to the community guidelines. Issue_57. --------- Co-authored-by: jfolen --- community-guidelines.md | 92 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 community-guidelines.md diff --git a/community-guidelines.md b/community-guidelines.md new file mode 100644 index 00000000..b3f3c735 --- /dev/null +++ b/community-guidelines.md @@ -0,0 +1,92 @@ +# Community Guidelines + +The Pi4Micronaut is an Open source project. Our goal is to create a Java library using the Micronaut Framework and Pi4J to streamline the process of creating IoT web applications which utilize hardware connectivity to Raspberry Pi's. + +*** + +The Micronaut Foundation™ is a not-for-profit organization that serves to: +- Ensure technical innovation and advancement of the Micronaut framework as a free and open public-use software development toolkit for a growing global community +- Evangelize and promote the Micronaut framework as a leading technology in the JVM space +- Build and support an ecosystem of complementary documentation, functionality, and services + +We are very pleased and grateful for our partnership with the Unity Foundation. The Unity Foundation™ is a non-profit, community-based organization that is using open source technology to bridge the digital divide in disadvantaged communities. + +The Unity Foundation is committed to leveraging open source software tools to provide more inherently equitable access to the information and services that support the needs of the greater community, with a focus on the underserved. Unity develops and aggregates several open source tools and systems that can be used to develop custom software solutions to address the specific needs of different communities. By providing open and transparent access to these tools and resources, the Unity Foundation is working with a network of community partners to create more equitable access to technology and the internet. + +The Micronaut Foundation, a subsidiary of the Unity Foundation, NP supports their mission and vision to collaborate with social service organizations and other support providers to develop grass-root, holistic, sustainable technology-based solutions that help uplift individuals in underserved communities. This partnership provides a meaningful alliance between Unity and our amazing community. We are excited for the opportunity to work closely with Unity to further develop an open source technology infrastructure and ecosystem supporting our underserved communities. As Unity continues its commitment to serve as an OSS aggregator, this will scale community participation in helping define, advance, and contribute to the ongoing success and sustainability of the Micronaut framework. + +Together we believe that “all of us” is better than any one of us. We desire very simply to serve our community through partnering with other members of our community who also want to uplift and empower everyone. Together, we can ideate, prioritize, and build new or leverage existing technology and tools needed to address the digital divide. + +Our Guiding Principles: + +- Don’t reinvent the wheel +- Integrate into existing systems +- Adhere to standards +- Be industry-agnostic and applicable across domains where possible +- Be easily usable by individuals, organizations, and ecosystems +- Be guided by open principles +- Be transparent +- Embrace the joy in sharing by serving underserved communities +- Leverage open source technologies, through community partnerships, to empower and uplift communities +- Attempt to make open systems solutions accessible to communities and individuals to encourage participation, enable knowledge sharing, integration and uplift + +Our commitment to the core values of IDEA: + +- Inclusive +- Diverse +- Equitable +- Actionable + +As part of our commitment to empowering our global community, we help to ensure the continuity and advancement of several open source projects. + +As a steward for the Micronaut open source community, the Foundation shares in the responsibility to communicate expectations, moderate public discourse, and respond to abuse as necessary. By outlining our mission, values, and what we expect within our community, we hope to help you understand how best to collaborate with us in public Micronaut forums. + +Reports of abuse will be investigated, and reports of abuse may result in active moderation of any content that we determine to be in violation of these guidelines. + +### EXPECTATIONS +The primary purpose of Micronaut GitHub Discussions and Micronaut Discord is to discuss and collaborate on the Micronaut framework and related projects. + +To help maintain a safe, respectful, and productive space for all community members, we expect everyone to adhere to the following guidelines. + +- Be welcoming and open-minded +- Be respectful +- Be civil and professional +- Do not post offensive, abusive, or hate speech +- Do not harass anyone +- Treat others with respect and consideration + +### PROHIBITED ACTIONS + +- Threats of violence +- Hate speech and discrimination +- Bullying and harassment +- Impersonation +- Doxxing and invasions of privacy +- Sexual or violent messages or content +- Misinformation and disinformation +- Active malware or exploits + +### RESPONDING TO PERCEIVED VIOLATIONS OF THIS POLICY + +We cannot always actively monitor community channels for offensive content, so we rely on the community to let us know when an issue needs to be addressed. If you encounter content in one of these forums that you find objectionable or feel violates these guidelines, here are some tools to help you take action immediately: + +- Communicate expectations +- Lock conversations +- Block the user +- Report the individual to: + + +Micronaut Foundation Board of Directors (foundation@micronaut.io) for reports of abuse in the Micronaut Discord and Micronaut Github Discussions channels + +When submitting a report, please include as many details as possible, including the individual’s name (or screen name), dates and times of the communications you found objectionable, and any actions you took to mediate the situation prior to reporting it. + +### REPORT FOLLOW-UP PROCEDURES + +We’ll review each abuse report on a case-by-case basis. In each case, our team will investigate the content and surrounding facts and respond as appropriate, using these guidelines to guide our decision. + +Actions we may take in response to an abuse report include but are not limited to: + +- Content removal +- Content blocking +- Account suspension +- Account termination \ No newline at end of file