Updating documentation for OpenAMS

docs/configuration/AFC_Hardware.cfg.md

@@ -296,6 +296,13 @@ trailing_min_multiplier: 1.00
 #    Default: 1.00
 #    Minimum multiplier floor applied once the buffer starts trailing,
 #    so small deviations still get a meaningful push.
+multiplier_hysteresis: 0.003
+#    Default: 0.003
+#    Minimum relative change (e.g. 0.003 = 0.3%) a new multiplier must
+#    differ from the last applied multiplier before it's sent to the
+#    stepper. Filters out insignificant corrections so
+#    update_rotation_distance isn't called every tick. Set to 0 to
+#    disable and apply every computed change.
 smoothing: 0.3
 #    Default: 0.3
 #    Exponential smoothing factor (0-0.95) applied to raw sensor

docs/configuration/AFC_UnitType_1.cfg.md

@@ -1095,6 +1095,159 @@ will then be calibrated to the correct distance.
 
 HTLF2-Claymore logic is setup to inherit the same settings and macros as an AFC_vivid unit, please refer to the [AFC_vivid](#afc_vivid-unit_name-section) section for macros and configs that are specific to a HTLF2-Claymore unit.
 
+## [AFC_OAMS unit_name] Section
+
+The following options are available in the `[AFC_OAMS unit_name]` section of the `AFC_UnitType_1.cfg` file. This
+section configures the OpenAMS hardware controller: the MCU it is connected to, the pressure (FPS) and Hall-effect
+sensor thresholds/calibration, PTFE length, PID gains, and load/unload retry behavior. One `[AFC_OAMS <unit_name>]`
+section is required per OpenAMS hardware unit and is referenced by name from a corresponding
+[AFC_OpenAMS](#afc_openams-unit_name-section) section.
+
+``` cfg
+[AFC_OAMS OAMS1]
+mcu: mcu_name
+#    Default: mcu
+#    Name of the MCU that this OpenAMS hardware unit is connected to.
+fps_upper_threshold: 0.7
+#    This parameter must be provided. Above this FPS (filament pressure
+#    sensor) reading, the hub motor runs at full speed.
+fps_lower_threshold: 0.3
+#    This parameter must be provided. Below this FPS reading, the hub
+#    motor stops.
+fps_is_reversed: False
+#    This parameter must be provided. Move the FPS slide by hand and
+#    watch the buffer state in Mainsail/Fluidd. If it shows the opposite
+#    of what you're doing, set this to True. Should also match the
+#    `reversed` value set in the corresponding `[AFC_buffer]` section.
+f1s_hes_on: 0.1, 0.1, 0.1, 0.1
+#    This parameter must be provided. Comma separated list of 4 values
+#    (0.0-1.0) for how full each spool bay's first-stage Hall-effect
+#    sensor needs to read for that bay to count as "loaded".
+f1s_hes_is_above: False
+#    This parameter must be provided. If True, a bay counts as empty
+#    above f1s_hes_on instead of below it.
+hub_hes_on: 0.825845, 0.8075905442237854, 0.837821, 0.813116
+#    This parameter must be provided. Comma separated list of 4 hub
+#    Hall-effect sensor calibration values. Calibrate with
+#    `OAMS_CALIBRATE_HUB_HES`.
+hub_hes_is_above: True
+#    This parameter must be provided. Above these hub_hes_on values,
+#    that bay's hub sensor is considered ON.
+ptfe_length: 2820
+#    This parameter must be provided. Distance in mm the OAMS feeds
+#    filament before checking the FPS slide to know when to stop
+#    loading. This value is critical and must match your machine's PTFE
+#    tube length. Run `OAMS_CALIBRATE_PTFE_LENGTH` to automatically
+#    calibrate this value.
+oams_idx: 1
+#    This parameter must be provided. This unit's number (1, 2, ...),
+#    used to name filament groups (oams1, oams2, ...) and to
+#    distinguish multiple AMS units in klippy.log.
+kp: 6.0
+#    Default: 6.0
+#    Proportional gain for the FPS (pressure) PID loop.
+ki: 0.0
+#    Default: 0.0
+#    Integral gain for the FPS (pressure) PID loop.
+kd: 0.0
+#    Default: 0.0
+#    Derivative gain for the FPS (pressure) PID loop.
+fps_target: 0.5
+#    Default: 0.5
+#    Range: fps_lower_threshold to fps_upper_threshold
+#    Target FPS (pressure) value the PID loop tries to hold.
+current_kp: 0.375
+#    Default: 0.375
+#    Proportional gain for the rewind current-sense PID loop.
+current_ki: 0.0
+#    Default: 0.0
+#    Integral gain for the rewind current-sense PID loop.
+current_kd: 0.0
+#    Default: 0.0
+#    Derivative gain for the rewind current-sense PID loop.
+current_target: 0.3
+#    Default: 0.3
+#    Range: 0.1 to 0.4
+#    Target motor current (0.0-1.0) used to control spool rewind speed.
+load_retry_max: 3
+#    Default: 3
+#    Range: 1 to 5
+#    How many times to retry a failed load.
+unload_retry_max: 2
+#    Default: 2
+#    Range: 1 to 3
+#    How many times to retry a failed unload.
+retry_delay: 3.0
+#    Default: 3.0
+#    Delay in seconds to wait between retry attempts.
+auto_unload_on_failed_load: True
+#    Default: True
+#    If True, automatically unload back to the AMS before retrying a
+#    failed load.
+load_stall_grace: 3.0
+#    Default: 3.0
+#    Seconds to wait after a load starts before stall detection begins,
+#    to allow the spool to spin up.
+load_stall_dwell: 5.0
+#    Default: 5.0
+#    Seconds the load encoder must stop advancing (after load_stall_grace
+#    has elapsed) before the load is considered stalled and aborted. Set
+#    to 0 to disable stall detection.
+```
+
+## [AFC_OpenAMS unit_name] Section
+
+The following options are available in the `[AFC_OpenAMS unit_name]` section of the `AFC_UnitType_1.cfg` file. This
+section defines the AFC unit that drives an OpenAMS hardware unit (configured above in
+[AFC_OAMS](#afc_oams-unit_name-section)), including stuck spool auto-recovery, clog detection, and filament
+engagement verification.
+
+AFC_OpenAMS inherits configuration options from the AFC_BoxTurtle configuration section, below are additional
+configuration values specific to an AFC_OpenAMS unit.
+
+<!--
+auto_spoolman_create: False
+#    Default: False
+#    If True, automatically creates matching spools in Spoolman on an
+#    RFID scan for this unit's lanes.
+-->
+
+``` cfg
+[AFC_OpenAMS AMS_1]
+oams: OAMS1
+#    Default: oams1
+#    Name of the corresponding [AFC_OAMS <unit_name>] section that
+#    provides the hardware for this unit.
+stuck_spool_auto_recovery: False
+#    Default: False
+#    If True, AFC will automatically attempt to recover from a stuck
+#    spool during a print (unload, then reload and resume) instead of
+#    pausing for manual intervention.
+stuck_spool_load_grace: 8.0
+#    Default: 8.0
+#    Seconds after a load starts to wait before stuck-spool detection
+#    begins, to allow the spool to spin up.
+stuck_spool_pressure_threshold: 0.08
+#    Default: 0.08
+#    FPS pressure value below which the spool is considered stuck during
+#    a print.
+clog_sensitivity: medium
+#    Default: medium
+#    Valid values: off, low, medium, high
+#    Sensitivity of clog detection based on FPS/encoder monitoring.
+engagement_length: 20.0
+#    Default: 20.0
+#    Distance in mm to extrude when verifying filament engagement after
+#    a load. Can be overridden per-lane.
+engagement_speed: 300.0
+#    Default: 300.0
+#    Speed in mm/min to extrude at when verifying filament engagement
+#    after a load. Can be overridden per-lane.
+defer_engagement: False
+#    Default: False
+#    If True, defers engagement verification instead of performing it
+#    immediately after load.
+```
 
 ## [servo tool_cut] Section
 
@@ -1119,3 +1272,88 @@ maximum_servo_angle: 180
 #   not send any signal at startup.
 
 ```
+
+## [temperature_oams] / [temperature_sensor sensor_name] Section (OpenAMS)
+
+If your unit has an OpenAMS HDC1080-based temperature/humidity sensor installed, it can be defined using the
+`temperature_oams` module and sensor type. This sensor reports both temperature and humidity, and can optionally
+report itself to Mainsail/Fluidd as an `aht3x` sensor for GUI compatibility.
+
+!!! note
+
+    Both sections shown below are required. The empty `[temperature_oams]` section loads the module, while the
+    `[temperature_sensor <sensor_name>]` section with `sensor_type: temperature_oams` defines the actual sensor.
+
+``` cfg
+[temperature_oams]
+#    This section must be present (it can be left empty) to load the
+#    temperature_oams module.
+
+[temperature_sensor sensor_name]
+sensor_type: temperature_oams
+#    This parameter must be provided and set to `temperature_oams`.
+i2c_mcu: mcu_name
+#    Default: mcu
+#    Name of the MCU that the sensor's I2C bus is connected to.
+i2c_bus: i2c_bus_name
+#    Name of the hardware I2C bus the sensor is connected to. Either this
+#    or i2c_software_scl_pin/i2c_software_sda_pin should be provided.
+i2c_software_scl_pin: mcu:pin
+#    MCU pin to use for a software emulated I2C clock (SCL) line. This is
+#    an alternative to i2c_bus for boards without a dedicated hardware
+#    I2C bus. Both i2c_software_scl_pin and i2c_software_sda_pin must be
+#    provided together.
+i2c_software_sda_pin: mcu:pin
+#    MCU pin to use for a software emulated I2C data (SDA) line. This is
+#    an alternative to i2c_bus for boards without a dedicated hardware
+#    I2C bus. Both i2c_software_scl_pin and i2c_software_sda_pin must be
+#    provided together.
+i2c_address: 64
+#    Default: 64
+#    I2C address of the HDC1080 sensor. Decimal 64 (0x40) is the default
+#    HDC1080 address.
+i2c_speed: 100000
+#    Default: 100000
+#    Speed of the I2C bus, in Hz. This is only used when i2c_bus is
+#    configured for a hardware I2C bus.
+min_temp: 0
+#    This parameter must be provided. Minimum allowed temperature in
+#    degrees Celsius. If a reading falls outside of the min_temp/max_temp
+#    range, a printer shutdown will be triggered.
+max_temp: 100
+#    This parameter must be provided. Maximum allowed temperature in
+#    degrees Celsius. If a reading falls outside of the min_temp/max_temp
+#    range, a printer shutdown will be triggered.
+report_time: 5
+#    Default: 5
+#    Minimum: 5
+#    Interval in seconds between sensor readings.
+temp_resolution: 14
+#    Default: 14
+#    Valid values: 11, 14
+#    Temperature measurement resolution in bits. Higher resolution
+#    increases sensor conversion time.
+humidity_resolution: 14
+#    Default: 14
+#    Valid values: 8, 11, 14
+#    Humidity measurement resolution in bits. Higher resolution
+#    increases sensor conversion time.
+temp_offset: 0.0
+#    Default: 0.0
+#    Offset in degrees Celsius applied to each temperature reading.
+#    Useful to calibrate against a known reference temperature.
+humidity_offset: 0.0
+#    Default: 0.0
+#    Offset in percent applied to each humidity reading. Useful to
+#    calibrate against a known reference humidity.
+heater_enabled: False
+#    Default: False
+#    If True, enables the HDC1080's internal heater. This can be used to
+#    drive off condensation in humid environments.
+simulate_supported_sensor_mainsail: True
+#    Default: True
+#    If True, the sensor also registers itself as an `aht3x` printer
+#    object so that Mainsail/Fluidd, which do not natively recognize
+#    `temperature_oams`, will display it in the GUI as a supported
+#    sensor type.
+```

docs/klipper/internal/openams.md

@@ -0,0 +1,124 @@
+## OpenAMS Related Commands
+
+These commands are used to manage OpenAMS units, including the `AFC_OpenAMS` unit driver (stuck spool recovery,
+clog detection, and calibration) and the underlying `AFC_OAMS` hardware controller (spool load/unload, follower,
+PID tuning, and retry status).
+
+-----
+[AFC_OAMS_CALIBRATE_PTFE]
+::: AFC_OpenAMS.afcAMS.cmd_AFC_OAMS_CALIBRATE_PTFE
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[AFC_OAMS_CALIBRATE_HUB_HES]
+::: AFC_OpenAMS.afcAMS.cmd_AFC_OAMS_CALIBRATE_HUB_HES
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[AFC_OAMS_CALIBRATE_HUB_HES_ALL]
+::: AFC_OpenAMS.afcAMS.cmd_AFC_OAMS_CALIBRATE_HUB_HES_ALL
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[AFC_OAMS_CLEAR_ERRORS]
+::: AFC_OpenAMS.afcAMS.cmd_AFC_OAMS_CLEAR_ERRORS
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[AFC_STOP_OAMS_FOLLOWER]
+::: AFC_OAMS.AFC_OAMS.cmd_AFC_STOP_OAMS_FOLLOWER
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[AFC_START_OAMS_FOLLOWER]
+::: AFC_OAMS.AFC_OAMS.cmd_AFC_START_OAMS_FOLLOWER
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_LOAD_SPOOL]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_LOAD_SPOOL
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_UNLOAD_SPOOL]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_UNLOAD_SPOOL
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_FOLLOWER]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_FOLLOWER
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_CALIBRATE_PTFE_LENGTH]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_CALIBRATE_PTFE_LENGTH
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_CALIBRATE_HUB_HES]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_CALIBRATE_HUB_HES
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_PID_AUTOTUNE]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_PID_AUTOTUNE
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_PID_SET]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_PID_SET
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_CURRENT_PID_SET]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_CURRENT_PID_SET
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_ABORT_ACTION]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_ABORT_ACTION
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_RETRY_STATUS]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_RETRY_STATUS
+    options:
+      docstring_style: numpy
+      heading_level: 3
+
+-----
+[OAMS_RESET_RETRY_COUNTS]
+::: AFC_OAMS.AFC_OAMS.cmd_OAMS_RESET_RETRY_COUNTS
+    options:
+      docstring_style: numpy
+      heading_level: 3