Merge branch 'develop' into issue-47

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 ([email protected]) 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

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

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

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

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]
+

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

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)

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)

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

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)

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

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

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]

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

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]
+----

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]
+----

micronautpi4j-utils/src/docs/asciidoc/inputComponents/rotaryEncoder.adoc → 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]
 ----