Feature/report filament usage (#40)

* Add filament usage reporting patch

Patch that adds to PrintStats JSON output to include cumulative and 250ms delta filament usage. See readme for more info

* Update README.md

* Make patch.sh executable

Author: harpua555

oc-patches/patch_config

@@ -26,4 +26,5 @@ HOME_POSITION_FRONT_RIGHT=true
 REPLACE_BOOTLOGO=true
 SET_FIRMWARE_VERSION=true
 ALWAYS_ALLOW_Z_OFFSET_ADJUST=true
-WAIT_FOR_CHAMBER_TEMP=true
+WAIT_FOR_CHAMBER_TEMP=true
+REPORT_FILAMENT_USAGE=true

oc-patches/report-filament-usage/README.md

@@ -0,0 +1,68 @@
+# Filament Usage JSON Patch
+
+This patch extends the existing `PrintStats` JSON
+structure to report filament usage in two forms:
+
+- **Cumulative usage** (total extruded E position for the print, retractions included as negative values to preserve actual length)
+- **Current usage delta** (current total minus last total, 250ms cycle)
+
+The new values are reported as additional JSON key–value pairs built by the
+patched JSON writer.
+
+---
+
+## Technical
+
+- Hooks an existing **PrintStats JSON writer** and branches into a new
+  function in unused executable space.
+- The function...
+  - Loads the current total E position from the motion planner via pointer offset.
+  - Stores this value into an unused `.bss` location for later comparison.
+  - Computes the delta between the current E position and the last stored
+    E position (representing filament called over the last 250 ms).
+  - Builds and reports two new JSON key–value pairs and injects them into the
+    existing PrintStats output.
+- The JSON keys themselves are **hex strings**, stored in the binary at fixed
+  addresses and interpreted by the Home Assistant integration
+  (TODO: push the HA fork that decodes these keys).
+
+---
+
+## Patched regions
+
+All offsets below are **file offsets** (0-based) as seen in Binary Ninja.
+
+### 1. Branch
+
+- **Address**: `0x002DEB18` (also clobber `0x002DEB20`, redundant due to in-function registers)
+- Patches an existing JSON writer site so that execution branches to the new
+  asm, then returns back to the stock code path.
+
+### 2. New assembly instructions
+
+- **Range**: `0x00392680` – `0x00392747`
+- Implements the new logic:
+
+  - Saves/restores the necessary registers and VFP state.
+  - Loads the current E‐axis commanded position from motion planner (Printer pointer in the transpiled cpp)
+    and stores it into safe `.bss` locations.
+  - Computes the 250 ms extrusion delta using the previous value stored in `.bss`.
+  - Builds two additional JSON key–value pairs and calls the existing JSON helper
+    used elsewhere in the firmware.
+  - Returns back to the original JSON writer using the loaded address target.
+
+### 3. String / key storage
+
+Two constant strings (hex key representations) are stored near the code cave:
+
+1. **Total filament usage key**
+
+   - **Address**: `0x003925A0`
+   - **Contents**: first key string (hex) used for **total filament usage**.
+
+2. **Current delta usage key**
+
+   - **Address**: `0x00392630`
+   - **Contents**: second key string (hex) used for the **current 250 ms delta**.
+
+These strings are referenced only by the new and are placed before it to preserve patchable 0-byte addresses.

oc-patches/report-filament-usage/patch.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+if [ $UID -ne 0 ]; then
+  echo "Error: Please run as root."
+  exit 1
+fi
+
+set -e
+
+project_root="$REPOSITORY_ROOT"
+source "$project_root/TOOLS/helpers/utils.sh" "$project_root"
+check_tools "bspatch"
+
+cd "$SQUASHFS_ROOT/app"
+bspatch ./app ./app-patch "$CURRENT_PATCH_PATH/report_filament_usage_patch.bsdiff"
+rm ./app
+mv ./app-patch ./app

oc-patches/report-filament-usage/patch.toml

@@ -0,0 +1,4 @@
+id = "report_filament_usage"
+name = "Adds both cumulative filament usage (per print) and filament requested per 250ms exports in PrintStats JSON"
+after = ["base"]
+compatible_versions = ["1.1.40"]