Conversie nivel baterie intre `NiMH` si `alkaline`

Scop

In acest repository exista o conversie configurabila pentru nivelul bateriei raportat de Zigbee2MQTT, folosita atunci cand dispozitivul are baterii reincarcabile NiMH in loc de baterii alkaline.

Motivatia este simpla: multe dispozitive raporteaza procentul bateriei pe o curba calibrata mai degraba pentru baterii alcaline, iar celulele NiMH au o curba de descarcare mai plata. Din acest motiv, procentul brut poate parea prea mic pentru baterii NiMH, mai ales in zona de mijloc a descarcarii.

Comportamentul este:

daca batteryType este alkaline, valoarea ramane neschimbata
daca batteryType este nimh, valoarea este remapata printr-o conversie bazata pe curbe aproximative alkaline -> tensiune -> NiMH
valoarea convertita este folosita atat pentru publicarea capabilitatii battery, cat si pentru derivarea lui battery_low atunci cand dispozitivul nu furnizeaza explicit acest camp

Configurare

Conversia este controlata din UI-ul nodurilor Node-RED prin campul Battery type, cu valoarea implicita alkaline.

Referinte UI:

Valorile disponibile sunt:

alkaline
nimh

Pragul pentru battery_low este separat si configurabil prin batteryLowThreshold, implicit 20.

Implementare generala

Fluxul logic este acelasi in ambele adaptoare:

se citeste payload.battery
valoarea este clamp-uita in intervalul 0..100
daca tipul bateriei este nimh, procentul este convertit mai intai intr-o tensiune echivalenta pe o curba alkaline
tensiunea echivalenta este proiectata pe o curba NiMH
valoarea rezultata este publicata pe capabilitatea battery
battery_low se calculeaza din valoarea convertita daca dispozitivul nu trimite deja un camp battery_low

Proiecte care folosesc functia

1. `zg-204zv/homebus-adapter`

Implementarea este in:

zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js

Configurarea tipului de baterie:

zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js

Unde este folosita functia:

pentru battery: zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js
pentru battery_low: zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js

Functia:

var ALKALINE_BATTERY_CURVE = [
  { pct: 100, voltage: 1.60 },
  { pct: 90, voltage: 1.55 },
  { pct: 80, voltage: 1.50 },
  { pct: 70, voltage: 1.46 },
  { pct: 60, voltage: 1.42 },
  { pct: 50, voltage: 1.36 },
  { pct: 40, voltage: 1.30 },
  { pct: 30, voltage: 1.25 },
  { pct: 20, voltage: 1.20 },
  { pct: 10, voltage: 1.10 },
  { pct: 0, voltage: 0.90 }
];

var NIMH_BATTERY_CURVE = [
  { pct: 100, voltage: 1.40 },
  { pct: 95, voltage: 1.33 },
  { pct: 90, voltage: 1.28 },
  { pct: 85, voltage: 1.24 },
  { pct: 80, voltage: 1.20 },
  { pct: 75, voltage: 1.19 },
  { pct: 70, voltage: 1.18 },
  { pct: 60, voltage: 1.17 },
  { pct: 50, voltage: 1.16 },
  { pct: 40, voltage: 1.15 },
  { pct: 30, voltage: 1.13 },
  { pct: 20, voltage: 1.11 },
  { pct: 10, voltage: 1.07 },
  { pct: 0, voltage: 1.00 }
];

function translateBatteryLevel(rawValue) {
  if (rawValue === undefined) return undefined;
  var raw = clamp(Math.round(Number(rawValue)), 0, 100);
  if (node.batteryType !== "nimh") return raw;

  var estimatedVoltage = interpolateCurve(ALKALINE_BATTERY_CURVE, "pct", "voltage", raw);
  var nimhPct = interpolateCurve(NIMH_BATTERY_CURVE, "voltage", "pct", estimatedVoltage);
  return clamp(Math.round(nimhPct), 0, 100);
}

Observatii:

