Skip to main content

Protocol version changelog

This page tracks changes to the Tensor Cloud battery optimization protocol. The version reflected here is info.version in the AsyncAPI specification and the schema_version field every EMS emits on every message.

Versioning follows semver-style: MAJOR.MINOR.PATCH.

  • MAJOR - backwards-incompatible changes to topic structure, payload shape, or required fields that existing integrations cannot satisfy without code changes.
  • MINOR - additive changes (new fields, new conditional validation, new behaviour) that strengthen guarantees but remain readable by clients on prior versions. Tensor Cloud remains backwards-compatible with messages emitted under older minor revisions.
  • PATCH - documentation clarifications, example corrections, and other changes with no payload impact. Because a PATCH release has no payload impact, the wire schema_version does not change: integrations keep emitting the current MINOR version (e.g. 2.3.0) until a MINOR or MAJOR release changes the payload.

2.6.0 - 2026-07-13​

Solar DC voltage and current telemetry for DC-linked systems. Additive and backward-compatible.

  • New solarDcTelemetry channel (dt/{siteId}/{gatewayId}/solar) with the SolarDcElectrical message and a sendSolarDc operation. DC-coupled (DC-link) PV plus battery sites publish the PV array's DC voltage (V) and current (A), measured at the DC link upstream of the inverter as a single value aggregated across the whole array. Voltage and current are sampled at the same instant and sent together as one matched pair, at 1-minute resolution. measurement_value carries voltage and current, each a {value, unit} object (unit is V or A, values ≥ 0). Applies only to DC-link sites; AC-coupled and stand-alone sites do not send it. See the integration guide's "DC-linked telemetry" section.
  • Wire schema_version bumps to 2.6.0. Per the versioning policy, a MINOR release changes the wire version, so integrations should emit schema_version: "2.6.0" going forward. Tensor Cloud remains backwards-compatible with messages emitted under prior versions.

2.5.0 - 2026-07-10​

Malformed telemetry can now be acknowledged. Additive and backward-compatible.

  • TelemetryFeedback.correlation_id is no longer constrained to the msg_ UUID pattern. When incoming telemetry cannot be parsed (MESSAGE_MALFORMED) and its message_id cannot be recovered, Tensor Cloud sets correlation_id to the sentinel string "unknown". Previously the pattern made such a feedback message impossible to construct, so no acknowledgement was sent at all and the integrator never learned the message had been rejected. If the message_id is partially recoverable, the recovered value is echoed instead. This mirrors the "unknown" sentinel already used by CommandResponse.command_id.
  • TelemetryFeedback gains an optional topic field carrying the topic the offending message was published on. It is present only when status is error, and is the only way to identify the rejected message when correlation_id is "unknown". The schema enforces its absence on status: "ok" through the same if/then/else block that already gates code and detail.
  • Corrected the Japanese TelemetryFeedback definition, which listed schema_version as required but never defined the property, leaving its examples invalid against their own schema.
  • Wire schema_version bumps to 2.5.0. Per the versioning policy, a MINOR release changes the wire version, so integrations should emit schema_version: "2.5.0" going forward. Tensor Cloud remains backwards-compatible with messages emitted under prior versions.

2.4.0 - 2026-07-06​

Grid frequency telemetry for FCR, plus a pre-qualification (事前審査) test flag. Both are additive and backward-compatible.

  • New gridFrequencyTelemetry channel (dt/{siteId}/{gatewayId}/frequency) with the GridFrequency message and a sendGridFrequency operation. Resources awarded FCR must publish grid frequency at 1 Hz for the full duration of every FCR-awarded slot, as the mean over each 1-second window, measured at the grid connection point from the live AC waveform and reported to at least 0.0001 Hz resolution. These readings are time-aligned with the 1 Hz supplied-power telemetry used for FCR Assessment II. See the integration guide's "FCR Assessment II reporting" section.
  • PowerInstant and GridFrequency gain an optional pre_qualification boolean. The EMS sets it to true on instantaneous-power and grid-frequency telemetry emitted while in FCR pre-qualification (事前審査) test mode, a mode the EMS operator activates, not Tensor Cloud. Tensor Cloud uses the flag to exclude that window from optimization and from FCR Assessment II submissions. Optional and backward-compatible: omitting it preserves normal-operation semantics.
  • Wire schema_version bumps to 2.4.0. Per the versioning policy, a MINOR release changes the wire version, so integrations should emit schema_version: "2.4.0" going forward. Tensor Cloud remains backwards-compatible with messages emitted under prior versions.

