18274 FIX Printer Supply: Upturn option failed for receptacles

This Werk fixes a regression that occurs since Checkmk 2.4.0.

At the _Printer cartridge levels_ ruleset, you can enable the option _Upturn supply levels_ (Previously called _Upturn toner levels_) to fix values from a device that reports its levels in an unusual way.
This fix, while being effective for Containers like ink cartridges and toners, failed to apply for receptacles like waste boxes.

Alongside this Werk, the wording around the _Upturn supply levels_ option and the Check's manpage has been adapted slightly to clarify the scope and meaning of this feature.

CMK-24095

Change-Id: Ia53995820af3c80c6181aea537b82524c6d38d80

Author: andiumbreit

.werks/18274.md

@@ -0,0 +1,20 @@
+[//]: # (werk v2)
+# Printer Supply: Upturn option failed for receptacles
+
+key        | value
+---------- | ---
+date       | 2025-07-25T07:47:01+00:00
+version    | 2.4.0p9
+class      | fix
+edition    | cre
+component  | checks
+level      | 1
+compatible | yes
+
+This Werk fixes a regression that occurs since Checkmk 2.4.0.
+
+At the _Printer cartridge levels_ ruleset, you can enable the option _Upturn supply levels_ (Previously called _Upturn toner levels_) to fix values from a device that reports its levels in an unusual way.
+This fix, while being effective for Containers like ink cartridges and toners, failed to apply for receptacles like waste boxes.
+
+Alongside this Werk, the wording around the _Upturn supply levels_ option and the Check's manpage has been adapted slightly to clarify the scope and meaning of this feature.
+

cmk/gui/plugins/wato/check_parameters/printer_supply.py

@@ -99,12 +99,15 @@ def _parameter_valuespec_printer_supply() -> Migrate:
                 (
                     "upturn_toner",
                     Checkbox(
-                        title=_("Upturn toner levels"),
-                        label=_("Printer sends <i>used</i> material instead of <i>remaining</i>"),
+                        title=_("Upturn supply levels"),
+                        label=_("Printer sends <i>used</i> supply instead of <i>remaining</i>"),
                         help=_(
-                            "Some Printers (e.g. Konica for Drum Cartdiges) returning the available"
-                            " fuel instead of what is left. In this case it's possible"
-                            " to upturn the levels to handle this behavior"
+                            "Some printers (e.g. Konica for drum cartridges) return"
+                            "<ul>"
+                            "<li>in case of a container: The used instead of the available supply</li>"
+                            "<li>in case of a receptacle: The available instead of the used space</li>"
+                            "<ul>"
+                            "Enable this option to handle this behavior."
                         ),
                     ),
                 ),

cmk/plugins/collection/agent_based/printer_supply.py

@@ -297,9 +297,14 @@ def _get_partial_data_results(
 def _get_fill_level_percentage(supply: PrinterSupply, upturn_toner: bool) -> float:
     fill_level_percentage = 100.0 * supply.level / supply.max_capacity
 
-    # Some printers handle the used / remaining material differently
-    # With the upturn option we can toggle the point of view (again)
-    if supply.supply_class is SupplyClass.RECEPTACLE or upturn_toner:
+    if supply.supply_class is SupplyClass.RECEPTACLE:
+        # We expect a receptacle (like a waste container) to display used space that counts up.
+        # Since we handle all percentages as "supply left", we turn the percentage upside down.
+        fill_level_percentage = 100 - fill_level_percentage
+
+    if upturn_toner:
+        # This option must always upturn the applying logic.
+        # Otherwise, we wouldn't catch a receptacle that shows space left instead of space used.
         return 100 - fill_level_percentage
 
     return fill_level_percentage

cmk/plugins/collection/checkman/printer_supply

@@ -4,22 +4,20 @@ catalog: hw/printer
 license: GPLv2
 distribution: check_mk
 description:
- This check monitors the remaining filling level in percent of a printers
- supplys like toner or fuser. The printer has to support the generic
- PRINTER-MIB.
- The default check levels are 20% (warning) and 10% of the full level
- (critical).
- According the PRINTER-MIB it's possible that a printer couldn't determine
- how much is remaining in a supply, so the printer says "some remaining".
- This value produces a warning.
+ This check monitors the remaining level of a printer's supplies, such as toner, fuser, or waste box.
+ The printer must support the generic PRINTER-MIB.
+ The default check levels are 20% (warning) and 10% (critical) of the full supply level.
+ According to the PRINTER-MIB, it is possible that a printer cannot determine the exact remaining amount in a supply and instead reports "some remaining."
+ This status will result in a warning. However, this is customizable via service parameter.
+ Some printers may report a supply level in an unsusual way, e.g., used ink instead of remaining, or space left in waste box instead of space used.
+ The check can't detect this situation, but you can correct the value by applying the service parameter {Upturn supply levels}.
 
- In case of OKI c5900 devices the name of the supply units ins not unique.
- One example is {Toner Cartridge OKI DATA CORP}. In this case the color of
- the supply unit is added to the beginning of the name to get a unique
- item name.
+ For OKI c5900 devices, the names of the supply units are not unique.
+ For example, one supply might be named {Toner Cartridge OKI DATA CORP}. In such cases, the color of the supply unit is added to the beginning of the name to create a unique item name.
 
 item:
- The description of the printer
+ The description of the printer supply unit.
 
 discovery:
  One service is created for each supply unit with a unique name.
+ The service always shows remaining supply. E.g., remaining ink, remaining space in waste box.

tests/unit/cmk/plugins/collection/agent_based/test_printer_supply.py

@@ -350,6 +350,34 @@ def test_inventory_printer_supply(
                 Metric("supply_toner_magenta", 75.0),
             ],
         ),
+        (
+            "Waste box that shows space used",
+            DEFAULT_PARAMETERS,
+            [
+                [["1.1", "waste"]],
+                [
+                    ["Waste box that shows space used", "19", "5000", "1000", "4", "1"],
+                ],
+            ],
+            [
+                Result(state=State.OK, summary="Supply level remaining: 80.00%"),
+                Metric("supply_toner_other", 80.0),
+            ],
+        ),
+        (
+            "Waste box that shows space left",
+            DEFAULT_PARAMETERS | {"upturn_toner": True},
+            [
+                [["1.1", "waste"]],
+                [
+                    ["Waste box that shows space left", "19", "5000", "1000", "4", "1"],
+                ],
+            ],
+            [
+                Result(state=State.OK, summary="Supply level remaining: 20.00%"),
+                Metric("supply_toner_other", 20.0),
+            ],
+        ),
     ],
 )
 def test_check_printer_supply(