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