Improve README.md #248
Description
What's needed?
I'd like to suggest to improve the README.md as follows:
# Frequenz Dispatch API
[](https://github.com/frequenz-floss/frequenz-api-dispatch/actions/workflows/ci.yaml)
[](https://pypi.org/project/frequenz-api-dispatch/)
[](https://frequenz-floss.github.io/frequenz-api-dispatch/)
## Introduction
The Frequenz Dispatch API is a gRPC-based service that enables applications to send real-time and scheduled dispatch instructions to microgrids. These dispatches allow to control the behavior of various microgrid components by sending operational directives such as charging a battery, reducing inverter output, or activating demand-side flexibility.
For an architectural overview and how this API fits into the Frequenz stack, please refer to the [API stack wiki](https://github.com/frequenz-floss/frequenz-sdk-python/wiki/APIs-stack-and-repositories-structure).
## Capabilities
The Dispatch API provides full lifecycle support for dispatches including creation, update, deletion, and real-time streaming. It allows targeting of dispatches to specific electrical components by ID, or to component categories like all Li-ion batteries or all EV chargers. Each dispatch contains timing and targeting parameters, and may optionally include recurrence rules that define if and how often the dispatch should repeat.
Support for dry-run dispatches is included, allowing system operators or developers to simulate the execution of a dispatch without making actual changes to the microgrid components. These dry-runs can be helpful for verifying logic or validating integrations without any operational impact.
## Typical Applications
This API can be used in various energy management scenarios, such as automatically charging or discharging a battery based on electricity market signals, limiting the production of a photovoltaic array during periods of low demand, activating or deactivating flexibility for ancillary services like Frequency Containment Reserve (FCR), or dynamically adjusting the power usage of electric vehicle chargers in response to grid conditions.
It also supports use cases where microgrids are partially or fully automated and need a consistent and secure method to receive scheduling and control instructions.
## Design Considerations
Dispatches are designed to be timezone-agnostic by using UTC timestamps throughout. Clients, particularly edge controllers, are responsible for translating these times to local time zones as needed.
The recurrence rule engine follows an RFC5545-inspired structure, enabling advanced scheduling options such as "every weekday at 15:00" or "last Sunday of every month". Developers can define start and end conditions, recurrence intervals, and specific timing constraints like hour, minute, weekday, monthday, and month values.
Filtering and querying capabilities are extensive, allowing consumers of the API to retrieve dispatches by time intervals, target components, activity status, recurrence properties, or update timestamps. Results can be sorted by start time, creation time, or last update time in either ascending or descending order.
Dispatch payloads are flexible and structured as JSON, with limits on nesting and total size to ensure efficient and safe processing. This allows encoding additional behavior or metadata into a dispatch that can be interpreted by the receiving controller.
## Getting Started
The API client is available via [PyPI](https://pypi.org/project/frequenz-api-dispatch/) and integrates easily with the Frequenz SDK. Full protocol documentation is published at the [documentation site](https://frequenz-floss.github.io/frequenz-api-dispatch/).
## Contributing
To learn how to build, test, and contribute to this API, please read the [Contributing Guide](CONTRIBUTING.md).
Other improvements
- The README is too short. It has 26 lines and 1255 characters. (Recommended: >30 lines and >1200 characters)
- A 'Quick Start' section is missing. This helps users get started immediately.
- The README should contain at least one code example (in a
```block) or a section titled '## Code Example'. - Installation instructions or a dedicated '## Installation' section is missing.
A good README typically includes:
- A clear project description.
- A 'Quick Start' guide.
- Detailed 'Installation' instructions.
- Code examples.
- A link to the full documentation.