Update to README

README.md

@@ -1,48 +1,49 @@
 Presenting...
---------------------------------
 
-The Pyr0-Piezo Z-Axis Sensor
-===================
+---
 
-**What's this for?**
---------------------
+# The Pyr0-Piezo Z-Axis Sensor
 
-This is a Z-axis sensor for 3D printers.
+## What is this thing?
 
-This design incorporates two different enhancements:
+TL;DR: It's a litte circuit that turns your actual nozzle into a z-probe.
 
-1. An Ultra-Sensitive Z-Axis sensor utilizing the mechanical force of the nozzle touching the bed, giving a direct measurement with no offsets or referential assumptions to consider
+This is a Z-Probe Sensor for 3D Printers that utilizes a piezoelectric element (commonly a 20-27mm piezo disk used in musical pickups) to detect when the nozzle of the printer touches the bed. There have been other Z-Probes in the past that do this, but this is the first to incorporate an onboard microcontroller that automatically calibrates and balances the circuit. Previous piezo Z-Probes all required manual tuning to some extent, usually with tiny hard-to-use trimpots. Due to the mechanical and electrical characteristics of this type of sensor, it has several advantages over other Z-Probes:
 
-2. (Optional) An FFC Cable chain [(Flat Flexible Cable)](https://en.wikipedia.org/wiki/Flexible_flat_cable) that can carry the entire print-head's signals and current in a clean and organized way
+- There are no offsets to configure or adjust
+- It can be configured to emulate either a standard endstop, or any active-high Z-Probe
+- It's not dependent on a specific type of bed or hotend
+- The builtin signal filtering reduces the amount of false driggers dramatically compared to other piezo sensors.
+- It's FAST. Delay between the piezo being actuated and the z-trigger signal being sent to the printer's controller is ***just 26 nanoseconds***
 
-**Why is this better than X sensor?**
+### Is there a catch?
 
- - Vs. Inductive / capacitative sensors: No Offset, more accurate, doesn't require special surface
+Well, yeah a couple. The sensor requires introducing a small amount of physical instability into the construction of the 3D printer. Something needs to move, even a small fraction of a millimeter. This can be something like the bed being pushed down slightly on it's springs, or adding a hinge and a tensioning spring to the print head. There's innumerable ways to make this work, and I've been working hard with my beta testers to find the best possible method combining as much stability as possble with the highest sensitivity. The other catch is that any oozing filament will skew the leveling results, so you have to decide to either assume there will always be ooze and use a small z-offset, or add a nozzle wipe/clean manuver to your startup gcode before bed leveling.
 
- - Vs. Mechanical touch (BL-Touch, servo mounted endstops): No Offset, more accurate
+### How do I use it?
 
- - Vs. removable pressure sensor: More accurate, no need for attaching a device only for levelling
+I designed the sensor to connect to a 3D Printer's controller like any other endstop or Z-Probe. Future versions will have an i2c interface that will allow the 3D Printer's controller to change parameters on the fly during a print or before a fast move.
 
- - Vs. Optical rangefinder / Time of Flight: Much more accurate, doesnt require specific surface
+The piezo element is mounted somewhere on the 3D Printer in such a way that it undergoes mechanical stress when the nozzle touches the bed. So far there have been three distinct mounting schemes that appear to work well:
 
- - Vs. Mechanical endstops: All the things
+- On the extruder assembly
+- Under the Print Bed
+- In the case of CoreXY or other Gantry Kinematic systems, on either end of the gantry
 
- - Vs [PrecisionPiezoUK](https://www.precisionpiezo.co.uk/resources-osh) version: No potentiometer calibration required, better false-signal filtering
+#### Features:
 
- Features:
+- Self-calibrating (no more fiddling with tiny potentiometers!)
+- Ultra-precise z-height measurements
+- Zero offset (The nozzle itself is the sensor!)
+- Compatible with ALL surface types
+- No plugging in removable sensors for leveling
+- Tunable over UART / I2C
 
- - Self-calibrating (no more fiddling with tiny potentiometers!)
- - Ultra-precise z-height measurements
- - Zero offset (The nozzle itself is the sensor!)
- - Compatible with ALL surface types
- - No plugging in removable sensors for leveling
- - Tunable over UART / I2C
+#### FFC Cable Chain Extra Features:
 
- FFC Cable Chain Extra Features:
-
- - FFC Cable chain for a clean connection between print head and controller
- - Onboard switchable DC buck converter for 12v or 5v fan operation
- - LED Feedback on all PWM components
+- FFC Cable chain for a clean connection between print head and controller
+- Onboard switchable DC buck converter for 12v or 5v fan operation
+- LED Feedback on all PWM components
  Standalone version available for drop-in installation
 
 Credit must be given to precisionpiezo.co.uk for getting me started on this project and giving me a place to start. I did build a version of the FFC cable chain based on their electrical designs but found the calibration of the circuit to be very fiddly, as the range of value on the potentiometers that was acceptable was very narrow.
@@ -52,37 +53,30 @@ I've since started from scratch using my own BOM and designs, while including an
 Join our discord for support and to join in realtime discussion for the project:
 
 ![Discord Banner 1](https://discordapp.com/api/guilds/544587989536473099/widget.png?style=banner1)
----------------------------
+
+---
 
 ## Contribution:
 
 Please submit all Pull Requests through the **develop** branch!
 
 The support site for this project uses a script to automatically parse git commits for changelog data. There are three categories of commits that should show up in the case log:
 
-  - Bugfix `#bugfix`: commits related to fixing something that's broken
-  - Added Features `#featureadd`: Commits related to adding new functions and features
-  - Changelog `#changelog`: Any other commits that should be on the changelog, but don't fall into the two categories above
+- Bugfix `#bugfix`: commits related to fixing something that's broken
+- Added Features `#featureadd`: Commits related to adding new functions and features
+- Changelog `#changelog`: Any other commits that should be on the changelog, but don't fall into the two categories above
 
 Simply by adding the corresponding tag to the end of the first line of your commit message, the changelog will automatically compile these for the documentation site. Please be sure to include this in any commit messages for this project.
 
 I would also request that commits remain small, adding each change/fix/feature to their own commits. This will help with future debugging, version tracking, and testing.
 
---------------------------
-
-Legacy links:
-
-[Original Mount (Doesn't work as well as I'd like)](https://www.thingiverse.com/thing:2712439)
-
-[Original Mount v1 (Doesnt work at all)](https://www.thingiverse.com/thing:2675788)
-
-[Original Piezo + FFC board](https://www.thingiverse.com/thing:2618717)
+---
 
 This is a complete redesign from the ground up, but was based on principles and methodologies developed by [PrecisionPiezoUK](https://precisionpiezo.co.uk/resources-osh)
 
 Original FFC Cable Chain designs can be found on my Thingiverse:
- - [3D Printed Mount for Prusa/Anet printers](https://www.thingiverse.com/thing:2712439)
- - [FFC Cable Chain + Piezo boards](https://www.thingiverse.com/thing:2618717)
 
+- [3D Printed Mount for Prusa/Anet printers](https://www.thingiverse.com/thing:2712439)
+- [FFC Cable Chain + Piezo boards](https://www.thingiverse.com/thing:2618717)
 
  Please refer to LICENSE.md for license information