Skip to main content

Integrator guide changelog

This page tracks what changed in the integrator guide and the integrator checklist, so you can tell at a glance whether anything you built against has moved since you last read it.

It records content changes: new requirements, changed thresholds and cadences, clarified behaviour, and corrections. Restructuring, renamed headings, link fixes, and wording polish are not listed, because they do not change what an EMS has to do.

Entries are dated by the day the change was published to this site. Where a change also moved the protocol version, the version is named and links to the corresponding protocol version changelog entry, which carries the schema-level detail.

2026-08-18b​

No protocol change.

  • Scheduling and submission. New sections at the end of the FCR pre-qualification page: how the test day is arranged with the area TSO, the obligations on the day, and what is submitted afterwards on Form 19-1 to 19-4.
  • Offered capacity is the bid cap. New section stating that the confirmed value becomes the upper bidding limit: the largest output change within 30 seconds on a 0.2 Hz drop, 0.3 Hz in Hokkaido.
  • Duration is not assessed. Now stated explicitly.
  • Droop ceiling has an exception. The 5 % ceiling now notes that the area TSO may permit otherwise where equipment characteristics justify it.
  • Base frequency section reworked. The deadband ceilings are now given directly, ±0.01 Hz at 50 Hz and ±0.012 Hz at 60 Hz, rather than derived. The 50 Hz staircase remains a scaled proposal pending area TSO confirmation, and the Hokkaido 0.3 Hz threshold is cited as proof that test a thresholds are not frequency-scaled.
  • Workbook. The instruction sheet now says to start recording at least one hour before the assessment window. The English workbook's prose no longer carries untranslated Japanese terms.

2026-08-18​

No protocol change.

  • New page: FCR pre-qualification. What the 事前審査 test actually consists of: the two standardized tests, the frequency patterns for test a and test b, the criteria applied to the response, the requirements verified (deadband, droop, response time, measurement interval, delay time), and how the 50 Hz and 60 Hz cases differ. Includes downloadable mock frequency workbooks for the engineer operating the transducer. The guide's own pre-qualification section is unchanged in substance and now links to it.
  • Pre-qualification testing. Now states explicitly that the section covers only what the EMS publishes during a test, and points to the new page for the test procedure itself.

2026-08-17​

Published with protocol 2.8.0, which adds batched telemetry. That entry carries the payload contract; below is what moved in this guide.

  • New section: Batched telemetry. The two batch topics, a worked payload, the rules for forming a batch, and a live-versus-backfill table. Batching is granted per site and is backfill-only by default, so confirm the mode with your technical contact before switching.
  • Quality of service. The QoS 0-or-1 latitude no longer applies everywhere: batch topics require QoS 1 and must not set RETAIN. Now also states that PUBACK is broker receipt, not ingestion.
  • Broker rate limits. Added the per-connection publish rate (100/second, excess discarded rather than queued), throughput cap (512 KB/second) and 256-byte topic-name limit, a backfill pacing target of 50 publishes/second and 256 KB/second, and a note that AWS meters in 5 KB increments counting the topic name.
  • Error codes. The DUPLICATE entry no longer reads "message with same id sent twice".
  • FCR Assessment II reporting. Now distinguishes its 1 Hz measurement requirement from arrival latency.

2026-08-13​

Published with protocol 2.7.0.

  • Command validation is all-or-nothing. New section. If any item in control.schedule fails validation, the EMS applies none of the items in that command, including the valid ones, and continues executing the previously valid schedule. This covers power setpoint and FCR commands, and FCR action: "cancel" as well as action: "execute". errors[] must carry one entry per invalid item rather than stopping at the first. This was previously undefined; an EMS that applied the valid part of a mixed command now needs to change.
  • New GRID_OTHER alert code for AC-side grid faults that no existing code covers: loss of the grid connection, a protection relay or grid-interconnection breaker trip, an out-of-tolerance voltage or frequency condition at the connection point, or a site-wide outage the EMS can still report. These previously had to be reported as UNKNOWN_FAULT.
  • One fault may raise several alert codes. New section. On a DC-linked system, a fault in hardware shared by the PV array and the battery is reported as both PV_OTHER and BATT_OTHER. Where the EMS reaches both subsystems through a single collector device and has no per-BMS or per-PVPCS visibility, raising BATT_COMM_FAIL and PV_COMM_FAIL simultaneously on loss of communication with that collector is acceptable.
  • alertState is published even when nothing is firing. With no active alerts, publish the snapshot with an empty measurement_value array on the normal schedule rather than suppressing it. Without the empty snapshot, a healthy site is indistinguishable from an EMS that has stopped reporting.
  • Setpoints now say where they apply. New section, and the change most likely to need code. Each BatteryPowerCommand interval carries reference_point: "battery" (the value refers to the battery, generation flows through untouched) or "grid" (the value refers to the metering point, and the battery absorbs whatever is generated). Omitting it means "battery", so nothing you have already built changes meaning, and power_kw = 0 still means the battery stands by. What changes is that the point is now stated rather than inferred: an EMS must read the field instead of deciding from its own topology, and DC-coupled systems honour "battery" by compensating their inverter setpoint against measured PV. You will not receive "grid" until your EMS reports schema_version 2.7.0.
  • Unreachable setpoints have defined behaviour for the first time. New schedule interpretation rule 9 and a new SETPOINT_UNREACHABLE alert code. If you cannot deliver a commanded value — an inverter limit on a "battery" interval, a state-of-energy limit on a "grid" one — clamp to the closest achievable value, keep running, and raise the alert. Do not reject the command and do not stop the battery. Previously the spec said nothing about this case at all.
  • Command validation rules gained three entries that AR-15 and FC-10 depend on and that the list did not previously carry: inverted or empty intervals (start_ts >= end_ts), out-of-range power_kw / capacity_kw, and capacity_kw on the wrong FCR action. These were already reachable through the error codes reference; they are now in the normative must-reject list.
  • Curtailment is required for every topology, including stand-alone. The metric table row is unchanged at 🔴 Required, but the schema previously called the message optional, so integrators reading the spec rather than the guide may have treated it as opt-in. It is required. The stand-alone section now says so explicitly: a battery with no co-located solar can still sit behind TSO output control. Irradiation remains not required for stand-alone.
  • Mocked-broker testing now names the mixed valid/invalid schedule among the error paths to cover.
  • New integrator checklist items A-5, A-6, AR-15, AR-16, AR-17, FC-10.
  • Wire schema_version moved to 2.7.0.
  • This page was added.

