load_cell: Load cell gram scale (#6729)

* Add gram scale features to load_cell
* Convert sensor counts to grams and make this available via unix socket and object status
* Basic GCodes for tearing and reading the load cell
* Guided Calibration
* Diagnostic gcode to check the health of the load cell
* Update load_cell Documentation
* Add API server load_cell/dump_force endpoint
* Update [load_cell] config with calibration fields
* Add G-Code commands for working with load cells
* Add status reference for load_cell objects

Signed-off-by: Gareth Farrington <gareth@waves.ky>

7 files changed, 187 insertions, 24 deletions

diff --git a/docs/API_Server.md b/docs/API_Server.md
index 3837f737..87e38031 100644
--- a/docs/API_Server.md
+++ b/docs/API_Server.md
@@ -364,37 +364,21 @@ and might later produce asynchronous messages such as:
 The "header" field in the initial query response is used to describe
 the fields found in later "data" responses.
 
-### hx71x/dump_hx71x
+### load_cell/dump_force
 
-This endpoint is used to subscribe to raw HX711 and HX717 ADC data.
-Obtaining these low-level ADC updates may be useful for diagnostic
-and debugging purposes. Using this endpoint may increase Klipper's
-system load.
+This endpoint is used to subscribe to force data produced by a load_cell.
+Using this endpoint may increase Klipper's system load.
 
 A request may look like:
-`{"id": 123, "method":"hx71x/dump_hx71x",
+`{"id": 123, "method":"load_cell/dump_force",
 "params": {"sensor": "load_cell", "response_template": {}}}`
 and might return:
-`{"id": 123,"result":{"header":["time","counts","value"]}}`
+`{"id": 123,"result":{"header":["time", "force (g)", "counts", "tare_counts"]}}`
 and might later produce asynchronous messages such as:
-`{"params":{"data":[[3292.432935, 562534, 0.067059278],
-[3292.4394937, 5625322, 0.670590639]]}}`
-
-### ads1220/dump_ads1220
-
-This endpoint is used to subscribe to raw ADS1220 ADC data.
-Obtaining these low-level ADC updates may be useful for diagnostic
-and debugging purposes. Using this endpoint may increase Klipper's
-system load.
+`{"params":{"data":[[3292.432935, 40.65, 562534, -234467]]}}`
 
-A request may look like:
-`{"id": 123, "method":"ads1220/dump_ads1220",
-"params": {"sensor": "load_cell", "response_template": {}}}`
-and might return:
-`{"id": 123,"result":{"header":["time","counts","value"]}}`
-and might later produce asynchronous messages such as:
-`{"params":{"data":[[3292.432935, 562534, 0.067059278],
-[3292.4394937, 5625322, 0.670590639]]}}`
+The "header" field in the initial query response is used to describe
+the fields found in later "data" responses.
 
 ### pause_resume/cancel
 
diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
index 1489670e..44f6431f 100644
--- a/docs/Config_Reference.md
+++ b/docs/Config_Reference.md
@@ -4758,6 +4758,16 @@ scale.
 [load_cell]
 sensor_type:
 #   This must be one of the supported sensor types, see below.
+#counts_per_gram:
+#   The floating point number of sensor counts that indicates 1 gram of force.
+#   This value is calculated by the LOAD_CELL_CALIBRATE command.
+#reference_tare_counts:
+#   The integer tare value, in raw sensor counts, taken when LOAD_CELL_CALIBRATE
+#   is run. This is the default tare value when klipper starts up.
+#sensor_orientation:
+#   Change the sensor's orientation. Can be either 'normal' or 'inverted'.
+#   The default is 'normal'. Use 'inverted' if the sensor reports a
+#   decreasing force value when placed under load.
 ```
 
 #### HX711
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
index 25c69604..b2272887 100644
--- a/docs/G-Codes.md
+++ b/docs/G-Codes.md
@@ -715,6 +715,40 @@ and RAW sensor value for calibration points.
 #### DISABLE_FILAMENT_WIDTH_LOG
 `DISABLE_FILAMENT_WIDTH_LOG`: Turn off diameter logging.
 
+### [load_cell]
+
+The following commands are enabled if a
+[load_cell config section](Config_Reference.md#load_cell) has been enabled.
+
+### LOAD_CELL_DIAGNOSTIC
+`LOAD_CELL_DIAGNOSTIC [LOAD_CELL=<config_name>]`: This command collects 10
+seconds of load cell data and reports statistics that can help you verify proper
+operation of the load cell. This command can be run on both calibrated and
+uncalibrated load cells.
+
+### LOAD_CELL_CALIBRATE
+`LOAD_CELL_CALIBRATE [LOAD_CELL=<config_name>]`: Start the guided calibration
+utility. Calibration is a 3 step process:
+1. First you remove all load from the load cell and run the `TARE` command
+1. Next you apply a known load to the load cell and run the
+`CALIBRATE GRAMS=nnn` command
+1. Finally use the `ACCEPT` command to save the results
+
+You can cancel the calibration process at any time with `ABORT`.
+
+### LOAD_CELL_TARE
+`LOAD_CELL_TARE [LOAD_CELL=<config_name>]`: This works just like the tare button
+on digital scale. It sets the current raw reading of the load cell to be the
+zero point reference value. The response is the percentage of the sensors range
+that was read and the raw value in counts.
+
+### LOAD_CELL_READ load_cell="name"
+`LOAD_CELL_READ [LOAD_CELL=<config_name>]`:
+This command takes a reading from the load cell. The response is the percentage
+of the sensors range that was read and the raw value in counts. If the load cell
+is calibrated a force in grams is also reported.
+
+
 ### [heaters]
 
 The heaters module is automatically loaded if a heater is defined in
diff --git a/docs/Load_Cell.md b/docs/Load_Cell.md
new file mode 100644
index 00000000..15e04ac8
--- /dev/null
+++ b/docs/Load_Cell.md
@@ -0,0 +1,122 @@
+# Load Cells
+
+This document describes Klipper's support for load cells. Basic load cell
+functionality can be used to read force data and to weigh things like filament.
+A calibrated force sensor is an important part of a load cell based probe.
+
+## Related Documentation
+
+* [load_cell Config Reference](Config_Reference.md#load_cell)
+* [load_cell G-Code Commands](G-Codes.md#load_cell)
+* [load_cell Status Reference](Status_Reference.md#load_cell)
+
+## Using `LOAD_CELL_DIAGNOSTIC`
+
+When you first connect a load cell its good practice to check for issues by
+running `LOAD_CELL_DIAGNOSTIC`. This tool collects 10 seconds of data from the
+load cell and resport statistics:
+
+```
+$ LOAD_CELL_DIAGNOSTIC
+// Collecting load cell data for 10 seconds...
+// Samples Collected: 3211
+// Measured samples per second: 332.0
+// Good samples: 3211, Saturated samples: 0, Unique values: 900
+// Sample range: [4.01% to 4.02%]
+// Sample range / sensor capacity: 0.00524%
+```
+
+Things you can check with this data:
+* The configured sample rate of the sensor should be close to the 'Measured
+samples per second' value. If it is not you may have a configuration or wiring
+issue.
+* 'Saturated samples' should be 0. If you have saturated samples it means the
+load sell is seeing more force than it can measure.
+* 'Unique values' should be a large percentage of the 'Samples
+Collected' value. If 'Unique values' is 1 it is very likely a wiring issue.
+* Tap or push on the sensor while `LOAD_CELL_DIAGNOSTIC` runs. If
+things are working correctly ths should increase the 'Sample range'.
+
+## Calibrating a Load Cell
+
+Load cells are calibrated using the `LOAD_CELL_CALIBRATE` command. This is an
+interactive calibration utility that walks you though a 3 step process:
+1. First use the `TARE` command to establish the zero force value. This is the
+`reference_tare_counts` config value.
+2. Next you apply a known load or force to the load cell and run the
+`CALIBRATE GRAMS=nnn` command. From this the `counts_per_gram` value is
+calculated. See [the next section](#applying-a-known-force-or-load) for some
+suggestions on how to do this.
+3. Finally, use the `ACCEPT` command to save the results.
+
+You can cancel the calibration process at any time with `ABORT`.
+
+### Applying a Known Force or Load
+
+The `CALIBRATE GRAMS=nnn` step can be accomplished in a number of ways. If your
+load cell is under a platform like a bed or filament holder it might be easiest
+to put a known mass on the platform. E.g. you could use a couple of 1KG filament
+spools.
+
+If your load cell is in the printer's toolhead a different approach is easier.
+Put a digital scale on the printers bed and gently lower the toolhead onto the
+scale (or raise the bed into the toolhead if your bed moves). You may be able to
+do this using the `FORCE_MOVE` command. But more likely you will have to
+manually moving the z axis with the motors off until the toolhead presses on the
+scale.
+
+A good calibration force would ideally be a large percentage of the load cell's
+rated capacity. E.g. if you have a 5Kg load cell you would ideally calibrate it
+with a 5kg mass. This might work well with under-bed sensors that have to
+support a lot of weight. For toolhead probes this may not be a load that your
+printer bed or toolhead can tolerate without damage. Do try to use at least 1Kg
+of force, most printers should tolerate this without issue.
+
+When calibrating make careful note of the values reported:
+```
+$ CALIBRATE GRAMS=555
+// Calibration value: -2.78% (-59803108), Counts/gram: 73039.78739,
+Total capacity: +/- 29.14Kg
+```
+The `Total capacity` should be close to the theoretical rating of the load cell
+based on the sensor's capacity. If it is much larger you could have used a
+higher gain setting in the sensor or a more sensitive load cell. This isn't as
+critical for 32bit and 24bit sensors but is much more critical for low bit width
+sensors.
+
+## Reading Force Data
+Force data can be read with a GCode command:
+
+```
+LOAD_CELL_READ
+// 10.6g (1.94%)
+```
+
+Data is also continuously read and can be consumed from the load_cell printer
+object in a macro:
+
+```
+{% set grams = printer.load_cell.force_g %}
+```
+
+This provides an average force over the last 1 second, similar to how
+temperature sensors work.
+
+## Taring a Load Cell
+Taring, sometimes called zeroing, sets the current weight reported by the
+load_cell to 0. This is useful for measuring relative to a known weight. e.g.
+when measuring a filament spool, using `LOAD_CELL_TARE` sets the weight to 0.
+Then as filament is printed the load_cell will report the weight of the
+filament used.
+
+```
+LOAD_CELL_TARE
+// Load cell tare value: 5.32% (445903)
+```
+
+The current tare value is reported in the printers status and can be read in
+a macro:
+
+```
+{% set tare_counts = printer.load_cell.tare_counts %}
+```
diff --git a/docs/Overview.md b/docs/Overview.md
index 1ab94891..3a0cc617 100644
--- a/docs/Overview.md
+++ b/docs/Overview.md
@@ -101,3 +101,4 @@ communication with the Klipper developers.
 - [TSL1401CL filament width sensor](TSL1401CL_Filament_Width_Sensor.md)
 - [Hall filament width sensor](Hall_Filament_Width_Sensor.md)
 - [Eddy Current Inductive probe](Eddy_Probe.md)
+- [Load Cells](Load_Cell.md)
diff --git a/docs/Status_Reference.md b/docs/Status_Reference.md
index a40e1ab2..1c983fd6 100644
--- a/docs/Status_Reference.md
+++ b/docs/Status_Reference.md
@@ -303,6 +303,17 @@ The following information is available for each `[led led_name]`,
   chain could be accessed at
   `printer["neopixel <config_name>"].color_data[1][2]`.
 
+## load_cell
+
+The following information is available for each `[load_cell name]`:
+- 'is_calibrated': True/False is the load cell calibrated
+- 'counts_per_gram': The number of raw sensor counts that equals 1 gram of force
+- 'reference_tare_counts': The reference number of raw sensor counts for 0 force
+- 'tare_counts': The current number of raw sensor counts for 0 force
+- 'force_g': The force in grams, averaged over the last polling period.
+- 'min_force_g': The minimum force in grams, over the last polling period.
+- 'max_force_g': The maximum force in grams, over the last polling period.
+
 ## manual_probe
 
 The following information is available in the
diff --git a/docs/_klipper3d/mkdocs.yml b/docs/_klipper3d/mkdocs.yml
index 02d32fad..e13fbe8d 100644
--- a/docs/_klipper3d/mkdocs.yml
+++ b/docs/_klipper3d/mkdocs.yml
@@ -141,4 +141,5 @@ nav:
     - TSL1401CL_Filament_Width_Sensor.md
     - Hall_Filament_Width_Sensor.md
     - Eddy_Probe.md
+    - Load_Cell.md
   - Sponsors.md