v0.9.0

Frequenz Microgrid API Client Release Notes

Summary

This is a small release to allow for easier interoperability between different APIs.

Upgrading

• Some minimum dependency versions are bumped, so you might need to update your dependencies as well.

• The IDs (MicrogridId, ComponentId, SensorId) are now imported from frequenz-client-common. Please add it to your dependencies if you haven't already, then you can replace your imports:

  • from frequenz.client.microgrid import MicrogridId -> from frequenz.client.common.microgrid import MicrogridId
  • from frequenz.client.microgrid import ComponentId -> from frequenz.client.common.microgrid.components import ComponentId
  • from frequenz.client.microgrid import SensorId -> from frequenz.client.common.microgrid.sensors import SensorId

What's Changed

• Clear release notes by @llucax in #150
• Allow base-client to be updated to 0.11.0 by @Marenz in #151
• Bump types-protobuf from 5.29.1.20250403 to 6.30.2.20250516 by @dependabot in #154
• Bump the patch group with 6 updates by @dependabot in #152
• Bump the minor group with 2 updates by @dependabot in #153
• Use IDs from frequenz-client-common by @llucax in #156

Full Changelog: v0.8.0...v0.9.0

v0.8.0

Frequenz Microgrid API Client Release Notes

Summary

This release introduces sensors support and adds official support for Python 3.12. It also includes some bug fixes.

Upgrading

• Some minimum versions of dependencies have been bumped to support Python 3.12. You might also need to bump these dependencies in your project.
• The ID classes (MicrogridId, ComponentId, etc.) were moved to the frequenz.client.microgrid.id module. They will be moved again, to frequenz-client-common in a near future.

New Features

• The MicrogridApiClient can now list sensor retrieving their metadata (list_sensors()) and can stream sensor data (stream_sensor_data()).

Bug Fixes

• When retrieving the microgrid metadata using metadata(), if the location was empty in the protobuf message, a wrong location with long=0, lat=0 was used. Now the location will be properly set to None in that case.
• The client now does some missing cleanup (stopping background tasks) when disconnecting (and when used as a context manager).

What's Changed

• Exclude repo-config from dependabot grouping by @llucax in #125
• Update protobuf requirement from <6,>=4.21.6 to >=4.21.6,<7 by @dependabot in #129
• Bump setuptools from 75.8.2 to 78.1.0 by @dependabot in #130
• Bump the required group with 6 updates by @dependabot in #126
• Bump types-protobuf from 5.29.1.20250208 to 5.29.1.20250315 by @dependabot in #128
• Bump types-markdown from 3.7.0.20241204 to 3.7.0.20250322 by @dependabot in #127
• Clear release notes by @llucax in #124
• Update to repo-config v0.13 by @llucax in #132
• Bump the patch group with 2 updates by @dependabot in #133
• Bump pydoclint from 0.6.2 to 0.6.4 by @dependabot in #135
• Bump flake8 from 7.1.2 to 7.2.0 in the minor group by @dependabot in #134
• Bump grpc-stubs from 1.53.0.5 to 1.53.0.6 by @dependabot in #142
• Bump types-protobuf from 5.29.1.20250315 to 5.29.1.20250403 by @dependabot in #141
• Bump pydoclint from 0.6.4 to 0.6.6 by @dependabot in #139
• Bump setuptools from 78.1.0 to 80.1.0 by @dependabot in #140
• Bump the patch group with 4 updates by @dependabot in #137
• Bump the minor group across 1 directory with 5 updates by @dependabot in #143
• Fix cleanup and missing location metadata by @llucax in #145
• Add sensors listing and data streaming by @llucax in #146
• Fix sensor data streaming without metrics filter by @llucax in #148
• Prepare release notes for release v0.8.0 by @llucax in #149

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

v0.7.0

Frequenz Microgrid API Client Release Notes

Upgrading

• Now component and microgrid IDs are wrapped in new classes: ComponentId and MicrogridId respectively.

  These classes provide type safety and prevent accidental errors by:

  • Making it impossible to mix up microgrid and component IDs (equality comparisons between different ID types always return false).
  • Preventing accidental math operations on IDs.
  • Providing clear string representations for debugging (MID42, CID42).
  • Ensuring proper hash behavior in collections.

  To migrate you just need to wrap your int IDs with the appropriate class: 0 -> ComponentId(0) / MicrogridId(0).

What's Changed