remaparea nu mai este o euristica pe praguri, ci o interpolare liniara intre doua curbe aproximative
procentul alkaline este reinterpretat ca tensiune echivalenta pe celula
tensiunea rezultata este apoi tradusa in procent NiMH
valoarea de referinta 1.20V pe celula este tratata ca o zona inca sanatoasa pentru NiMH, nu ca baterie aproape goala

Exemple:

Brut	Convertit `nimh`
5	0
10	18
20	80
25	83
30	86
40	92
50	97
60	100
80	100
100	100

Impact functional:

battery/value publica procentul convertit
battery_low/value este calculat din procentul convertit daca nu exista deja battery_low in payload
la pragul implicit 20, un raw=5 devine 25, deci nu va fi marcat imediat ca battery_low

2. `PA-44Z/homebus-adapter`

Implementarea este in:

PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js

Configurarea tipului de baterie:

PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js

Unde este folosita functia:

pentru battery: PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js
pentru derivarea battery_low: PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js

Functia:

var ALKALINE_BATTERY_CURVE = [
  { pct: 100, voltage: 1.60 },
  { pct: 90, voltage: 1.55 },
  { pct: 80, voltage: 1.50 },
  { pct: 70, voltage: 1.46 },
  { pct: 60, voltage: 1.42 },
  { pct: 50, voltage: 1.36 },
  { pct: 40, voltage: 1.30 },
  { pct: 30, voltage: 1.25 },
  { pct: 20, voltage: 1.20 },
  { pct: 10, voltage: 1.10 },
  { pct: 0, voltage: 0.90 }
];

var NIMH_BATTERY_CURVE = [
  { pct: 100, voltage: 1.40 },
  { pct: 95, voltage: 1.33 },
  { pct: 90, voltage: 1.28 },
  { pct: 85, voltage: 1.24 },
  { pct: 80, voltage: 1.20 },
  { pct: 75, voltage: 1.19 },
  { pct: 70, voltage: 1.18 },
  { pct: 60, voltage: 1.17 },
  { pct: 50, voltage: 1.16 },
  { pct: 40, voltage: 1.15 },
  { pct: 30, voltage: 1.13 },
  { pct: 20, voltage: 1.11 },
  { pct: 10, voltage: 1.07 },
  { pct: 0, voltage: 1.00 }
];

function translateBatteryLevel(rawValue) {
  if (rawValue === null || rawValue === undefined) return null;
  var raw = clamp(Math.round(Number(rawValue)), 0, 100);
  if (node.batteryType !== "nimh") return raw;

  var estimatedVoltage = interpolateCurve(ALKALINE_BATTERY_CURVE, "pct", "voltage", raw);
  var nimhPct = interpolateCurve(NIMH_BATTERY_CURVE, "voltage", "pct", estimatedVoltage);
  return clamp(Math.round(nimhPct), 0, 100);
}

Observatii:

foloseste aceeasi conversie bazata pe curbe ca adaptorul ZG-204ZV
rezultatul este continuu si mai aproape de comportamentul electric asteptat pentru NiMH

Exemple:

Brut	Convertit `nimh`
5	0
10	18
15	40
20	80
30	86
50	97
55	98
95	100

Impact functional:

battery publicat pe HomeBus este valoarea convertita
daca payload.battery_low lipseste, acesta este derivat din valoarea convertita si comparat cu batteryLowThreshold

Diferente intre cele doua implementari

In varianta actuala, ambele adaptoare folosesc aceeasi abordare bazata pe curbe, pentru a evita discrepantele dintre proiecte.

Referinte suplimentare in documentatia UI

Explicatiile din help-ul nodurilor confirma intentia conversiei:

Concluzie

In starea actuala a repository-ului, functia de conversie intre NiMH si alkaline este folosita in doua proiecte:

zg-204zv/homebus-adapter
PA-44Z/homebus-adapter

Ambele aplica conversia doar cand batteryType este setat la nimh, iar pentru alkaline publica procentul brut primit de la Zigbee2MQTT.

Conversie nivel baterie intre NiMH si alkaline