Merge branch 'develop' into issue_199

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

@@ -9,6 +9,7 @@
 import jakarta.inject.Named;
 
 
+//tag::ex[]
 @Controller("/ultraSound")
 public class UltraSonicSensorController {
 
@@ -55,3 +56,4 @@ public String disableUltrasoundSensor() {
         return "Ultra Sonic Sensor Disabled";
     }
 }
+//end::ex[]

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

@@ -0,0 +1,101 @@
+:imagesdir: img/
+
+ifndef::rootpath[]
+:rootpath: ../../
+endif::rootpath[]
+
+ifdef::rootpath[]
+:imagesdir: {rootpath}{imagesdir}
+endif::rootpath[]
+
+
+==== Ultrasonic Sensor
+[.text-right]
+https://github.com/oss-slu/Pi4Micronaut/edit/develop/micronautpi4j-utils/src/docs/asciidoc/components/inputComponents/ultraSonicSensor.adoc[Improve this doc]
+
+===== Overview
+This document provides details of the Ultrasonic Sensor circuit,
+including its components, assembly instructions, and functionality.
+
+===== Components
+. HC SR04
+. T-Extension Board
+. Breadboard
+. Jumper wires
+. Power source
+
+===== Circuit Diagram
+Model:
+
+image::ultrasonic_sensor_model.png[]
+
+
+
+Circuit Diagram:
+
+image::ultrasonic_sensor_circuit.png[]
+
+===== Functionality
+The Ultrasonic Sensor uses sound waves to calculate the distance from itself to the surface it is pointed at.
+The resulting measurement is accurate within a range of 3mm of the true measurement.
+The Ultrasonic Sensor's signal is stable within 5m of the sensor, gradually weakening until the signal fully disappears at 7m.
+
+Some information about the trigger and echo signals (from the sunfounder docs):
+The timing diagram is shown below. You only need to supply a short 10us pulse for the trigger input to start the ranging,
+and then the module will send out an 8 cycle burst of ultrasound at 40 kHz and raise its echo.
+You can calculate the range through the time interval between sending trigger signal and receiving echo signal.
+
+Formula: us / 58 = centimeters or us / 148 =inch; or: the range = high level time * velocity (340M/S) / 2;
+you are suggested to use measurement cycle over 60ms in order to prevent signal collisions of trigger signal and the echo signal.
+
+image::ultrasonic_sensor_timing_diagram.png[]
+
+
+
+===== Troubleshooting
+. Distance measurements not showing: Check all connections, ensure the sensor is placed correctly,
+and check the power source.
+
+===== YAML Pin Order
+The order for declaring the Trigger Pin for the Ultrasonic Sensor is as follows:
+
+[source, yaml]
+----
+digital-input:
+  ultra-sonic-trig:
+    address: 23
+----
+So the Trigger Pin would be connected to GPIO 23.
+
+The order for declaring the Echo Pin for the Ultrasonic Sensor is as follows:
+
+[source, yaml]
+----
+digital-output:
+  ultra-sonic-echo:
+    address: 24
+----
+So the Echo Pin would be connected to GPIO 24.
+
+===== Constructors
+
+[source, java]
+----
+include::../../../../../../pi4micronaut-utils/src/main/java/com/opensourcewithslu/inputDevices/UltraSonicSensorHelper.java[tag=const]
+----
+
+===== Methods
+
+[source, java]
+----
+include::../../../../../../pi4micronaut-utils/src/main/java/com/opensourcewithslu/inputDevices/UltraSonicSensorHelper.java[tags=method]
+----
+
+===== An Example Controller
+
+====== This controller uses the Ultrasonic Sensor to calculate distance from the sensor to a surface
+
+[source, java]
+----
+include::../../../../../../components/src/main/java/com/opensourcewithslu/components/controllers/UltraSonicSensorController.java[tag=ex]
+----

pi4micronaut-utils/src/docs/asciidoc/index.adoc

@@ -66,6 +66,8 @@ include::components/inputComponents/rfidScanner.adoc[]
 
 include::components/inputComponents/photosensor.adoc[]
 
+include::components/inputComponents/ultraSonicSensor.adoc[]
+
 
 include::components/outputComponents.adoc[]
 

pi4micronaut-utils/src/main/java/com/opensourcewithslu/inputdevices/UltraSonicSensorHelper.java

@@ -23,7 +23,10 @@ public class UltraSonicSensorHelper {
      * @param triggerPin The DigitalOutput pin for triggering the ultrasonic sensor.
      * @param echoPin The DigitalInput pin for receiving the echo from the ultrasonic sensor.
      */
-    public UltraSonicSensorHelper(DigitalOutput triggerPin, DigitalInput echoPin) {
+    //tag::const[]
+    public UltraSonicSensorHelper(DigitalOutput triggerPin, DigitalInput echoPin)
+    //end::const[]
+    {
         this.triggerPin = triggerPin;
         this.echoPin = echoPin;
         initialize();
@@ -32,7 +35,10 @@ public UltraSonicSensorHelper(DigitalOutput triggerPin, DigitalInput echoPin) {
     /**
      * Initializes the Ultrasonic Sensor
      */
-    public void initialize() {
+    //tag::method[]
+    public void initialize()
+    //end::method[]
+    {
         log.info("Ultrasonic Sensor Initialized");
         sensorActive = true;
         // TriggerPin is low initially
@@ -42,7 +48,10 @@ public void initialize() {
     /**
      * Begins measuring distance from sensor calling triggerAndMeasureDistance function every 100 milliseconds
      */
-    public void startMeasuring() {
+    //tag::method[]
+    public void startMeasuring()
+    //end::method[]
+    {
         if (!sensorActive) {
             return;
         }
@@ -110,7 +119,10 @@ private void calculateDistance(long durationInNano) {
      *
      * @return The distance value in centimeters.
      */
-    public double getDistanceInCentimeter() {
+    //tag::method[]
+    public double getDistanceInCentimeter()
+    //end::method[]
+    {
         return distance;
     }
 
@@ -119,14 +131,20 @@ public double getDistanceInCentimeter() {
      *
      * @return The distance value in meters.
      */
-    public double getDistanceInMeters() {
+    //tag::method[]
+    public double getDistanceInMeters()
+    //end::method[]
+    {
         return distance/100;
     }
 
     /**
      * Shuts down ultrasonic sensor
      */
-    public void stopMeasuring() {
+    //tag::method[]
+    public void stopMeasuring()
+    //end::method[]
+    {
         sensorActive = false;
         if (!executorService.isShutdown()) {
             executorService.shutdownNow();