v0.8.1

Frequenz Common API Release Notes

Summary

Features

• Add gridpool.Gridpool message type to v1alpha8, defining a gridpool as an assigned group of microgrids for the purpose of energy trading.

What's Changed

• Bump mkdocs-material from 9.6.15 to 9.6.16 in the patch group by @dependabot[bot] in #402
• Bump mkdocstrings[python] from 0.29.1 to 0.30.0 in the mkdocstrings group by @dependabot[bot] in #404
• Bump mypy from 1.16.1 to 1.17.1 in the minor group by @dependabot[bot] in #403
• Bump actions/download-artifact from 4 to 5 in the artifacts group by @dependabot[bot] in #406
• Bump actions/checkout from 4 to 5 by @dependabot[bot] in #407
• Bump setuptools-scm[toml] from 8.3.1 to 9.2.0 by @dependabot[bot] in #412
• Bump the patch group with 2 updates by @dependabot[bot] in #410
• Bump pydoclint from 0.6.6 to 0.6.11 by @dependabot[bot] in #411
• Bump actions/labeler from 5.0.0 to 6.0.1 by @dependabot[bot] in #413
• Use a monthly schedule for GitHub Actions updates by @llucax in #415
• Bump pydoclint from 0.6.11 to 0.7.3 by @dependabot[bot] in #420
• Bump the patch group with 3 updates by @dependabot[bot] in #418
• Bump the minor group with 2 updates by @dependabot[bot] in #419
• Bump isort from 6.0.1 to 6.1.0 in the minor group across 1 directory by @dependabot[bot] in #422
• feat(gridpool): add gridpool definition to v1alpha8 by @sandovalrr in #423

New Contributors

• @sandovalrr made their first contribution in #423

Full Changelog: v0.8.0...v0.8.1

v0.8.0

Frequenz Common API Release Notes

Summary

This release introduces the new v1alpha8 version of the API, which includes several breaking changes compared to v1alpha7. The changes focus on improving consistency and clarity by renaming several symbols and removing unused components.

Upgrading

• A new package frequenz.api.common.v1alpha8 has been introduced, containing the following breaking changes from v1alpha7.

• Removed:

  • electrical_components.Fuse
  • InverterType.INVERTER_TYPE_WIND_TURBINE

• Renamed several symbols to increase consistency and clarity:

  • microgrid:

    • MicrogridComponentIds to MicrogridElectricalComponentIds
    • MicrogridComponentIDs.component_ids to MicrogridElectricalComponentIds.electrical_component_ids

  • electrical_components:

    • ElectricalComponentConnections.source_component_id to ElectricalComponentConnections.source_electrical_component_id
    • ElectricalComponentConnections.destination_component_id to ElectricalComponentConnections.destination_electrical_component_id
    • ElectricalComponentStateSnapshot.component_id to ElectricalComponentStateSnapshot.electrical_component_id
    • Transformer-related terms are renamed to align them with power transformers, which are more commonly used in electrical engineering:
      • electrical_components.VoltageTransformer to electrical_components.PowerTransformer
      • ElectricalComponentCategorySpecificInfo.kind.voltage_transformer to ElectricalComponentCategorySpecificInfo.kind.power_transformer
      • ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_VOLTAGE_TRANSFORMER to ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_POWER_TRANSFORMER

  • type:

    • The whole package has been renamed to types to avoid using reserved keywords in programming languages.

What's Changed

