v0.12.0

[github-actions[bot]]

Frequenz Migrogrid API Release Notes

Summary

This release introduces a few breaking changes to the API. The changes consist
of renaming RPCs, removing deprecated code, and introducing new features.
Please refer to the following sections for details.

Upgrading

• Renamed RPCs

  The following RPC has been renamed to make their objectives clearer:

  • GetMetadata -> GetMicrogridMetadata
  • GetComponentData -> StreamComponentData

• Removed deprecated code

  The following deprecated code has been removed:

  • The COMPONENT_CATEGORY_LOAD variant from the ComponentCategory enum.
  • The COMPONENT_CATEGORY_JUNCTION variant from the ComponentCategory enum.
  • The RPCs Charge and Discharge, in favour of RPC SetPowerActive.
  • The RPC SetBounds, in favour of RPCs AddExclusiveBounds and
    AddInclusiveBounds.

  This removal also includes code that has been deprecated after the last major
  release. The reason to remove these deprecations now is to have a leaner API
  earlier, since we are already on the way for a major release now.

New Features

• Added new RPC to return the microgrid metadata

  The microgrid metadata consists of information about the overall microgrid,
  as opposed to its components, e.g., the microgrid ID, location, etc.
  This change adds a new RPC GetMicrogridMetadata() that allows users to fetch
  microgrid metadata. The returned value is an instance of the message
  MicrogridMetadata.

  Further changes were introduced to this addition in PR #43.

• Added enum variants for setting bounds on currents

  This will allow clients to set bounds on a components

  1. DC electrical current,
  2. total AC electrical current,
  3. per-phase AC electrical currents.

• Add RPC to set active power using a signed integer

  While reading power values, the passive sign convention is followed
  (-ve for production, and +ve for consumption). This new method allows setting
  active power values in the same convention, making the API more consistent.

• Introduced component category-specific metadata

  This metadata is returned in response to ListComponents calls,
  in a new message variable Component.metadata.
  This is a more general way of representing category-specific metadata,
  like category-type, and removes Component.type.

• Introduced grid max-current

  This change introduces a grid.Metadata message, which contains the item
  rated_fuse_current. This is the rating of the fuse at the grid connection
  point.
  This rating specifies the maximum amount of current, measured in amperes,
  that can flow in or out of each of the 3 phases individually.
  The current i A at the grid connection point must comply with the
  following constraint: : -rated_fuse_current <= i <= rated_fuse_current

• Introduced exclusion bounds

  In the messages common.Metric and common.MetricAggregation,
  system_bounds has now been replaced by system_exclusion_bounds and
  system_inclusion_bounds. A metric's value now has to comply with the
  following constraints:

  • value <= system_exclusion_bounds.lower OR
    system_exclusion_bounds.upper <= value

  • system_inclusion_bounds.lower <= value <= system_inclusion_bounds.upper

  system_inclusion_bounds behave in the same manner as the earlier
  system_bounds.

  The following diagram illustrates the relationship between the exclusion and
  inclusion bounds.

    inclusion.lower                              inclusion.upper
  <-------|============|------------------|============|--------->
                 exclusion.lower    exclusion.upper
  

  ---- values here are disallowed and wil be rejected, and
  ==== values here are allowed and will be accepted.

  Two new simple RPCs for setting exclusion and inclusion bounds have been
  added:

  • AddExclusionBounds: adds a pair of exclusion bounds for a given component
    and metric, and returns the UTC timestamp until when it will stay in effect.
  • AddInclusionBounds: adds a pair of inclusion bounds for a given component
    and metric, and returns the UTC timestamp until when it will stay in effect.

  Exclusion bounds are a useful tool for enhancing the performance of a system.
  They can be used to restrict the acceptance of commands that fall below a
  certain threshold, which can help ensure the smooth functioning of the system.
  E.g., exclusion bounds can be set to limit the minimum charging power to a
  sufficiently high level, preventing a peak-shaver client from sending charge
  powers that are too low when a DC heater client is executing a charge pulse.
  This can significantly improve the overall performance of the DC heating
  mechanism.

  The RPC SetBounds has been deprecated.

Bug Fixes

None

What's Changed

• Remove unnecessary setuptools.find configuration by @leandro-lucarella-frequenz in Remove unnecessary setuptools.find configuration #17
• Clear RELEASE_NOTES.md by @leandro-lucarella-frequenz in Clear RELEASE_NOTES.md #13
• Improve and generate documentation by @leandro-lucarella-frequenz in Improve and generate documentation #21
• Add new RPC to return the microgrid metadata by @tiyash-basu-frequenz in Add new RPC to return the microgrid metadata #30
• ci: Test also Python 3.11 by @leandro-lucarella-frequenz in ci: Test also Python 3.11 #20
• Specify non-guarantee of 1W resolution in methods by @tiyash-basu-frequenz in Specify non-guarantee of 1W resolution in methods #34
• Add enum variants for setting bounds on currents by @tiyash-basu-frequenz in Add enum variants for setting bounds on currents #33
• Add RPC to set active power using a signed integer by @tiyash-basu-frequenz in Add RPC to set active power using a signed integer #36
• Fix a few formatting issues by @tiyash-basu-frequenz in Fix a few formatting issues #37
• Support returning max allowed current at grid connection point by @tiyash-basu-frequenz in Support returning max allowed current at grid connection point #38
• Introduce minimum bounds by @tiyash-basu-frequenz in Introduce minimum bounds #39
• Removing all deprecated code by @tiyash-basu-frequenz in Removing all deprecated code #44
• Rename a few RPCs to improve clarity by @tiyash-basu-frequenz in Rename a few RPCs to improve clarity #43
• Publish to PyPi using trusted publishing by @leandro-lucarella-frequenz in Publish to PyPi using trusted publishing #45
• Update RELEASE_NOTES and README by @tiyash-basu-frequenz in Update RELEASE_NOTES and README #46

New Contributors

• @tiyash-basu-frequenz made their first contribution in Add new RPC to return the microgrid metadata #30

Full Changelog: v0.11.0...v0.12.0

---

This discussion was created from the release v0.12.0.