2.3.1 - 2026-06-29​

ACK and INTERNAL_ERROR semantics clarified. Documentation only: no payload changes.

  • Clarified that the CommandResponse.status field reflects validation and acceptance at receipt time, not the execution outcome. The ACK is sent immediately after the command is received, parsed, and committed (not at execution time) and cannot report a failure that surfaces only later at execution.
  • Clarified that INTERNAL_ERROR also covers a well-formed command that fails during receipt-time handling and cannot be accepted/committed before the ACK is sent (e.g. an internal failure committing a requested schedule change). Use INTERNAL_ERROR with a descriptive detail. Failures that surface only at execution time are reported through alerts/telemetry, not the ACK.
  • Documented that PATCH releases do not change the wire schema_version (see the versioning note above).

2.3.0 - 2026-06-16​

FCR Assessment II telemetry.

  • The instantaneous-power topics (dt/{siteId}/{gatewayId}/{metric}/power) are now documented as the channel for offline FCR Assessment II data. Resources offering FCR must publish 1-second-resolution supplied power for every FCR-awarded slot, via meter_export_ac/meter_import_ac (grid-connection-point registration) or battery_discharge_ac/battery_charge_ac (equipment-point registration). Tensor Cloud assembles the TSO's Assessment II template (Form 35) from this data and submits it on behalf of the aggregator. See the integration guide's "FCR Assessment II telemetry" section.
  • powerTelemetry channel description in the AsyncAPI specification updated to note this Assessment II use.
  • PowerInstant.measurement_value gains two optional fields: aggregation (instant default, or average) and aggregation_window (ISO-8601 duration, e.g. PT1S), with aggregation_window conditionally required when aggregation is average (enforced via JSON Schema if/then). This lets a power sample declare whether it is an instantaneous point reading or a windowed mean; FCR Assessment II uses average over PT1S. Additive and backward-compatible: omitting both fields keeps the prior instantaneous semantics, and prior-version messages remain accepted.

2.2.0 - 2026-05-28​

Alerts, acknowledgements, and commands strengthened.

  • schema_version is now required on AlertEvent and AlertState payloads. Previously the field was defined but not in the required list of either alert message. Tensor Cloud continues to accept alert payloads emitted under prior versions that omit schema_version; EMS implementations should add the field to alert payloads going forward.
  • CommandResponse.errors is now conditionally required by the schema: present (≥ 1 item) when status: "error", absent when status: "ok". Enforced via JSON Schema if/then/else. Previously the rule was prose-only. No producer-side change required for EMS implementations that already followed the prose rule.
  • TelemetryFeedback.code and TelemetryFeedback.detail are now conditionally required by the schema: both present when status: "error", both absent when status: "ok". Enforced via JSON Schema if/then/else. Affects the testing-only telemetry feedback channel; Tensor Cloud is the producer, EMS implementations only consume.
  • BatteryFcrCommand.control.schedule[*].capacity_kw is now conditionally required by the schema: required when control.action is execute (the default) and forbidden when control.action is cancel. Enforced via JSON Schema if/then/else.
  • BatteryPowerCommand.control.schedule and BatteryFcrCommand.control.schedule now declare minItems: 1. Empty schedules are rejected at the schema layer.
  • Embedded schema examples corrected: CommandResponse examples now include the required schema_version; FCR cancel examples use message_id values that match the documented ^msg_[0-9a-f]{8}-…$ pattern.
  • Top-level additionalProperties is now true on every message family (including BatteryPowerCommand and BatteryFcrCommand). Previously commands were strict and other families lenient - the asymmetry is removed so forward-compatibility is uniform across the protocol.

2.1.0 - Previous baseline​

Pre-changelog baseline. Includes the full set of telemetry, command, alert, and response channels documented in the integration guide and AsyncAPI spec.