• Bump the patch group with 2 updates by @dependabot in #383
• dependabot: Group grpc/protobuf updates together by @llucax in #385
• Bump the minor group across 1 directory with 2 updates by @dependabot in #386
• Bump frequenz-floss/gh-action-setup-python-with-deps from 1.0.0 to 1.0.1 in the compatible group by @dependabot in #388
• Bump frequenz-floss/gh-action-nox from 1.0.0 to 1.0.1 in the compatible group by @dependabot in #389
• Clear release notes and add v1alpha8 package by @tiyash-basu-frequenz in #396
• Remove electrical_components.Fuse from frequenz.api.common.v1alpha8 by @tiyash-basu-frequenz in #394
• Remove InverterType.INVERTER_TYPE_WIND_TURBINE by @tiyash-basu-frequenz in #397
• Rename leftover uses of component_id to electrical_component_id by @tiyash-basu-frequenz in #398
• Rename voltage-transformer to power-transformer by @tiyash-basu-frequenz in #399
• Rename type package to types in v1alpha8 proto files by @tiyash-basu-frequenz in #400
• Clean up and reformat the release notes for v1alpha8 by @tiyash-basu-frequenz in #401

Full Changelog: v0.7.0...v0.8.0

v0.7.0

Frequenz Common API Release Notes

Summary

This release introduces several breaking changes, new features, and improvements to the existing API. The most significant changes include renaming and restructuring of the components package to electrical_components, the introduction of new diagnostic codes, and the addition of new messages for communication components and streaming events.

Upgrading

• Removed:

  • microgrid.components.ComponentStatus.

  • ComponentErrorCode.UNDERVOLTAGE_SHUTDOWN, use ElectricalComponentDiagnosticCode.UNDERVOLTAGE instead

  • microgrid.sensors.SensorMetric, use metrics.Metric instead

  • microgrid.sensors.SensorMetricSample, use metrics.MetricSample instead

  • microgrid.sensors.SensorCategory, since it was not useful and potentially confusing

    Sensors can report different sensor metrics, and they could belong to several of these categories simultaneously. This defeats the purpose of having singular categories for sensors. Some more useful categorization may be introduced again in the future.

• Renamed several symbols to increase consistency and clarity:

  • microgrid.components:

    • The whole package and all proto files, messages, field, enums were renamed to electrical_components

    • ComponentCategoryMetadataVariant to ElectricalComponentCategorySpecificInfo

    • ComponentCategory to ElectricalComponentCategory

    • Component.category_type to ElectricalComponent.category_specific_info

    • ComponentCategoryMetadataVariant.metadata to ElectricalComponentCategorySpecificInfo.kind

    • ComponentErrorCode to ElectricalComponentDiagnosticCode

    • ComponentState to ElectricalComponentStateSnapshot

    • ComponentState.sampled_at to ElectricalComponentStateSnapshot.origin_time

    • ComponentData to ElectricalComponentTelemetry (to better specify its purpose of encapsulating general telemetry data from electrical components)

    • ComponentData.states to ElectricalComponentTelemetry.state_snapshots

    • Grid-related terms to clarify their meaning and purpose:

      • COMPONENT_CATEGORY_GRID to ELECTRICAL_COMPONENT_CATEGORY_GRID_CONNECTION_POINT
      • ComponentCategoryMetadataVariant.metadata.grid to ElectricalComponentCategorySpecificInfo.kind.grid_connection_point

    • InverterType.INVERTER_TYPE_SOLAR to InverterType.INVERTER_TYPE_PV (to align with the more colloquial term "PV inverter")

    • ComponentCategory.COMPONENT_CATEGORY_RELAY to ElectricalComponentCategory.ELECTRICAL_COMPONENT_CATEGORY_BREAKER (to better align with the common terminology used in electrical engineering).

    • All contents of all the files in the electrical_components directory (previously components) are now moved into the electrical_components.proto file.

  • microgrid.sensors:

    • SensorErrorCode to SensorDiagnosticCode
    • SensorData to SensorTelemetry (to better specify its purpose of encapsulating general telemetry data from sensors)
    • SensorState to SensorStateSnapshot
    • SensorData.states to SensorTelemetry.state_snapshots
    • SensorState.sampled_at to SensorStateSnapshot.origin_time
    • SensorStateCode.SENSOR_STATE_CODE_ON to SensorStateCode.SENSOR_STATE_CODE_OK (to better indicate that we do not control on/off state of sensors)

  • metrics:

    • The file metric_sample.proto to metrics.proto
    • MetricSample.source to MetricSample.connection
    • MetricSample.sampled_at to sample_time

  • metrics.Metric:

    • The enum variants to follow a more consistent naming scheme of core-concept to modifier.
    • METRIC_AC_APPARENT_POWER* to METRIC_AC_POWER_APPARENT*
    • METRIC_AC_ACTIVE_POWER* to METRIC_AC_POWER_ACTIVE*
    • METRIC_AC_REACTIVE_POWER* to METRIC_AC_POWER_REACTIVE*
    • METRIC_AC_APPARENT_ENERGY* to METRIC_AC_ENERGY_APPARENT*
    • METRIC_AC_ACTIVE_ENERGY* to METRIC_AC_ENERGY_ACTIVE*
    • METRIC_AC_REACTIVE_ENERGY* to METRIC_AC_ENERGY_REACTIVE*

  • types:

    • The whole package has been renamed to type.