2026-08-12​

  • Before commands can reach you. New section. Commands are published only for a battery that exists as an asset in a Tensor Cloud workspace and is associated with your EMS gateway. Until Tensor Energy has registered that asset and created the association, your command subscription is connected but silent, and every checklist item that depends on receiving a command is blocked. Telemetry is unaffected and starts flowing as soon as the certificate connects.
  • Testing error paths with a mocked broker. New section. Tensor Cloud only ever emits valid commands and your gateway certificate cannot publish on cmd/..., so the error paths of your command handling cannot be exercised against the test server at all. The section recommends covering them with unit and integration tests against a mocked MQTT broker, injecting at the MQTT boundary, and lists the cases to cover. The integrator checklist now marks which items this applies to in a Verification column.

2026-07-28​

Published with protocol 2.6.1.

  • measurement_ts on windowed measurements. New section. On any measurement covering a period of time, measurement_ts always carries the start of that period, never its end or midpoint: it equals measurement_value.start_ts on windowed energy, and the start of aggregation_window on power and grid frequency sent with aggregation: "average". Point-in-time telemetry is unchanged.
  • Curtailment measurement_ts is the schedule's TSO-issued creation time when the TSO data carries it, otherwise the time the EMS received the schedule. The periods the schedule covers remain in measurement_value[].start_ts and end_ts.
  • Added a sequence diagram of the alert message flow.

2026-07-14​

Published with protocol 2.6.0.

  • Solar DC voltage and current for DC-linked systems. New requirement. DC-link PV plus battery sites publish the PV array's DC voltage (V) and current (A) on dt/{siteId}/{gatewayId}/solar, measured at the DC link upstream of the inverter as a single value aggregated across the whole array, sampled at the same instant and sent as one matched pair at 1-minute resolution. AC-linked and stand-alone sites do not send this channel.
  • Missing-data guidance extended: if either half of the voltage/current pair cannot be read at a timestamp, skip the publish for that timestamp rather than sending one value alone.
  • Wire schema_version moved to 2.6.0.

2026-07-10​

Published with protocol 2.5.0.

  • Telemetry that cannot be parsed is now acknowledged. The feedback carries correlation_id: "unknown", code: "MESSAGE_MALFORMED", and a topic field naming the channel it arrived on. Do not assume correlation_id always matches the msg_ UUID pattern.
  • The error-surfaces reference now documents detail, field_path, and topic on TelemetryFeedback, and states that topic is the only identifier available when correlation_id is the sentinel.
  • Wire schema_version moved to 2.5.0.

2026-07-07​

Two changes published the same day.

  • FCR is dispatched in 30-minute slots, not 3-hour blocks. Corrected in the FCR offer schedule and Assessment II sections.
  • Power sign convention stated explicitly: positive = charging, negative = discharging, 0 = standby. The command topic does not encode direction, so the sign of power_kw is authoritative.
  • A higher priority number wins. The direction was previously left to inference.
  • The acknowledgement must be sent immediately after receiving and parsing a command; this was previously "should". The curtailment merge of TSO fixed and update schedules likewise became "must".
  • res_topic is authoritative for where the response goes; the AsyncAPI channel address ack-cmd/{siteId} is illustrative. Application-level acknowledgements are required regardless of the MQTT QoS in use.
  • Message envelope essentials. New section covering the message_id format and its reuse on resend, schema_version, the +09:00 timezone convention, the {window} token enum (PT1M, PT5M, PT10M, PT15M, PT30M, PT1H), and forward compatibility with unknown fields.
  • Broker rate limits. New section with the AWS IoT Core quotas an EMS actually meets: 100 in-flight publishes per connection, 128 KB payload, per-account publish rate, 8 subscriptions per SUBSCRIBE, one CONNECT per second per client ID.
  • Telemetry that is required only under a stated condition is now marked 🟡 Conditional rather than ⚪️ Optional, with a legend. The affected metrics are grid_to_load_ac, load_demand_ac, grid_to_battery_ac, inverter_net_output_ac, inverter_to_load_ac, and grid_to_inverter_ac.
  • Added a terminology table, and the list of telemetry topics that use a fixed tail instead of the {metric}/{type} pattern.
  • Malformed command acknowledgement. When a command cannot be parsed at all (MESSAGE_MALFORMED), its message_id cannot be recovered, so set the response's command_id to the sentinel string "unknown". If the message_id is partially recoverable, echo the recovered value. The response's own message_id is always freshly generated.

