v0.13.0

Frequenz Migrogrid API Release Notes

Summary

This release adds a breaking change to improve the DC data reporting
capabilities for inverters.

This release also adds non-breaking changes to extend the API to support more
sensor types, and to add support for adding bounds on AC reactive power.

Upgrading

• Updated inverters' DC links to support hybrid and solar inverters

  The Inverter message has been updated to support hybrid and solar inverters.
  The dc field has been renamed to dc_battery, and a new field dc_solar
  has been added.
  The dc_battery field is used to report the DC electricity flowing to/from
  the linked battery, and is applicable to battery and hybrid inverters.
  The dc_solar field is used to report the DC electricity flowing to/from the
  linked solar panels, and is applicable to solar and hybrid inverters.

New Features

• Added a general sensor type

  Some sensors can be a collection of several individual sensor modules. E.g.,
  a sensor can have pyranometer and anemometer sensor modules, and report both
  irradiance and wind velocity and direction. This new sensor type
  TYPE_GENERAL supports such cases.

• Added dew point to sensor metrics

  Dew point is the temperature to which air must be cooled to become saturated
  with water vapor. When further cooled, the airborne water vapor will condense
  to form liquid water (dew).
  This metric has now been added to the SensorMetric enum as
  SENSOR_METRIC_DEW_POINT.

• Added enum variant for setting bounds on AC reactive power
  This will allow clients to set bounds on a component's AC reactive power.

Bug Fixes

None

What's Changed

• Clear release notes by @tiyash-basu-frequenz in #48
• Extend the API for sensors by @tiyash-basu-frequenz in #49
• Support solar and battery DC links for inverters by @tiyash-basu-frequenz in #50
• Update CODEOWNERS by @tiyash-basu-frequenz in #52
• Add enum variant for setting bounds on AC reactive power by @tiyash-basu-frequenz in #51
• Update release notes by @tiyash-basu-frequenz in #54

Full Changelog: v0.12.0...v0.13.0

v0.12.0

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

New Contributors

• @tiyash-basu-frequenz made their first contribution in #30

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

v0.11.0

Frequenz Migrogrid API Release Notes

Summary

This is the first public open source release based on the internal version v0.10.0. There are no breaking changes in this release, only changes to the
project structure, metadata, and automation. Packages are also now uploaded to PyPI as frequenz-api-microgrid, so this project now can be installed normally via pip:

python -m pip install frequenz-api-microgrid

The GitHub issues were also improved, adding templates for reporting issues and requesting features. Users are also pointed to the Discussion forums when trying to open an issue if they have questions instead. Also many labels are assigned automatically on issue and pull request creation.

What's Changed

• Add CODEOWNERS file by @leandro-lucarella-frequenz in #2
• ci: Add automatic pull request labeler by @leandro-lucarella-frequenz in #3
• Add GitHub issue form templates by @leandro-lucarella-frequenz in #4
• Add KeywordLabeler app configuration by @leandro-lucarella-frequenz in #5
• Upload packages to PyPI by @leandro-lucarella-frequenz in #8
• ci: Create GitHub Release automatically by @leandro-lucarella-frequenz in #9
• Add write permissions to the release job by @leandro-lucarella-frequenz in #11

New Contributors

• @leandro-lucarella-frequenz made their first contribution in #2

Full Changelog: https://github.com/frequenz-floss/frequenz-api-microgrid/commits/v0.11.0