• Renumbered some enum values to remove unnecessary gaps:

  • microgrid.components.ComponentCategory (microgrid.electrical_components.ElectricalComponentCategory)
  • microgrid.components.ComponentErrorCode (microgrid.electrical_components.ElectricalComponentDiagnosticCode)
  • metrics.Metric

• The minimum allowed version of protobuf and grpcio has been updated to 6.31.1 and 1.72.1 respectively, you might also need to bump your dependencies accordingly.

• The file location.proto has been moved to the types package, moving the message Location to types.Location.

• The type of the field metrics.MetricSample.connection has been changed from string to metrics.MetricConnection. The latter is a newly added message that provides a better categorization of the connection type.

• The v1 package has been renamed to v1alpha7. The current v1 package now consists of the contents the same directory from the v0.6.x branch, which is the latest stable version of the API.

• The enum ComponentCategory (now ElectricalComponentCategory) has been extended with new variants.

New Features

Added many new messages and enum values:

• microgrid.communication_components: Package with message definitions for communication components

  • CommunicationComponentDiagnostic: Message to represent warnings and errors in microgrid communication components
  • CommunicationComponentStateSnapshot: Message to represent the state of communication components

• microgrid.electrical_components (previously microgrid.components)

  • ElectricalComponentDiagnostic: Message to represent warnings and errors in microgrid electrical components
  • ElectricalComponentDiagnosticCode (previously ComponentErrorCode): New diagnostic codes to cover more cases, especially for inverters
  • InverterType.INVERTER_TYPE_WIND_TURBINE: Enum value to represent wind turbine inverters

• microgrid.ElectricalComponentCategory (previously microgrid.ComponentCategory) has been extended with new enum values:

  • ELECTRICAL_COMPONENT_CATEGORY_PLC
  • ELECTRICAL_COMPONENT_CATEGORY_STATIC_TRANSFER_SWITCH
  • ELECTRICAL_COMPONENT_CATEGORY_UNINTERRUPTIBLE_POWER_SUPPLY
  • ELECTRICAL_COMPONENT_CATEGORY_CAPACITOR_BANK
  • ELECTRICAL_COMPONENT_CATEGORY_WIND_TURBINE

• microgrid.sensors

  • Message linking microgrid and sensor IDs
  • SensorDiagnostic: Message to represent warnings and errors in microgrid sensors
  • Added warnings to sensor SensorState

• streaming: Package with message definitions for streaming events

  • Event: Enum to represent different types of streaming events (Created, Deleted, Updated)

• types

  • Interval: Message to standardize time interval filtering across APIs

    This uses start_time (inclusive) and end_time (exclusive) fields, aligning with ISO 8601 and common programming conventions.

What's Changed

