Load cell gram scale

docs/API_Server.md

@@ -396,6 +396,22 @@ and might later produce asynchronous messages such as:
 `{"params":{"data":[[3292.432935, 562534, 0.067059278],
 [3292.4394937, 5625322, 0.670590639]]}}`
 
+### load_cell/dump_force
+
+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":"load_cell/dump_force",
+"params": {"sensor": "load_cell", "response_template": {}}}`
+and might return:
+`{"id": 123,"result":{"header":["time", "force (g)", "counts", "tare_counts"]}}`
+and might later produce asynchronous messages such as:
+`{"params":{"data":[[3292.432935, 40.65, 562534, -234467]]}}`
+
+The "header" field in the initial query response is used to describe
+the fields found in later "data" responses.
+
 ### pause_resume/cancel
 
 This endpoint is similar to running the "PRINT_CANCEL" G-Code command.

docs/Config_Reference.md

@@ -4659,6 +4659,15 @@ 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 CALIBRATE_LOAD_CELL command.
+#reference_tare_counts:
+#   The integer tare value, in raw sensor counts, taken when CALIBRATE_LOAD_CELL
+#   is run. This is the default tare value when klipper starts up.
+#reverse:
+#   Reverses the polarity of the load cell. This is a boolean value, the
+#   default is False.
 ```
 
 #### HX711

docs/G-Codes.md

@@ -700,6 +700,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.
+
+### CALIBRATE_LOAD_CELL
+`CALIBRATE_LOAD_CELL [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`.
+
+### TARE_LOAD_CELL
+`TARE_LOAD_CELL [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.
+
+### READ_LOAD_CELL load_cell="name"
+`READ_LOAD_CELL [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

docs/Load_Cell.md

@@ -0,0 +1,102 @@
+# 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 `CALIBRATE_LOAD_CELL` 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 rating of the load cell itself. 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:
+
+```
+READ_LOAD_CELL
+// 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.

docs/Status_Reference.md

@@ -282,6 +282,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