Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add OSO Energy Service documentation #33070

Merged
merged 2 commits into from
Oct 25, 2024
Merged

Add OSO Energy Service documentation #33070

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1970e26
Add OSO Energy Service documentation
osohotwateriot Jun 4, 2024
52b3c13
Apply suggestions from code review
osohotwateriot Jun 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
190 changes: 190 additions & 0 deletions source/_integrations/osoenergy.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,196 @@ This OSO Energy integration uses a subscription key, which a user can create for

{% include integrations/config_flow.md %}

## Services

### Service `osoenergy.get_profile`

You can use the service `osoenergy.get_profile` to get the temperature profile for a water heater. Each temperature corresponds to the a given local hour during the current day, e.g. temperature at index 1 corresponds to 01:00 local time.
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved

| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------- |
| `entity_id` | no | String, Name of entity e.g., `water_heater.heater` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved

Example:

```yaml
# Example script to get the temperature profile of a water heater.
script:
get_profile:
sequence:
- service: osoenergy.get_profile
target:
entity_id: water_heater.heater
```

```yaml
# Example response for the temperature profile of the heater.
water_heater.heater:
profile:
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
- 70
```

### Service `osoenergy.set_profile`

You can use the service `osoenergy.set_profile` to set the temperature profile for a water heater.

| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------- |
| `entity_id` | no | String, Name of entity e.g., `water_heater.heater` |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarify parameter descriptions.

The description for entity_id in the osoenergy.set_profile service could be standardized to match other descriptions in the document. Consider revising to: "String, specifies the entity name, e.g., water_heater.heater."

| `hour_00` | yes | The temperature at hour 00:00 (Local) for a heater |
| `hour_01` | yes | The temperature at hour 01:00 (Local) for a heater |
| `hour_02` | yes | The temperature at hour 02:00 (Local) for a heater |
| `hour_03` | yes | The temperature at hour 03:00 (Local) for a heater |
| `hour_04` | yes | The temperature at hour 04:00 (Local) for a heater |
| `hour_05` | yes | The temperature at hour 05:00 (Local) for a heater |
| `hour_06` | yes | The temperature at hour 06:00 (Local) for a heater |
| `hour_07` | yes | The temperature at hour 07:00 (Local) for a heater |
| `hour_08` | yes | The temperature at hour 08:00 (Local) for a heater |
| `hour_09` | yes | The temperature at hour 09:00 (Local) for a heater |
| `hour_10` | yes | The temperature at hour 10:00 (Local) for a heater |
| `hour_11` | yes | The temperature at hour 11:00 (Local) for a heater |
| `hour_12` | yes | The temperature at hour 12:00 (Local) for a heater |
| `hour_13` | yes | The temperature at hour 13:00 (Local) for a heater |
| `hour_14` | yes | The temperature at hour 14:00 (Local) for a heater |
| `hour_15` | yes | The temperature at hour 15:00 (Local) for a heater |
| `hour_16` | yes | The temperature at hour 16:00 (Local) for a heater |
| `hour_17` | yes | The temperature at hour 17:00 (Local) for a heater |
| `hour_18` | yes | The temperature at hour 18:00 (Local) for a heater |
| `hour_19` | yes | The temperature at hour 19:00 (Local) for a heater |
| `hour_20` | yes | The temperature at hour 20:00 (Local) for a heater |
| `hour_21` | yes | The temperature at hour 21:00 (Local) for a heater |
| `hour_22` | yes | The temperature at hour 22:00 (Local) for a heater |
| `hour_23` | yes | The temperature at hour 23:00 (Local) for a heater |

Example:

```yaml
# Example script to set temperature profile for a water heater.
script:
set_profile:
sequence:
- service: osoenergy.set_profile
target:
entity_id: water_heater.heater
data:
hour_00: 70
hour_01: 70
hour_02: 70
hour_03: 70
hour_04: 70
hour_05: 70
hour_06: 70
hour_07: 70
hour_08: 70
hour_09: 70
hour_10: 70
hour_11: 70
hour_12: 70
hour_13: 70
hour_14: 70
hour_15: 70
hour_16: 70
hour_17: 70
hour_18: 70
hour_19: 70
hour_20: 70
hour_21: 70
hour_22: 70
hour_23: 70
```

### Service `osoenergy.set_v40_min`

You can use the service `osoenergy.set_v40_min` to set the minimum quantity of water at 40°C for a water heater.

| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------- |
| `entity_id` | no | String, Name of entity e.g., `water_heater.heater` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved
| `v40_min` | no | Specify the minimum quantity of water at 40°C for a water heater, e.g., `240` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved

Examples:

```yaml
# Example script to set minimum water level on a water heater, v40 min specified.
script:
set_v40:
sequence:
- service: osoenergy.set_v40_min
target:
entity_id: water_heater.heater
data:
v40_min: 240
```

### Service `osoenergy.turn_off`

You can use the service `osoenergy.turn_off` to turn off the heating on your device for one hour or until the minimum temperature is reached.

| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `entity_id` | no | String, Name of entity e.g., `water_heater.heater` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved
| `until_temp_limit` | no | Choose if heating should be off until minimum temperature (`True`) is reached or for one hour (`False`), e.g., `True` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved

Examples:

```yaml
# Example script to turn off heating, until temp limit specified.
script:
turn_off:
sequence:
- service: osoenergy.turn_off
target:
entity_id: water_heater.heater
data:
until_temp_limit: true
```

### Service `osoenergy.turn_on`

You can use the service `osoenergy.turn_on` to turn on the heating on your device for one hour or until the maximum temperature is reached.

| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `entity_id` | no | String, Name of entity e.g., `water_heater.heater` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved
| `until_temp_limit` | no | Choose if heating should be on until maximum temperature (`True`) is reached or for one hour (`False`), e.g., `True` |
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved

Examples:

```yaml
# Example script to turn on heating, until temp limit specified.
osohotwateriot marked this conversation as resolved.
Show resolved Hide resolved
script:
turn_on:
sequence:
- service: osoenergy.turn_on
target:
entity_id: water_heater.heater
data:
until_temp_limit: true
```

## Binary sensors

The **OSO Energy** integration exposes OSO Energy data as a binary sensor. It provides the following binary sensors:
Expand Down