• Reset Release Notes after release v0.6.3 by @camille-bouvy-frequenz in #269
• Bump the required group with 5 updates by @dependabot in #271
• Bump setuptools-scm[toml] from 7.1.0 to 8.1.0 by @dependabot in #276
• Bump the required group across 1 directory with 9 updates by @dependabot in #277
• Bump setuptools from 68.1.0 to 75.6.0 by @dependabot in #275
• Bump the required group with 5 updates by @dependabot in #278
• Bump black from 24.10.0 to 25.1.0 by @dependabot in #282
• Add message linking microgrid and sensor IDs by @stefan-brus-frequenz in #283
• Bump the required group with 7 updates by @dependabot in #280
• Bump isort from 5.13.2 to 6.0.0 by @dependabot in #281
• Bump nox from 2024.10.9 to 2025.2.9 by @dependabot in #289
• Rename microgrid.components -> microgrid.electrical_components by @tar-viturawong-frequenz in #291
• Add protobuf definition for communication components by @tar-viturawong-frequenz in #292
• Update repo-conf by @Marenz in #295
• Bump pydoclint from 0.6.0 to 0.6.5 by @dependabot in #301
• Bump mkdocstrings[python] from 0.28.3 to 0.29.1 in the mkdocstrings group by @dependabot in #300
• Bump the minor group with 3 updates by @dependabot in #298
• Bump actions/checkout from 3 to 4 by @dependabot in #296
• Fix: Forgot to update repo-conf dependency to 0.13.1 by @Marenz in #304
• Bump the patch group across 1 directory with 7 updates by @dependabot in #305
• Bump setuptools from 75.8.0 to 78.1.0 by @dependabot in https://gi...

v0.6.5

Frequenz Common API Release Notes

New Features

• Added message linking microgrid and sensor IDs.

• Update of the PaginationParams struct.

Upgrading

• PaginationParams has been changed so that the page_size and page_token
  fields are now mutually exclusive.

• A new component category COMPONENT_CATEGORY_HVAC has been added to the API
  to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.

• Additional information for energy metric

• Generalize Energy message documentation for broader market use

• Add Power message to represent Power in MW

Bug Fixes

• Fix a dependency issue by pinning the grpcio version and related libraries.
• Fixed a wrong documentation comment for COMPONENT_CATEGORY_UNSPECIFIED.

What's Changed

• Bump the required group with 3 updates by @dependabot in #227
• Be a bit more explicit about when some fields can be missing by @llucax in #228
• Bump brettcannon/check-for-changed-files from 1.2.0 to 1.2.1 by @dependabot in #229
• Bump the required group with 6 updates by @dependabot in #230
• Add energy metric information by @flora-hofmann-frequenz in #235
• Change PaginationParams to make page_size and page_token mutually exclusive by @Marenz in #232
• Merge v0.6.2 into v0.x.x by @llucax in #243
• Bump the required group across 1 directory with 10 updates by @dependabot in #247
• Bump the protobuf and grpcio versions by @llucax in #251
• Fix documentation comment for COMPONENT_CATEGORY_UNSPECIFIED by @llucax in #245
• Bump yoheimuta/action-protolint from 1.1.0 to 1.3.0 by @dependabot in #196
• Move conftest.py to the python package root by @llucax in #252
• Improve the Lifetime message documentation by @llucax in #259
• Bump the required group with 3 updates by @dependabot in #265
• Add Power message and make Energy message broader by @camille-bouvy-frequenz in #267
• Build source packages with PEP 625 compliant filenames by @llucax in #285
• Merge v0.6.3 into v0.6.x by @tiyash-basu-frequenz in #286

New Contributors

• @flora-hofmann-frequenz made their first contribution in #235

Full Changelog: v0.6.4...v0.6.5

v0.6.4

This is an erroneous release. It is out of sync with the v0.6.x branch. Please use v0.6.5 instead.

v0.6.3

Frequenz Common API Release Notes

Update of the PaginationParams struct.

Upgrading

• PaginationParams has been changed so that the page_size and page_token
  fields are now mutually exclusive.

• A new component category COMPONENT_CATEGORY_HVAC has been added to the API
  to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.

