# 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:

- [zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.html](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.html#L11)
- [PA-44Z/homebus-adapter/z2m-pa-44z-homebus.html](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.html#L11)

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:

1. se citeste `payload.battery`
2. valoarea este clamp-uita in intervalul `0..100`
3. daca tipul bateriei este `nimh`, procentul este convertit mai intai intr-o tensiune echivalenta pe o curba `alkaline`
4. tensiunea echivalenta este proiectata pe o curba `NiMH`
5. valoarea rezultata este publicata pe capabilitatea `battery`
6. `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](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js#L214)

Configurarea tipului de baterie:

- [zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js#L34)

Unde este folosita functia:

- pentru `battery`: [zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js#L146)
- pentru `battery_low`: [zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.js#L164)

Functia:

```js
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](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js#L84)

Configurarea tipului de baterie:

- [PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js#L9)

Unde este folosita functia:

- pentru `battery`: [PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js#L215)
- pentru derivarea `battery_low`: [PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.js#L217)

Functia:

```js
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:

- [zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.html](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/zg-204zv/homebus-adapter/z2m-zg-204zv-homebus.html#L64)
- [PA-44Z/homebus-adapter/z2m-pa-44z-homebus.html](/Users/bogdan/Documents/Workspaces/Home/NodeRed/myNodes/PA-44Z/homebus-adapter/z2m-pa-44z-homebus.html#L60)

## 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.