• Clear release notes by @shsms in #117
• Bump nox from 2024.10.9 to 2025.2.9 by @dependabot in #119
• Bump types-protobuf from 5.29.1.20241207 to 5.29.1.20250208 by @dependabot in #120
• Bump the required group across 1 directory with 12 updates by @dependabot in #121
• Add ID wrapper classes by @llucax in #122
• Prepare for release v0.7.0 by @llucax in #123

Full Changelog: v0.6.1...v0.7.0

v0.6.1

Frequenz Microgrid API Client Release Notes

Upgrading

• Widen frequenz-client-base dependency to allow v0.9.0.

What's Changed

• Clear release notes by @llucax in #102
• Bump setuptools-scm[toml] from 7.1.0 to 8.1.0 by @dependabot in #105
• Bump setuptools from 68.1.0 to 75.6.0 by @dependabot in #104
• Bump the required group across 1 directory with 6 updates by @dependabot in #106
• Bump types-markdown from 3.7.0.20240822 to 3.7.0.20241204 by @dependabot in #108
• Bump the required group across 1 directory with 7 updates by @dependabot in #109
• Bump black from 24.10.0 to 25.1.0 by @dependabot in #111
• Bump the required group across 1 directory with 7 updates by @dependabot in #114
• Revert "Enable autorefs plugin option to resolve closest references" by @llucax in #115
• Bump isort from 5.13.2 to 6.0.0 by @dependabot in #112
• Widen frequenz-client-base dependency to allow v0.9.0 by @shsms in #116

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

v0.6.0

Frequenz Microgrid API Client Release Notes

Upgrading

• ApiClient:

  • The class was renamed to MicrogridApiClient.
  • The api attribute was renamed to stub.
  • The constructor parameter channel_options was renamed to channels_defaults to match the name used in BaseApiClient.
  • The constructor now accepts a connect parameter, which is True by default. If set to False, the client will not connect to the server upon instantiation. You can connect later by calling the connect() method.

• The frequenz-client-base dependency was bumped to v0.8.0.

New Features

• The client now inherits from frequenz.client.base.BaseApiClient, so it provides a few new features, like disconnect()ing or using it as a context manager. Please refer to the BaseApiClient documentation for more information on these features.
• The client now supports setting reactive power for components through the new set_reactive_power method.

What's Changed

• Clear release notes by @llucax in #87
• Inherit from BaseApiClient by @llucax in #88
• Use call_stub_method() to call stub methods by @llucax in #89
• Remove duplicated show_symbol_type_toc key in mkdocs.yml by @llucax in #90
• Bump mkdocstrings dependencies by @llucax in #91
• Bump the required group with 5 updates by @dependabot in #92
• Bump the required group with 7 updates by @dependabot in #95
• Bump types-protobuf from 4.21.0.7 to 5.28.3.20241030 by @dependabot in #97
• Add the set_reactive_power method by @shsms in #99
• Update the client-base dependency to v0.8.0 by @llucax in #100
• Prepare for the v0.6.0 release by @llucax in #101

Full Changelog: v0.5.1...v0.6.0

v0.5.2

Frequenz Microgrid API Client Release Notes

New Features

• The client now supports setting reactive power for components through the new set_reactive_power method.

What's Changed

• Add the set_reactive_power method by @shsms in #99

Full Changelog: v0.5.1...v0.5.2

v0.5.1

Frequenz Microgrid API Client Release Notes

Bug Fixes

• Fix a bug where SSL was enabled by default. It is now disabled by default as in previous versions.

What's Changed

• Clear release notes by @llucax in #83
• Disable SSL by default by @llucax in #85
• Bump the required group across 1 directory with 4 updates by @dependabot in #86

Full Changelog: v0.5.0...v0.5.1

v0.5.0

Frequenz Microgrid API Client Release Notes

Upgrading

• This release stops using betterproto and grpclib as backend for gRPC and goes back to using Google's grpcio and protobuf.

  If your code was using betterproto and grpclib, it now needs to be ported to use grpcio and protobuf too. Remember to also remove any betterproto and grpclib dependencies from your project.

• We are now using base-client v0.6.0.

What's Changed

• Clear release notes by @llucax in #56
• Bump the required group with 14 updates by @dependabot in #57
• Bump docker/build-push-action from 5 to 6 by @dependabot in #58
• Bump brettcannon/check-for-changed-files from 1.2.0 to 1.2.1 by @dependabot in #59
• Configure dependabot to have separate minor updates for in-devel deps by @llucax in #61
• Bump mike from 2.1.1 to 2.1.2 by @dependabot in #65
• Bump pytest from 8.2.1 to 8.2.2 by @dependabot in #67
• Bump pydoclint from 0.4.1 to 0.5.3 by @dependabot in #63
• Fix patterns in dependabot.yml by @llucax in #70
• Bump the required group with 4 updates by @dependabot in #72
• Group GitHub action dependabot updates by @llucax in #71
• Bump the required group across 1 directory with 15 updates by @dependabot in #78
• Drop betterproto/grpclib (and upgrade client-base) by @llucax in #80
• Disable pylints no-name-in-module check by @llucax in #81
• Prepare readme for release by @Marenz in #82