• Additional information for energy metric

• Generalize Energy message documentation for broader market use

• Add Power message to represent Power in MW

Bug Fixes

• Fix a dependency issue by pinning the grpcio version and related libraries.
• Fixed a wrong documentation comment for COMPONENT_CATEGORY_UNSPECIFIED.

What's Changed

• Bump the required group with 3 updates by @dependabot in #227
• Be a bit more explicit about when some fields can be missing by @llucax in #228
• Bump brettcannon/check-for-changed-files from 1.2.0 to 1.2.1 by @dependabot in #229
• Bump the required group with 6 updates by @dependabot in #230
• Add energy metric information by @flora-hofmann-frequenz in #235
• Change PaginationParams to make page_size and page_token mutually exclusive by @Marenz in #232
• Merge v0.6.2 into v0.x.x by @llucax in #243
• Bump the required group across 1 directory with 10 updates by @dependabot in #247
• Bump the protobuf and grpcio versions by @llucax in #251
• Fix documentation comment for COMPONENT_CATEGORY_UNSPECIFIED by @llucax in #245
• Bump yoheimuta/action-protolint from 1.1.0 to 1.3.0 by @dependabot in #196
• Move conftest.py to the python package root by @llucax in #252
• Improve the Lifetime message documentation by @llucax in #259
• Bump the required group with 3 updates by @dependabot in #265
• Add Power message and make Energy message broader by @camille-bouvy-frequenz in #267

New Contributors

• @flora-hofmann-frequenz made their first contribution in #235

Full Changelog: v0.6.2...v0.6.3

v0.6.2

Frequenz Common API Release Notes

Bug Fixes

• Fix a dependency issue by pinning the grpcio version and related libraries.

What's Changed

• Pin grpc related dependencies by @llucax in #241

Full Changelog: v0.6.1...v0.6.2

v0.6.1

Frequenz Common API Release Notes

Summary

This release adds a new component category COMPONENT_CATEGORY_HVAC to the API.

New Features

• A new component category COMPONENT_CATEGORY_HVAC has been added to the API
  to represent HVAC (Heating, Ventilation, and Air Conditioning) systems.

What's Changed

• Update protobuf requirement from <5,>=4.25.3 to >=4.25.3,<6 by @dependabot in #205
• Bump the optional group with 2 updates by @dependabot in #211
• Bump the optional group with 1 update by @dependabot in #214
• Bump the optional group with 2 updates by @dependabot in #216
• Bump black from 24.3.0 to 24.4.0 in the required group by @dependabot in #219
• Bump the required group with 2 updates by @dependabot in #220
• Bump the required group with 5 updates by @dependabot in #222
• Make Dependabot check for updates monthly on Thursdays by @llucax in #223
• Bump the required group with 4 updates by @dependabot in #224
• Add new component category HVAC by @tiyash-basu-frequenz in #225
• Clean up release notes to prepare for release v0.6.1 by @tiyash-basu-frequenz in #226

Full Changelog: v0.6.0...v0.6.1

v0.6.0

Frequenz Common API Release Notes

Summary

• Removed dependency on googleapis-common-protos in favor of internal frequenz.api.common.v1.types.Decimal, advising updates to dependencies for users previously relying on Google's types.
• Renamed voltage and current metrics for clarity and introduced new metrics, including line-to-line voltages and Total Harmonic Distortion (THD) metrics, with updated naming conventions for simplicity and precision.

Upgrading

• The dependency on googleapis-common-protos / googleapis/googleapis was removed, now the built-in frequenz.api.common.v1.types.Decimal is used internally instead. This is compatible with Google's type, but if you depended indirectly on Google's submodule or python packages, you may need to update your dependencies.

  Nevertheless it is strongly recommended to remove the dependency on Google repos and use the built-in frequenz.api.common.v1.types.Decimal instead if your project only uses the Decimal type from it too.

