Skip to content

v0.0.21

Choose a tag to compare

View all tags
@chris1howell chris1howell released this 30 Aug 00:06
· 6 commits to OpenEVSE9 since this release
v0.0.21
caad0b3

OpenEVSE_Lib 0.0.21

Branch: OpenEVSE9

New: relay contact-life health API

Adds client support for the controller's new relay-health RAPI commands
($GL / $FH, firmware open_evse dev branch commit 442a98f), following
the same D9-gated pattern as the existing getFrequency() /
getRelayStatus() / resetFaultCounters() helpers.

OpenEVSEClass::getRelayHealth(callback)

Sends $GL and reports the controller's cumulative-damage relay-life
estimate:

OpenEVSE.getRelayHealth([](int ret, uint8_t life_remaining_pct,
                            uint32_t cold_open_count, uint32_t elec_damage_x1e6,
                            uint32_t transit_baseline_ms, bool transit_drift_warning,
                            uint32_t thermal_index_x100, uint32_t thermal_baseline_x100,
                            uint8_t thermal_warning_level)
{
  if (ret == RAPI_RESPONSE_OK) {
    Serial.printf("Relay life remaining: %u%%\n", life_remaining_pct);
  }
});
Field Meaning
life_remaining_pct 0-100: Miner's-rule electrical-damage accumulator (hot opens, weighted by (I/I_rated)^2 × load-character × temperature) combined with a mechanical-damage term (cold opens / rated mechanical life)
cold_open_count cumulative cold (non-arced) relay-open count
elec_damage_x1e6 raw electrical-damage accumulator, millionths of rated electrical life consumed (debug/trend field)
transit_baseline_ms self-learned open (drop-out) transit-time baseline; OPENEVSE_RELAY_HEALTH_NOT_AVAILABLE until established (needs 8 post-reset measurements; requires CGMI hardware)
transit_drift_warning true if the live open-transit time has drifted ≥1.5x the baseline - an early symptom of contact welding, ahead of the hard stuck-relay fault
thermal_index_x100 most recent ΔT/I² sample ×100, proportional to contact resistance; OPENEVSE_RELAY_HEALTH_NOT_AVAILABLE if not available (needs TEMPERATURE_MONITORING on the controller)
thermal_baseline_x100 self-learned baseline H0 ×100; same "not available" sentinel
thermal_warning_level 0 = ok/not available, 1 = watch (≥1.5x baseline), 2 = warn (≥2x baseline)

OpenEVSEClass::resetRelayHealth(callback)

Sends $FH. Clears the cumulative-damage accumulator and the transit-time/
thermal-index self-learned baselines - call this after physically replacing
the contactor, so the estimate doesn't carry over wear from the old relay.

New constant

OPENEVSE_RELAY_HEALTH_NOT_AVAILABLE (0xffff) - sentinel for the
transit-baseline and thermal fields above when that signal isn't available
yet, or at all (thermal fields require TEMPERATURE_MONITORING on the
controller).

Requirements

Both calls are gated by isD9Supported() (RAPI protocol ≥ 6.0.0) like the
other D9 extensions, and additionally require the controller to have been
built with the RELAY_HEALTH firmware feature (auto-enabled wherever the
existing $GW/$GZ relay-life diagnostics are). A controller without it
returns RAPI_RESPONSE_FEATURE_NOT_SUPPORTED / a normal RAPI NAK for $GL/
$FH, not a crash.

Changes

  • src/openevse.h / src/openevse.cpp: added getRelayHealth(),
    resetRelayHealth(), OPENEVSE_RELAY_HEALTH_NOT_AVAILABLE.
  • library.json: version bump 0.0.20 → 0.0.21.

Upgrading

No breaking changes - existing calls are unaffected. New calls are safe to
use against older controllers; they'll simply report "not supported" until
the firmware side (RELAY_HEALTH) is deployed.

Assets 2
Loading