pull before push

docs/config.md

@@ -1,24 +1,38 @@
-## Configurations over UART/Serial TTY
+## Serial Terminal Applications
+
+In order to send commands, you will need an application capable of communicating over serial. Please download and install one of the following:
+
+ - Windows
+    - [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)
+    - [RealTerm](https://sourceforge.net/projects/realterm/)
+    - [Termite](https://www.compuphase.com/software_termite.htm)
+ - MacOS
+ - Linux
+    - minicom - `sudo apt install minicom` || `sudo yum install minicom`
+
+## Updatng Pyr0-Piezo Circuit Parameters over Serial
+
+The Pyr0-Piezo onboard microcontroller can be adjusted over UART/TTY/Serial.
 
 To set the below parameters using serial input, use the following:
 
-- To change trigger active duration: `TRG_D` [integer for milliseconds]
-- To change gain factor: `GAIN_F` [integer for gain state - see note*]
-- To change ADC hysteresis value: `HYST` [integer]
-- To change sensor input pullup vRef low threshold: `VFOL` [integer in millivolts]
-- To change comparator trigger high threshold: `VCOMP` [integer in millivolts]
-- To change the duration between ADC measurements: `LOOP_D` [integer in milliseconds]
+- To change trigger active duration: `TRG_D [integer for milliseconds]`
+- To change gain factor: `GAIN_F [integer for gain state - see note*]`
+- To change ADC hysteresis value: `HYST [integer]`
+- To change sensor input pullup vRef low threshold: `VFOL [integer in millivolts]`
+- To change comparator trigger high threshold: `VCOMP [integer in millivolts]`
+- To change the duration between ADC measurements: `LOOP_D [integer in milliseconds]`
+- To update the internal vRef constant value **(see notes below): `CONST [long value]`
 
-You can also enable or disable DEBUG output with: `DEBUG` [0|1]
+You can also enable or disable DEBUG output with: `DEBUG [0|1]`
 
 You can query the current configuration with: `CONFIG`
 You can query the current state (including ADC measurements) with: `STATE`
 
 To reset all settings to defaults, use: `RESET`
 
-
 These commands should be wrapped in this format:
-1CMD INT1
+`CMD INT`
 
 Examples:
 
@@ -29,6 +43,7 @@ Examples:
 
 *Note for Gain Factor:
 The gain STATE is representative of these values:
+
 - 0 = 3x
 - 1 = 3.5x
 - 2 = 4.33x
@@ -48,16 +63,13 @@ with this if you don't know what you're doing!
 
 The reading can be fine-tuned by using a multimeter, and this equation:
 
-```
-scale_constant = internal1.1Ref * 1023 * 1000
+`scale_constant = internal1.1Ref * 1023 * 1000`
 
 where
 
-internal1.1Ref = 1.1 * Vcc1 (per voltmeter) / Vcc2 (per readVcc() function)
-```
+`internal1.1Ref = 1.1 * Vcc1 (per voltmeter) / Vcc2 (per readVcc() function)`
 
-If the scale_constant calculated is different from the default 1125300,
-update the voltMeterConstant variable in pP_config.h with the correct value.
+If the scale_constant calculated is different from the default 1125300, update the voltMeterConstant variable in pP_config.h with the correct value or use the `CONST` command
 
 ## Configuration in firmware
 

docs/tutorials/config/pyr0piezo-parameters/pyr0piezo-parameters.md

@@ -0,0 +1,62 @@
+## Pyr0-Piezo circuit explaination
+
+In order to understand what each parameter does, a basic understanding of the circuit and signal involved is required.
+
+To begin, we start with the piezo element itself, which usually consists of a disk of brass doped with a piezoelectric ceramic. When flexed, bent, or pressed, this disk outputs a voltage. The amount of energy produced is small, however, and can be "noisy". Each stage of the circuit addresses a different aspect of amplifying, filtering, and conditioning the signal to reject false positives and noise.
+
+**Stage 1: Amplification**
+
+The piezo's output is tied to a high impedance input of an [Operational Amplifier](https://www.electronics-tutorials.ws/opamp/opamp_1.html). The Amp stage takes the signal from the piezo and increases it's voltage by a factor, anywhere between 3x and 11x depending on the `GAIN_F` setting. This amplified signal is then passed through to the third stage. The wire between Stage 1 and Stage 3 is also attached to the output of Stage 2 through a high-ohmage resistor. Adjusting the `GAIN_F` setting is the coarsest and easiest way to adjust the sensor's sensitivity.
+
+Use cases for adjusting `GAIN_F`:
+
+ - Sensor is not sensitive enough, or is too sensitive
+ - Many false triggers during movement
+
+[Image placeholder. Add a visual of before/after amplification stage]
+
+**Stage 2: Noise Filter & Slow-Recovery Sustain (Voltage Follower)**
+
+This stage utilizes a combination of a PWM-based DAC, another Amp channel, and a high-ohmage resistor. The purpose of this stage is to provide a "Voltage Floor" or a "Virtual Ground" to the Low-Side input of Stage 3. This stage is governed by the `VFOL` setting. The essential effect of this stage is that any signal input from the first stage that falls below the `VFOL` threshold will be filtered out and suppressed. This setting can be used to address a noisy input signal from too much EMI, static electricity, or other factors.
+
+Use case for adjusting `VFOL`:
+
+ - Many false triggers when stationary
+ - Many false triggers during movement
+
+[Image placeholder. Add a visual of VFol compared to input signal]
+
+**Stage 3: Comparator Trigger**
+
+This stage of the circuit utilized another PWM-based DAC to set a "trigger threshold", which is governed by the `VCOMP` setting. When the input signal from the previous two stages increases beyond the threshold set by `VCOMP`, the sensor's Z-Min signal is tripped and a Z-Min trigger signal is sent to the control board of the 3D Printer. As the Follower's filtering signal is attached to this input through a high-ohmage resistor, the amount of time it takes for this triggering circuit to reset is extended, which further reduces multiple trigger signals from being sent. By default, `VCOMP` is set to 2.85v which should be compatible with even 3.3v systems, but there could be instances where the `VCOMP` setting is higher than what the rest of the circuit can provide, and therefore no triggering would occur, even with valid input.
+
+Use case for adjusting `VCOMP`:
+
+ - No triggering from the sensor at all
+ - Low input voltage
+
+[Image placeholder. Add a visual representation of the comparator signals]
+
+## Other Settings
+
+**Trigger Duration**
+
+The Trigger duration, governed by the `TRG_D` setting, determines the length of the pulse sent to the printer's control board. Too short of a signal might not be registered by the controller, but too long can interfere with the ADC calculations of the firmware.
+
+**Loop Duration**
+
+The Loop duration, governed by the `LOOP_D` setting, determines how long the controller waits between ADC readings which are used to automatically balance the circuit. This setting should be kept as short as possible for the best possible results, but too short could cause hitching or overloading of the software.
+
+**Software Hysteresis**
+
+The hysteresis value, governed by the `HYST` setting, is a variable used in the ADC calculation to determine whether to adjust the PWM-DAC duty cycle. The hysteresis value adds or subtracts that value from the ADC comparator calculation. It gives a buffer to the software, preventing it from making adjustments to the DAC outputs below the value defined by `HYST`.
+
+**Volt Meter Multiplier Constant**
+
+The Voltage Multiplier Constant, governed by the `CONST` setting, is a value used in the software to accurately determine the microcontroller's input voltage. However, due to minor differences in each chip, this value may not be completely accurate for each individual board. Usually the amount of difference is so minor as to not make much of a difference, but if desired, the end-user can adjust this constant value by using the following:
+
+`scale_constant = internal1.1Ref * 1023 * 1000`
+
+where
+
+`internal1.1Ref = 1.1 * Vcc1 (per voltmeter) / Vcc2 (per readVcc() function)`

firmware/AVR-Source/Pyr0_Piezo_Sensor_v2.x.x/src/Pyr0_Piezo_Sensor_V2.x.x.cpp

@@ -100,6 +100,16 @@ update the voltMeterConstant variable in pP_config.h with the correct value
 //#define I2C_INPUT true
 
 void setup() {
+  //Setup PWM on voltage follower (PD3)
+  TCCR2A = (1 << COM2B1) | (0 << COM2B0) | (0 << WGM21) | (1 << WGM20);
+  TCCR2B = (0 << WGM22) | (0 << CS22) | (0 << CS21) | (1 << CS20);
+  DDRD |= (1 << DDD3);
+
+  //Setup PWM on comparator (PB1)
+  TCCR1A = (1 << COM1A1) | (0 << COM1A0) | (1 << WGM11) | (1 << WGM10);
+  TCCR1B = (0 << WGM13) | (0 << WGM12) | (0 << CS12) | (0 << CS11) | (1 << CS10);
+  DDRB |= (1 << DDB1);
+
   pinMode(TRG_OUT, OUTPUT);       // declare the Trigger as as OUTPUT
   pinMode(ERR_LED, OUTPUT);
   pinMode(Z_TRG, INPUT_PULLUP);   // declare z-sense input with pullup

firmware/AVR-Source/Pyr0_Piezo_Sensor_v2.x.x/src/pP_function.h

@@ -89,15 +89,13 @@ update the voltMeterConstant variable in pP_config.h with the correct value
   ADJ_FOLLOW = (followerInt / 4);
 
   // Analog output (PWM) of duty cycle
-  analogWrite(V_FOL_PWM, ADJ_FOLLOW);
+  OCR2B = ADJ_FOLLOW;
 }
 
 /*------------------------------------------------*/
 
 void adjustComp() {
-  ADJ_COMP = (compInt / 4);
-
-  analogWrite(VCOMP_PWM, ADJ_COMP);
+  OCR1A = compInt;
 }
 
 /*------------------------------------------------*/

mkdocs.yml

@@ -60,6 +60,7 @@ nav:
         - Ultimaker Under Bed: 'mounts/quadrap/um-under-bed.md'
   - Configuration:
     - Pyr0-Piezo Config: 'config.md'
+    - Settings Explaination: 'tutorials/config/pyr0piezo-parameters/pyr0piezo-parameters.md'
     - Printer Firmware Config:
       - Marlin: 'tutorials/config/printer-firmware/marlin/marlin-config.md'
       - Klipper: 'tutorials/config/printer-firmware/klipper/klipper-config.md'