New Contributors

• @Marenz made their first contribution in #82

Full Changelog: v0.4.0...v0.5.0

v0.4.0

Frequenz Microgrid API Client Release Notes

Summary

This release migrates to use betterproto and grpclib instead of grpcio and protobuf internally. It also stops leaking these internal libraries to downstream users. It should now be possible to use the client without having to use grpclib or betterproto directly.

Upgrading

• The client now uses a string URL to connect to the server, the grpc_channel and target arguments are now replaced by server_url. The current accepted format is grpc://hostname[:<port:int=9090>][?ssl=<ssl:bool=false>], meaning that the port and ssl are optional and default to 9090 and false respectively. You will have to adapt the way you connect to the server in your code.

• The client is now using grpclib to connect to the server instead of grpcio. You might need to adapt your code if you are using grpcio directly.

• The client now doesn't raise grpc.aio.RpcError exceptions anymore. Instead, it raises its own exceptions, one per gRPC error status code, all inheriting from GrpcError, which in turn inherits from ClientError (as any other exception raised by this library in the future). GrpcErrors have the grpclib.GRPCError as their __cause__. You might need to adapt your error handling code to catch these specific exceptions instead of grpc.aio.RpcError.

  You can also access the underlying grpclib.GRPCError using the grpc_error attribute for GrpStatusError exceptions, but it is discouraged because it makes downstream projects dependant on grpclib too

• The client now uses protobuf/grpc bindings generated betterproto (frequenz-microgrid-betterproto) instead of grpcio (frequenz-api-microgrid). If you were using the bindings directly, you might need to do some minor adjustments to your code.

• If an unknown EV charger component state is received, it will now be set to EVChargerComponentState.UNKNOWN instead of EVChargerComponentState.UNSPECIFIED.

New Features

• The client now raises more specific exceptions based on the gRPC status code, so you can more easily handle different types of errors.

  For example:

  try:
     connections = await client.connections()
  except OperationTimedOut:
     ...

  instead of:

  try:
     connections = await client.connections()
  except grpc.aio.RpcError as e:
     if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
        ...

• We now expose component errors as part of the streamed component data:

  • BatteryData.errors
  • InverterData.errors

• We now expose component states as part of the streamed component data:

  • BatteryData.component_state and BatteryData.relay_state
  • InverterData.component_state

• Added the missing EVChargerComponentState.UNKNOWN state.

Bug Fixes

• Fix a leakage of GrpcStreamBroadcaster instances.
• The user-passed retry strategy was not properly used by the data streaming methods.
• The client set_bounds() method might have not done anything and if it did, errors were not properly raised.

What's Changed

• Clear release notes by @llucax in #32
• Bump nox from 2023.4.22 to 2024.3.2 by @dependabot in #35
• Update protobuf requirement from <5,>=4.21.6 to >=4.21.6,<6 by @dependabot in #34
• Bump nox from 2024.3.2 to 2024.4.15 in the required group by @dependabot in #38
• Improve exception messages by @llucax in #43
• Fix a few bugs related to GrpcStreamBroadcaster by @llucax in #42
• Bump client-base to v0.4.0 by @llucax in #44
• Properly await for AddInclusionBounds by @llucax in #47
• Allow using None to specify the default retry strategy by @llucax in #46
• Raise a new ClientError instead of AioRpcError by @llucax in #48
• Convert to betterproto by @llucax in #37
• Make the client accept a server URL to connect to by @llucax in #49
• Add specific gRPC client errors by @llucax in #53
• Add missing state and error wrappers by @llucax in #54

Full Changelog: v0.3.0...v0.4.0

v0.3.0

Frequenz Microgrid API Client Release Notes

New Features

• The reactive_power is exposed for meters, inverters and EV chargers.

What's Changed

• Clear RELEASE_NOTES.md by @shsms in #27
• Add reactive power for inverters, meters and EV chargers by @llucax in #30
• Improve Location docs and tests by @llucax in #29
• Widen the channels dependency by @llucax in #31

Full Changelog: v0.2.0...v0.3.0