feat(qn): add ble.qn_report_byte so the history-response byte can be tested

The handshake answers the scale's 0x21 config request with
`a0 0d 04 fe 00 ...`. That 0xFE comes from openScale's QNHandler, which took it
from an ES-30M capture and annotates it only as a payload byte.

Two vendor-app captures on other firmware in the family send 0xFC in the same
position: a GE CS 10 G on the 20-byte extended dialect (#235) and an Arboleaf
QN-Scale FW V39 on the 19-byte es26m dialect (#75). Both were taken from
sessions where the vendor app completed a weigh-in, on scales where this adapter
sees the entire handshake acknowledged and then silence. Two reporters reached
the same reading of the byte independently, that it chooses between a live
report stream and the stored-history path.

The default does not move, because that reading is not established: openScale
dispatches live 0x10 weight frames while sending 0xFE, and the 0x23 stored-record
path this adapter relies on for V10 Renpho and ES-CS20M firmware (#213) hangs off
the same exchange. A wrong value here is silent in exactly the way a wrong
qn_protocol_byte is, so guessing would trade a diagnosable failure for an
undiagnosable one. The setting lets the reporters run the experiment on their own
hardware, and the default changes when it produces a reading.

Both QN bytes are now reachable from the Home Assistant add-on as well. They
were previously custom_config only, which is not a usable escape hatch for the
reporters who need them, since all three run the add-on. They are text options so
that unset stays distinguishable from 0, and a value outside 0 to 255 is dropped
with a warning rather than written into a config that would then fail validation.

The A00D pair had no test coverage at all; it now has three tests, one of which
pins that the second frame does not move with the first.

Refs #235, #75, #331

Author: KristianP26

ble-scale-sync-addon/config.yaml

@@ -38,6 +38,8 @@ options:
   scale_mac: ''
   ble_adapter: ''
   force_scale_adapter: ''
+  qn_protocol_byte: ''
+  qn_report_byte: ''
   weight_unit: kg
   height_unit: cm
   user_name: Default
@@ -66,6 +68,8 @@ schema:
   scale_mac: str?
   ble_adapter: str?
   force_scale_adapter: str?
+  qn_protocol_byte: str?
+  qn_report_byte: str?
   weight_unit: list(kg|lbs)
   height_unit: list(cm|in)
   user_name: str

ble-scale-sync-addon/run.sh

@@ -45,6 +45,8 @@ else
 
   SCALE_MAC=$(opt scale_mac)
   FORCE_SCALE_ADAPTER=$(opt force_scale_adapter)
+  QN_PROTOCOL_BYTE=$(opt qn_protocol_byte)
+  QN_REPORT_BYTE=$(opt qn_report_byte)
 
   WEIGHT_UNIT=$(opt weight_unit)
   HEIGHT_UNIT=$(opt height_unit)
@@ -135,12 +137,31 @@ YAML
     FORCE_SCALE_ADAPTER=""
   fi
 
-  # BLE section (only if scale_mac, adapter or a forced scale adapter is set)
-  if [ -n "$SCALE_MAC" ] || [ -n "$BLE_ADAPTER" ] || [ -n "$FORCE_SCALE_ADAPTER" ]; then
+  # The two QN bytes are text options so that "unset" stays distinguishable from
+  # 0, which is a meaningful value for both. Anything that is not a plain 0 to
+  # 255 integer is dropped with a warning rather than written into config.yaml,
+  # where it would fail schema validation and stop the add-on from starting.
+  for _qn in QN_PROTOCOL_BYTE QN_REPORT_BYTE; do
+    eval "_qv=\$$_qn"
+    [ -z "$_qv" ] && continue
+    case "$_qv" in
+      ''|*[!0-9]*) _ok=0 ;;
+      *) [ "$_qv" -le 255 ] && _ok=1 || _ok=0 ;;
+    esac
+    if [ "$_ok" != "1" ]; then
+      log "WARNING: Invalid $(echo "$_qn" | tr '[:upper:]' '[:lower:]') '$_qv' (expected 0 to 255). Ignoring."
+      eval "$_qn=''"
+    fi
+  done
+
+  # BLE section (only if scale_mac, adapter, a forced scale adapter or a QN byte is set)
+  if [ -n "$SCALE_MAC" ] || [ -n "$BLE_ADAPTER" ] || [ -n "$FORCE_SCALE_ADAPTER" ]     || [ -n "$QN_PROTOCOL_BYTE" ] || [ -n "$QN_REPORT_BYTE" ]; then
     echo "ble:" >> "$FRESH"
     [ -n "$SCALE_MAC" ] && echo "  scale_mac: \"$(yaml_escape "$SCALE_MAC")\"" >> "$FRESH"
     [ -n "$BLE_ADAPTER" ] && echo "  adapter: \"$(yaml_escape "$BLE_ADAPTER")\"" >> "$FRESH"
     [ -n "$FORCE_SCALE_ADAPTER" ] && echo "  force_scale_adapter: \"$(yaml_escape "$FORCE_SCALE_ADAPTER")\"" >> "$FRESH"
+    [ -n "$QN_PROTOCOL_BYTE" ] && echo "  qn_protocol_byte: $QN_PROTOCOL_BYTE" >> "$FRESH"
+    [ -n "$QN_REPORT_BYTE" ] && echo "  qn_report_byte: $QN_REPORT_BYTE" >> "$FRESH"
     echo "" >> "$FRESH"
   fi
 

ble-scale-sync-addon/translations/en.yaml

@@ -19,6 +19,20 @@ configuration:
       (e.g. Hutbit). Requires the scale MAC to be set, because a forced adapter
       claims every device it is shown. Please also report the misdetection so it
       can be fixed for everyone.
+  qn_protocol_byte:
+    name: QN protocol byte
+    description: >-
+      QN-family scales only (Renpho, Arboleaf, FITINDEX, GE and rebadges).
+      Leave empty unless your QN scale connects, completes the whole handshake
+      in the log and then never reports a weight. Then try 0, or 255, or the
+      value the "QN: scale info" log line shows as proto. Accepts 0 to 255.
+  qn_report_byte:
+    name: QN history response byte
+    description: >-
+      QN-family scales only, and only worth trying after the QN protocol byte
+      did not help. Try 252, which is what vendor-app captures of a GE CS 10 G
+      and an Arboleaf QN-Scale send where this add-on sends the default 254.
+      Accepts 0 to 255.
   weight_unit:
     name: Weight unit
     description: >-

docs/guide/configuration.md

@@ -60,6 +60,7 @@ ble:
   # force_scale_adapter: 'Hutbit'
   # session_timeout_sec: 20
   # qn_protocol_byte: 0
+  # qn_report_byte: 252
 ```
 
 | Field                 | Required                    | Default        | Description                                                                                                                                                                                                                                        |
@@ -72,6 +73,7 @@ ble:
 | `force_scale_adapter` | No                          | Auto-detect    | Name of the scale protocol adapter to use, bypassing auto-detection. Requires `scale_mac`. See below.                                                                                                                                              |
 | `session_timeout_sec` | No                          | `120`          | Seconds one GATT session may wait for a complete reading (5 to 600). Native BLE handlers only; ignored on `mqtt-proxy` and `esphome-proxy`. See below.                                                                                             |
 | `qn_protocol_byte`    | No                          | Auto           | QN-family scales only. Protocol byte the handshake echoes back to the scale (0 to 255). Set it when a QN scale runs the whole handshake and then reports nothing, or when its scale-info frame is lost in transit on a proxy transport. See below. |
+| `qn_report_byte`      | No                          | `254` (0xFE)   | QN-family scales only. Payload byte of the history-response frame (0 to 255). Try `252` (0xFC) when a QN scale completes the handshake and then reports nothing. See below.                                                                        |
 | `mqtt_proxy`          | If `handler: mqtt-proxy`    | (none)         | MQTT proxy connection (`broker_url`, `device_id`, `topic_prefix`, `username`, `password`, `auto_connect`, `embedded_broker_*`). See [ESP32 BLE Proxy](./esp32-proxy).                                                                              |
 | `esphome_proxy`       | If `handler: esphome-proxy` | (none)         | ESPHome Native API connection (`host`, `port`, `encryption_key` or `password`, `client_info`). See [ESPHome Bluetooth Proxy](./esphome-proxy).                                                                                                     |
 
@@ -118,6 +120,36 @@ If a value makes your scale work, please say so in an issue with the model and t
 
 :::
 
+::: tip QN scales that still report nothing (`qn_report_byte`)
+
+If `qn_protocol_byte` did not help, there is one more byte worth trying, and it is a separate one.
+
+When the scale asks for its configuration (`0x21`), the handshake answers with a history-response frame:
+
+```
+a0 0d 04 fe 00 00 00 00 00 00 00 00 <checksum>
+                ^^
+```
+
+That `fe` comes from openScale, which took it from a capture of an ES-30M and labels it only as a payload byte. Vendor-app captures of two other scales in the family send `fc` in the same position: a GE CS 10 G and an Arboleaf QN-Scale on firmware V39. Both captures are of sessions where the vendor app completed a weigh-in, on scales where this app sees the whole handshake acknowledged and then nothing.
+
+What the byte actually selects is not known. Both reporters read it as choosing between a live weight stream and the stored-history path, which fits their symptoms, but openScale receives live weight frames while sending `fe`, so that reading cannot be the whole story. The default therefore stays where the evidence is:
+
+```yaml
+ble:
+  qn_report_byte: 252 # 0xFC, the value both vendor-app captures send
+```
+
+With debug logging on, a session running an overridden byte says so:
+
+```
+QN: history response byte forced to 0xfc (default 0xfe)
+```
+
+If `252` makes your scale produce a weight, please say so in an issue with the model, the dialect from the `QN: scale info` line and that log line. Two confirmations on different firmware would be enough to move the default.
+
+:::
+
 ::: tip Shortening the session (`session_timeout_sec`)
 Some scales will not run a standalone weigh-in while a host holds the GATT session open. The Beurer BF500 is the clearest example: it displays `APP` and waits, so only a measurement taken **between** sessions is picked up.
 

src/config/schema.ts

@@ -140,6 +140,26 @@ export const BleSchema = z
      * (proxy transports) and sessions without it open on the wrong byte.
      */
     qn_protocol_byte: z.number().int().min(0).max(255).optional().nullable(),
+    /**
+     * Payload byte of the QN A00D history-response frame, default 0xFE (#235,
+     * #75, #331).
+     *
+     * The handshake answers the scale's 0x21 config request with
+     * `a0 0d 04 <byte> 00 ...`. The default comes from openScale's QNHandler,
+     * which took it from an ES-30M capture. Two vendor-app captures on other
+     * firmware in the same family send 0xFC there instead: a GE CS 10 G (20-byte
+     * dialect) and an Arboleaf QN-Scale V39 (19-byte es26m), both from sessions
+     * that produced a reading in the vendor app while ble-scale-sync saw the
+     * handshake acknowledged and then silence.
+     *
+     * What the byte selects is NOT decoded. openScale annotates it only as
+     * "Payload", and it demonstrably does not gate the live 0x10 stream, since
+     * openScale receives those frames while sending 0xFE. So this ships as a
+     * setting rather than a changed default: on a scale that reads today, 0xFE
+     * is the value with evidence behind it, and a wrong choice here is silent in
+     * exactly the way `qn_protocol_byte` is.
+     */
+    qn_report_byte: z.number().int().min(0).max(255).optional().nullable(),
     mqtt_proxy: MqttProxySchema.optional(),
     esphome_proxy: EsphomeProxySchema.optional(),
   })

src/index.ts

@@ -286,7 +286,8 @@ async function main(): Promise<void> {
   const applyAdapterConfig = (bindKey: string | undefined): void => {
     const weightUnit = ctx.config.scale.weight_unit;
     const qnProtocolByte = ctx.config.ble?.qn_protocol_byte ?? undefined;
-    for (const a of adapters) a.configure?.({ bindKey, weightUnit, qnProtocolByte });
+    const qnReportByte = ctx.config.ble?.qn_report_byte ?? undefined;
+    for (const a of adapters) a.configure?.({ bindKey, weightUnit, qnProtocolByte, qnReportByte });
   };
   applyAdapterConfig(ctx.config.ble?.bind_key ?? undefined);
 

src/interfaces/scale-adapter.ts

@@ -154,6 +154,16 @@ export interface AdapterRuntimeConfig {
    * The frame length picks a default; this overrides it (#75, #331).
    */
   qnProtocolByte?: number;
+  /**
+   * Payload byte of the QN A00D history-response frame (`ble.qn_report_byte`).
+   *
+   * Defaults to 0xFE, the value openScale's ES-30M capture uses. Two vendor-app
+   * captures on other firmware in the family send 0xFC instead, from sessions
+   * that read successfully where this adapter saw the whole handshake
+   * acknowledged and then silence. What the byte selects is not decoded, so it
+   * is a setting rather than a changed default (#235, #75, #331).
+   */
+  qnReportByte?: number;
 }
 
 /**

src/scales/qn-scale.ts

@@ -113,6 +113,34 @@ const CHR_SIG_WEIGHT_MEASUREMENT = uuid16(0x2a9d);
 /** Seconds from Unix epoch to 2000-01-01 00:00:00 UTC. */
 const SCALE_EPOCH_OFFSET = 946684800;
 
+/**
+ * Payload byte of the A00D history-response frame sent in reply to the scale's
+ * 0x21 config request: `a0 0d 04 <byte> 00 ...`.
+ *
+ * 0xFE comes from openScale's QNHandler, which annotates it only as "Payload"
+ * and took it from an ES-30M BLE capture. Two vendor-app captures on other
+ * firmware in this family send 0xFC in the same position instead:
+ *
+ *   #235  GE CS 10 G, 20-byte extended dialect
+ *   #75   Arboleaf QN-Scale FW V39, 19-byte es26m dialect
+ *
+ * Both were taken from sessions where the vendor app completed a weigh-in while
+ * this adapter saw the whole handshake acknowledged and then silence, and both
+ * reporters reached the same reading of it independently: that the byte selects
+ * between a live report stream and the stored-history path.
+ *
+ * That reading is NOT established, and the default therefore does not move.
+ * openScale dispatches live 0x10 weight frames while sending 0xFE, so the byte
+ * plainly does not gate the live stream on the firmware it was captured from,
+ * and the 0x23 stored-record path this adapter relies on for V10 Renpho and
+ * ES-CS20M firmware (#213) hangs off the same exchange. A wrong value here is
+ * silent in exactly the way a wrong `qn_protocol_byte` is: every command is
+ * acknowledged and no weight ever arrives. So `ble.qn_report_byte` exists to
+ * let the reporters test 0xFC on their own hardware, and the default changes
+ * only if that produces a reading.
+ */
+const REPORT_BYTE_DEFAULT = 0xfe;
+
 /**
  * Grace period (ms) to wait for an impedance frame after the first stable
  * R1=R2=0 frame on long-frame variants (e.g. ES-26M). If an impedance frame
@@ -339,6 +367,12 @@ export class QnScaleAdapter
    */
   private forcedProtocolType: number | null = null;
 
+  /**
+   * Payload byte of the A00D history-response frame, forced by
+   * `ble.qn_report_byte` (#235, #75, #331). Null leaves REPORT_BYTE_DEFAULT.
+   */
+  private forcedReportByte: number | null = null;
+
   /**
    * Whether a completed-weigh-in result frame (0xB4/0xB1) has already produced a
    * reading this session. The scale repeats the 0xB4 frame ~3x and then sends
@@ -379,6 +413,7 @@ export class QnScaleAdapter
   configure(opts: AdapterRuntimeConfig): void {
     if (opts.weightUnit) this.displayUnit = opts.weightUnit;
     this.forcedProtocolType = opts.qnProtocolByte ?? null;
+    this.forcedReportByte = opts.qnReportByte ?? null;
   }
 
   /** 0x13 config unit flag: 0x01 kg, 0x02 lb (openScale QNHandler). */
@@ -1132,9 +1167,31 @@ export class QnScaleAdapter
     this.historyResponseSent = true;
     const wait = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 
-    // A00D response 1 (from openScale QNHandler)
-    const msg1 = [0xa0, 0x0d, 0x04, 0xfe, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00];
+    // A00D response 1 (from openScale QNHandler). byte[3] is the payload byte
+    // `ble.qn_report_byte` overrides; see REPORT_BYTE_DEFAULT.
+    const msg1 = [
+      0xa0,
+      0x0d,
+      0x04,
+      this.forcedReportByte ?? REPORT_BYTE_DEFAULT,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+      0x00,
+    ];
     msg1[12] = msg1.reduce((a, b) => a + b, 0) & 0xff;
+    if (this.forcedReportByte !== null) {
+      bleLog.debug(
+        `QN: history response byte forced to ` +
+          `0x${this.forcedReportByte.toString(16).padStart(2, '0')} ` +
+          `(default 0x${REPORT_BYTE_DEFAULT.toString(16)})`,
+      );
+    }
     await this.writeCmd(msg1);
 
     await wait(200);

tests/config/schema.test.ts

@@ -390,6 +390,18 @@ describe('BleSchema', () => {
     }
   });
 
+  it('accepts ble.qn_report_byte across the whole byte range', () => {
+    for (const byte of [0, 0xfc, 0xfe, 255]) {
+      expect(BleSchema.safeParse({ qn_report_byte: byte }).success).toBe(true);
+    }
+  });
+
+  it('rejects a ble.qn_report_byte that is not a byte', () => {
+    for (const byte of [-1, 256, 1.5]) {
+      expect(BleSchema.safeParse({ qn_report_byte: byte }).success).toBe(false);
+    }
+  });
+
   it('rejects ble.session_timeout_sec outside 5 to 600', () => {
     for (const secs of [4, 601]) {
       expect(BleSchema.safeParse({ session_timeout_sec: secs }).success).toBe(false);

tests/scales/qn-scale.test.ts

@@ -1387,6 +1387,40 @@ describe('AE02 dispatch (#75, #235)', () => {
       expect(config).toEqual([0x13, 0x09, 0xff, 0x01, 0x10, 0x00, 0x00, 0x00, 0x2c]);
     });
 
+    // The A00D history-response pair had no coverage at all before #235/#75
+    // put its payload byte in question, so these pin both the default and the
+    // override.
+    it('sends the A00D history response with the default payload byte 0xFE', async () => {
+      const adapter = makeAdapter();
+      const writes = await driveHandshake(adapter, makeExtendedScaleInfo());
+      const msg1 = writes.find((w) => w[0] === 0xa0 && w[2] === 0x04);
+      expect(msg1).toBeDefined();
+      expect(msg1![3]).toBe(0xfe);
+      expect(msg1![12]).toBe(msg1!.slice(0, 12).reduce((a, b) => a + b, 0) & 0xff);
+    });
+
+    it('applies ble.qn_report_byte to the A00D payload byte and recomputes the checksum', async () => {
+      // 0xFC is the value both vendor-app captures send in this position.
+      const adapter = makeAdapter();
+      adapter.configure({ qnReportByte: 0xfc });
+      const writes = await driveHandshake(adapter, makeExtendedScaleInfo());
+      const msg1 = writes.find((w) => w[0] === 0xa0 && w[2] === 0x04);
+      expect(msg1![3]).toBe(0xfc);
+      expect(msg1![12]).toBe(msg1!.slice(0, 12).reduce((a, b) => a + b, 0) & 0xff);
+    });
+
+    it('leaves the second A00D frame alone when the report byte is overridden', async () => {
+      // Only byte[3] of the 0x04 frame is in question. The 0x02 frame is a
+      // separate command and must not move with it.
+      const adapter = makeAdapter();
+      adapter.configure({ qnReportByte: 0xfc });
+      const writes = await driveHandshake(adapter, makeExtendedScaleInfo());
+      const msg2 = writes.find((w) => w[0] === 0xa0 && w[2] === 0x02);
+      expect(msg2).toEqual([
+        0xa0, 0x0d, 0x02, 0x01, 0x00, 0x08, 0x00, 0x21, 0x06, 0xb8, 0x04, 0x02, 0x9d,
+      ]);
+    });
+
     it('20B 0x12 frame makes the 0x22 START byte identical to the vendor app', async () => {
       const adapter = makeAdapter();
       const writes = await driveHandshake(adapter, makeExtendedScaleInfo());