AcTemperatureDerating

Applies AC current limits to an EnergyNode based on temperature sensor readings and configurable derating curves using linear interpolation between points.

Handwritten Documentation

AcTemperatureDerating

Applies AC current limits to an EnergyNode based on temperature_sensor readings and configurable derating curves (linear interpolation between points).

Requirements

Energy tree placement

Place a dedicated EnergyNode for temperature derating between the grid connection and downstream nodes. The EnergyManager merges limits from all nodes; OCPP/API external limits on other nodes continue to work independently.

Configuration

derating_curves_json is a nested object {module_id: {identification: point_array}} where each point array holds {"temp_C", "max_current_A"} points.

  • module_id: temperature provider instance id from the Everest config (active_modules / connections.temperature.module_id)

  • identification: Temperature.identification published by that provider

Every connected temperature provider must have at least one curve. Providers publishing multiple temperature values need one curve per identification. The effective limit is the minimum across all readings. Missing curves log a warning and use fallback_max_current_A. Temperature readings without identification are treated as misconfigured and also use fallback_max_current_A.

temperature_provider_ignore_list is a comma-separated list of module_id.identification entries to exclude from derating. If a derating curve is configured for an ignored entry, the module fails to start.

Runtime behaviour

  • Stale readings: After temperature_stale_timeout_ms without an update, a reading is treated as stale and fallback_max_current_A applies. Limits are re-evaluated periodically (at most half the stale timeout) so a provider that stops publishing still triggers fallback.

  • Limit decreases (more derating, e.g. temperature rising) are published immediately.

  • Limit increases (relaxing derating, e.g. temperature falling) are debounced by update_debounce_ms; the periodic re-evaluation retries a debounced increase once the window has elapsed.

Example module config:

ac_temp_derating:
  module: AcTemperatureDerating
  config_module:
    fallback_max_current_A: 0
    temperature_stale_timeout_ms: 10000
    update_debounce_ms: 1000
    derating_curves_json: |
      {"cgem580": {"Powermeter": [{"temp_C": 25, "max_current_A": 32}, {"temp_C": 70, "max_current_A": 10}]}}
  connections:
    temperature:
      - module_id: cgem580
        implementation_id: temperature_sensor
    energy_node:
      - module_id: temp_derate_node
        implementation_id: external_limits

No derating (constant limit at all temperatures):

derating_curves_json: |
  {"yeti_driver_1": {"Powermeter": [{"temp_C": -20, "max_current_A": 32}, {"temp_C": 25, "max_current_A": 32}, {"temp_C": 80, "max_current_A": 32}]}}

See also config/config-sil-ac-temp-derating.yaml for a full SIL example using TemperatureSensorSimulator.

Auto-Generated Reference

Module Configuration

derating_curves_json: string <optional>
default: “{}”
Nested JSON object: {module_id: {identification: point_array}}. Each point array holds derating points {“temp_C”: number, “max_current_A”: number}. Points may be in any order (the module sorts by ascending temp_C); duplicate temp_C values are rejected. The curve is defined from its first point upward: below the first point’s temp_C no derating is applied (that sensor imposes no limit), between points the module linearly interpolates, and at/above the last point the final limit is held. A single-point curve therefore means “no limit below temp_C, cap at max_current_A at/above temp_C”. To cap current even at low temperatures, place the first point at a sufficiently low temperature.
module_id is the temperature provider instance id from active_modules / connections.temperature.module_id (not the module type name and not implementation_id). identification is Temperature.identification from the published reading. Each Temperature.identification in a batch needs a matching curve. Readings without identification log a warning and use fallback_max_current_A.
Every connected temperature provider must have at least one curve. Missing curves at runtime log a warning and apply fallback_max_current_A.
No derating (constant limit at all temperatures): { “my_module”: {
“Powermeter”:[
{“temp_C”: -20, “max_current_A”: 32},
{“temp_C”: 25, “max_current_A”: 32},
{“temp_C”: 80, “max_current_A”: 32}
]
}
}
With derating (one provider, two identifications): { “yeti_driver_1”:{
“Powermeter”:[
{ “temp_C”:25, “max_current_A”:32 },
{ “temp_C”:40, “max_current_A”:16 },
{ “temp_C”:55, “max_current_A”:6 }
],
“Connector”:[
{ “temp_C”:30, “max_current_A”:32 },
{ “temp_C”:60, “max_current_A”:10 }
]
}
}
temperature_provider_ignore_list: string <optional>
default: “”
Comma-separated list of module_id.identification entries to exclude from derating. module_id is the temperature provider instance id from connections.temperature.module_id. identification is Temperature.identification from the published reading. Ignored readings do not contribute to the effective limit. Configuring a derating curve for an ignored entry prevents module startup.
fallback_max_current_A: number <optional>
default: 0.0
Conservative limit applied when a temperature reading is missing, stale, or has no matching curve
temperature_stale_timeout_ms: integer <optional>
default: 10000
Time after which a temperature reading is considered stale. The module also re-evaluates limits periodically (at most half this interval) so staleness is detected even when a provider stops publishing.
update_debounce_ms: integer <optional>
default: 1000
Minimum time between external limit updates when the computed limit increases (relaxing derating). Limit decreases are applied immediately for thermal safety. Debounced increases are retried on the periodic re-evaluation.

Requirements

temperature: temperature_sensor 1..16
energy_node: external_energy_limits 1

Metadata

Authors

florin.mihut@pionix.com

License

https://opensource.org/licenses/Apache-2.0