Update load_cell Documentation

garethky · garethky · commit d12b00ceeed0 · 2025-02-26T15:35:12.000-08:00
* 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 &lt;gareth@waves.ky&gt;
diff --git a/docs/API_Server.md b/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.
diff --git a/docs/Config_Reference.md b/docs/Config_Reference.md
@@ -4758,6 +4758,18 @@ 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.
+#reverse:
+#   Reverse the polarity of the force reported by the load cell. The default
+#   is False.
+#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.
+#reverse:
+#   Reverses the polarity of the load cell. This is a boolean value, the
+#   default is False.
 ```
 
 #### HX711
diff --git a/docs/G-Codes.md b/docs/G-Codes.md
@@ -721,6 +721,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
@@ -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
@@ -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
@@ -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