• Voltage metrics have been renamed from METRIC_VOLTAGE_PHASE_[1|2|3] to METRIC_VOLTAGE_PHASE_[1|2|3]_N.

• The variants in the enum Metric have been renumberd due to the addition of line-to-line voltages.

• Current metrics have been renamed:
  METRIC_AC_APPARENT_CURRENT -> METRIC_AC_CURRENT
METRIC_AC_APPARENT_CURRENT_PHASE_[1|2|3] -> METRIC_AC_CURRENT_PHASE_[1|2|3]

• Metrics for Total Harmonic Distortion have been un-abbreviated:
  METRIC_AC_THD_CURRENT -> METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT
METRIC_AC_THD_CURRENT_PHASE_[1|2|3] -> METRIC_AC_TOTAL_HARMONIC_DISTORTION_CURRENT_PHASE_[1|2|3]

• Renamed SimpleMetricSample to SimpleMetricValue, because it does not contain a timestamp, so it does not represent a sample but a value.

• Renamed AggregatedMetricSample to AggregatedMetricValue, because it does not contain a timestamp, so it does not represent a sample but a value.

• Renamed MetricSampleVariant to MetricValueVariant.

• Rename MetricSample.sample to MetricSample.value.

• Rename SensorMetricSample.sample to SensorMetricSample.value.

New Features

• Added a Frequenz.api.common.v1.types.Decimal type, compatible with google.type.Decimal.

• The following new metrics have been added:

  • METRIC_VOLTAGE_PHASE_1_PHASE_2
  • METRIC_VOLTAGE_PHASE_2_PHASE_3
  • METRIC_VOLTAGE_PHASE_3_PHASE_1

What's Changed

• Clear release notes by @tiyash-basu-frequenz in #192
• Remove dependency on googleapis by @llucax in #187
• Bump the optional group with 3 updates by @dependabot in #194
• Bump actions/labeler from 4.3.0 to 5.0.0 by @dependabot in #145
• Update to repo-conf 0.9.0 by @Marenz in #195
• Bump the optional group with 4 updates by @dependabot in #199
• Bump pytest from 7.4.4 to 8.1.0 by @dependabot in #202
• Bump nox from 2023.4.22 to 2024.3.2 by @dependabot in #201
• Bump the optional group with 2 updates by @dependabot in #200
• Bump the optional group with 3 updates by @dependabot in #203
• Add line-to-line voltage metrics by @tiyash-basu-frequenz in #206
• Remove APPARENT_ from current metric names by @tiyash-basu-frequenz in #208
• Unabbreviate THD in the Metric enum by @tiyash-basu-frequenz in #209
• Rename [Simple|Aggregated]MetricSample to [Simple|Aggregated]MetricValue by @tiyash-basu-frequenz in #210
• Cleanup release notes for release v0.6.0 by @tiyash-basu-frequenz in #212

New Contributors

• @Marenz made their first contribution in #195

Full Changelog: v0.5.5...v0.6.0

v0.5.5

Frequenz Common API Release Notes

Summary

This release contains minor updates to the API, including new metric variants,
and a new field in MetricSample to identify the source of the metric.

New Features

• Added a field named source to MetricSample to allow the user to identify
  the source of the metric, in case different sensors in component report
  metrics with the same Metric variant.

• Added 3 new metric variants for inverter temperatures:

  • METRIC_INVERTER_TEMPERATURE_CABINET
  • METRIC_INVERTER_TEMPERATURE_HEATSINK
  • METRIC_INVERTER_TEMPERATURE_TRANSFORMER

What's Changed

• Clear release notes by @llucax in #180
• Bump submodules/api-common-protos from 86f7539 to 738ff24 by @dependabot in #182
• Add field source to MetricSample by @tiyash-basu-frequenz in #181
• Add metrics variants for inverter temperatures by @tiyash-basu-frequenz in #188
• Update release notes for v0.5.5 release by @tiyash-basu-frequenz in #191

Full Changelog: v0.5.4...v0.5.5