From 88f6061cd7232e883848e78d8b3cf5a2488babef Mon Sep 17 00:00:00 2001
From: Pascal P <7480344+Cirromulus@users.noreply.github.com>
Date: Fri, 26 Mar 2021 16:25:09 +0100
Subject: output_pin: Support setting max_duration  (#3995)

Also added documentation for using powered tools.

Signed-off-by: Pascal Pieper <accounts@pascalpieper.de>
---
 docs/Config_Reference.md |  7 +++++
 docs/Overview.md         |  2 ++
 docs/Using_PWM_Tools.md  | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 76 insertions(+)
 create mode 100644 docs/Using_PWM_Tools.md

(limited to 'docs')

diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
index 1c86acf5..cca85161 100644
--- a/docs/Config_Reference.md
+++ b/docs/Config_Reference.md
@@ -2529,6 +2529,13 @@ pin:
 #shutdown_value:
 #   The value to set the pin to on an MCU shutdown event. The default
 #   is 0 (for low voltage).
+#maximum_mcu_duration:
+#   The maximum duration a non-shutdown value may be driven by the MCU
+#   without an acknowledge from the host.
+#   If host can not keep up with an update, the MCU will shutdown
+#   and set all pins to their respective shutdown values.
+#   Default: 0 (disabled)
+#   Usual values are around 5 seconds.
 #cycle_time: 0.100
 #   The amount of time (in seconds) per PWM cycle. It is recommended
 #   this be 10 milliseconds or greater when using software based PWM.
diff --git a/docs/Overview.md b/docs/Overview.md
index 94ffd8fa..a82f372b 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -46,6 +46,8 @@ communication with the Klipper developers.
   with Klipper.
 - [Skew correction](skew_correction.md): Adjustments for axes not
   perfectly square.
+- [PWM tools](Using_PWM_Tools.md): Guide on how to use PWM controlled
+  tools such as lasers or spindles.
 - [G-Codes](G-Codes.md): Information on commands supported by Klipper.
 
 # Developer Documentation
diff --git a/docs/Using_PWM_Tools.md b/docs/Using_PWM_Tools.md
new file mode 100644
index 00000000..3947e183
--- /dev/null
+++ b/docs/Using_PWM_Tools.md
@@ -0,0 +1,67 @@
+This document describes how to setup a PWM-controlled laser or spindle
+using `output_pin` and some macros.
+
+
+## How does it work?
+With re-purposing the printhead's fan pwm output, you can control
+lasers or spindles.
+This is useful if you use switchable print heads, for example
+the E3D toolchanger or a DIY solution.
+Usually, cam-tools such as LaserWeb can be configured to use `M3-M5`
+commands, which stand for _spindle speed CW_ (`M3 S[0-255]`),
+_spindle speed CCW_ (`M4 S[0-255]`) and _spindle stop_ (`M5`).
+
+
+**Warning:** When driving a laser, keep all security precautions
+that you can think of! Diode lasers are usually inverted.
+This means, that when the MCU restarts, the laser will be
+_fully on_ for the time it takes the MCU to start up again.
+For good measure, it is recommended to _always_ wear appropriate
+laser-goggles of the right wavelength if the laser is powered;
+and to disconnect the laser when it is not needed.
+Also, you should configure a safety timeout,
+so that when your host or MCU encounters an error, the tool will stop.
+
+For an example configuration, see `config/sample-pwm-tool-cfg`.
+
+## Current Limitations
+
+There is a limitation of how frequent PWM updates may occur.
+While being very precise, a PWM update may only occur every 0.1 seconds,
+rendering it almost useless for raster engraving.
+However, there exists an [experimental branch](https://github.com/Cirromulus/klipper/tree/laser_tool) with its own tradeoffs.
+In long term, it is planned to add this functionality to main-line klipper.
+
+## Commands
+
+`M3/M4 S<value>` : Set PWM duty-cycle. Values between 0 and 255.
+`M5` : Stop PWM output to shutdown value.
+
+## Laserweb Configuration
+
+If you use Laserweb, a working configuration would be:
+
+    GCODE START:
+        M5            ; Disable Laser
+        G21           ; Set units to mm
+        G90           ; Absolute positioning
+        G0 Z0 F7000   ; Set Non-Cutting speed
+
+    GCODE END:
+        M5            ; Disable Laser
+        G91           ; relative
+        G0 Z+20 F4000 ;
+        G90           ; absolute
+
+    GCODE HOMING:
+        M5            ; Disable Laser
+        G28           ; Home all axis
+
+    TOOL ON:
+        M3 $INTENSITY
+
+    TOOL OFF:
+        M5            ; Disable Laser
+
+    LASER INTENSITY:
+        S
-- 
cgit v1.2.3-70-g09d2