2026-07-06​

Published with protocol 2.4.0.

  • Grid frequency telemetry. New requirement for FCR-awarded resources: publish grid frequency at 1 Hz on dt/{siteId}/{gatewayId}/frequency for the full duration of every FCR-awarded slot, measured at the grid connection point from the live AC waveform, reported to at least 0.0001 Hz, as the mean over each 1-second window and time-aligned with the 1 Hz power samples.
  • Pre-qualification (事前審査) flag. New section. While the EMS operator has the site in pre-qualification test mode, set pre_qualification: true on every instantaneous-power and grid-frequency message. Tensor Cloud uses it to exclude the window from optimization and from Assessment II submissions.
  • Wire schema_version moved to 2.4.0.

2026-06-30​

  • Alert thresholds defined. BATT_SOC_LOW is state of charge below 3%; BATT_SOH_DEGRADED is state of health below 80%. Both were previously described only as "below the minimum threshold" and "degraded compared to expected performance". The BATT_OVERTEMP threshold is noted as usually defined by the battery OEM.
  • INTERNAL_ERROR and ACK timing (protocol 2.3.1). The acknowledgement reflects validation and acceptance at receipt time, not the execution outcome, and cannot report a failure that surfaces only later at execution. INTERNAL_ERROR also covers a well-formed command that fails during receipt-time handling and cannot be committed before the ACK is sent.

2026-06-20​

  • State telemetry. Added as a fourth telemetry data type alongside instantaneous power, windowed energy, and lifetime energy: dt/{siteId}/{gatewayId}/{metric}/state, required for battery State of Energy (battery_soe).
  • Curtailment became a required metric, carrying limit_percent per interval. FCR cancellation requires capacity_kw to be omitted.
  • Dynamic updates for aggregated (VPP) resources. The EMS may receive an updated FCR capacity or power baseline for a slot that has already started and must apply it immediately, the same as any other in-progress interval.

2026-06-19​

  • Corrected the order of operations for FCR Assessment II. Tensor Cloud derives the net measured power, converts it to the sending-end basis including network-loss correction, then subtracts the registered baseline to obtain the supplied power. The earlier text applied the baseline before the sending-end conversion.

2026-06-16​

Published with protocol 2.3.0.

  • FCR Assessment II reporting. New section. Resources registered as offline-monitored publish 1-second-resolution power for FCR-awarded slots, on the metric set that matches the resource's TSO registration (grid-connection-point or equipment-point). Covers which slots the TSO selects and when, 60-day local retention for that data (longer than the 7 days for general telemetry), and buffering and resend after a connection loss.

2026-05-28​

  • Missing data policy. New section. If the EMS cannot read a numeric value at a given timestamp, skip the publish for that metric at that timestamp. value: null fails schema validation and value: 0 is indistinguishable from a genuine zero reading. If the underlying resource fails for an extended period, raise an alert.
  • Curtailment scope. A single publish may cover any time horizon and any number of intervals, bounded only by the 128 KB MQTT payload limit. Where the TSO provides separate fixed and update schedules, the EMS resolves them into a single effective schedule and publishes that.

2026-01-22​

Published with protocol 2.1.0.

  • Irradiation telemetry. Required for co-located storage (AC-link and DC-link), published to dt/{siteId}/{gatewayId}/irradiation in kW/m2. Not required for stand-alone batteries.

2026-01-14​

  • FCR baseline. New section. When the battery is operated in FCR mode, the regular power command determines the baseline that the FCR response is delivered around.

2025-11-03​

  • Site ID and gateway ID. New section covering what each identifier addresses, and the hot-standby and cold-standby gateway configurations, including that each physical gateway needs its own certificate and that one certificate supports only one concurrent connection.
  • Battery capacity metrics. New section. battery_soe must be calculated against battery_energy_remaining (effective capacity), never nominal capacity, and battery_energy_remaining itself is updated as capacity degrades.
  • Added the command lifecycle sequence diagram.

2025-10-31​

  • issue_ts on command messages. Commands carry the time Tensor Cloud issued them, used to break ties between schedules of equal priority covering the same period.

2025-09-17​

  • Command response topics updated to the ack-cmd/{siteId} namespace.