From 3bc2f3b498d4f9eb1c776267d347bdaa9de996ad Mon Sep 17 00:00:00 2001
From: th33xitus <th33xitus@googlemail.com>
Date: Fri, 24 Dec 2021 01:08:09 +0100
Subject: [PATCH] doc: document passing parameters to gcode_shell_commands

---
 docs/gcode_shell_command.md | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/docs/gcode_shell_command.md b/docs/gcode_shell_command.md
index 39f1a9f..b3a2233 100644
--- a/docs/gcode_shell_command.md
+++ b/docs/gcode_shell_command.md
@@ -40,6 +40,34 @@ verbose: True
 Execute with:
 `RUN_SHELL_COMMAND CMD=hello_world`
 
+### Passing parameters:
+As of commit [f231fa9](https://github.com/th33xitus/kiauh/commit/f231fa9c69191f23277b4e3319f6b675bfa0ee42) it is also possible to pass optional parameters to a `gcode_shell_command`.
+The following short example shows storing the extruder temperature into a variable, passing that value with a parameter to a `gcode_shell_command`, which then, 
+once the gcode_macro runs and the gcode_shell_command gets called, executes the `script.sh`. The script then echoes a message to the console (if `verbose: True`) 
+and writes the value of the parameter into a textfile called `test.txt` located in the home directory.
+
+Content of the `gcode_shell_command` and the `gcode_macro`:
+```
+[gcode_shell_command print_to_file]
+command: sh /home/pi/klipper_config/script.sh
+timeout: 30.
+verbose: True
+
+[gcode_macro GET_TEMP]
+gcode:
+    {% set temp = printer.extruder.temperature %}
+    { action_respond_info("%s" % (temp)) }
+    RUN_SHELL_COMMAND CMD=print_to_file PARAMS={temp}
+```
+
+Content of `script.sh`:
+```shell
+#!/bin/sh
+
+echo "temp is: $1"
+echo "$1" >> "${HOME}/test.txt"
+```
+
 ## Warning
 
 This extension may have a high potential for abuse if not used carefully! Also, depending on the command you execute, high system loads may occur and can cause system instabilities.