-
-
Notifications
You must be signed in to change notification settings - Fork 7.8k
Docs about integration docs #36968
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.
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
Merged
Merged
Docs about integration docs #36968
Changes from 9 commits
Commits
Show all changes
21 commits
Select commit
Hold shift + click to select a range
6507b4c
Docs about integration docs
c0ffeeca7 129405c
Add section on images
c0ffeeca7 f638f92
Fix steps
c0ffeeca7 e01f9b9
rephrase section about reuse
c0ffeeca7 9ed8cc8
add a reference to a video on YT
c0ffeeca7 5ea406b
Fix typo
c0ffeeca7 b38b323
remove platform
c0ffeeca7 abed539
Teaks
c0ffeeca7 702166a
Rename file, remove instructions
c0ffeeca7 cd09ad0
Update source/_integrations/_integration_docs_template.markdown
c0ffeeca7 88945b5
Apply suggestions from code review
c0ffeeca7 eb38808
Comment out instructions
c0ffeeca7 86447e6
rename service to action
c0ffeeca7 32cfe7f
Fix typo
c0ffeeca7 9aa93dc
Update source/_integrations/_integration_docs_template.markdown
c0ffeeca7 c416040
Apply suggestions from code review
c0ffeeca7 82b132d
Update source/_integrations/_integration_docs_template.markdown
c0ffeeca7 0df5420
remove section on community notes
c0ffeeca7 70699bd
Convert table to list
c0ffeeca7 780182c
Streamline My integration name
c0ffeeca7 5768b9a
Streamline My integration name
c0ffeeca7 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
211 changes: 211 additions & 0 deletions
211
source/_integrations/_integration_docs_template.markdown
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,211 @@ | ||
--- | ||
title: Integration documentation template | ||
description: Example document structure and text blocks for integration documentation. | ||
ha_release: 2025.03 | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
ha_iot_class: Local Push | ||
ha_codeowners: | ||
- '@home-assistant/core' | ||
ha_domain: lorem_ipsum | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
ha_integration_type: integration | ||
related: | ||
- url: https://developers.home-assistant.io/docs/documenting/standards | ||
title: Documentation standard | ||
- url: https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/ | ||
title: Integration Quality Scale - Rules | ||
- docs: /docs/glossary/ | ||
title: Glossary | ||
- docs: /docs/tools/quick-bar/#my-links | ||
title: My link | ||
--- | ||
|
||
The integration documentation template provides a documentation structure as well as some example content per section. The example content is meant for inspiration, it may not apply for your integration or will at least have to be adapted. | ||
|
||
Use this template together with the developer documentation, under [Documentation standard](https://developers.home-assistant.io/docs/documenting/standards) and the documentation rules of the [Integration Quality Scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/rules/). | ||
silamon marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
### Example integration documentation text below | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
The **my integration** {% term integration %} is used to integrate with the devices of [MyCompany](https://www.mycompany.com). MyCompany creates various smart home appliances and devices and are known for their MyProduct. | ||
Use case: When you combine it with their other device you can do x. | ||
|
||
## Supported devices | ||
|
||
The following devices are known to be supported by the integration: | ||
|
||
- Device 1 | ||
- Device 2 | ||
- Every appliance that runs MyOS | ||
|
||
## Unsupported devices | ||
|
||
The following devices are not supported by the integration: | ||
|
||
- Device 3 | ||
- Appliances built before 2010 | ||
|
||
## Prerequisites | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
1. Open the app store and install the **MyProduct** app. | ||
2. Create an account. | ||
3. Add a device to the app. | ||
4. Open the app and go to the **Settings** page. | ||
5. Select **Expose API**. | ||
|
||
{% include integrations/config_flow.md %} | ||
|
||
The next section is about documenting configuration variables. For details, refer to the [documentation standard on configuration variables](/docs/documenting/standards#configuration-variables). | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
In case your integration is used via a config flow: | ||
|
||
{% configuration_basic %} | ||
Host: | ||
description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**." | ||
Local access token: | ||
description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**." | ||
{% endconfiguration_basic %} | ||
|
||
In case an integration is set up via YAML in the {% term "`configuration.yaml`" %}: | ||
|
||
{% configuration %} | ||
Host: | ||
description: "The IP address of your bridge. You can find it in your router or in the Integration app under **Bridge Settings** > **Local API**." | ||
required: false | ||
type: string | ||
Local access token: | ||
description: "The local access token for your bridge. You can find it in the Integration app under **Bridge Settings** > **Local API**." | ||
required: false | ||
type: string | ||
{% endconfiguration %} | ||
|
||
## Configuration options | ||
|
||
The integration provides the following configuration options: | ||
|
||
{% configuration_basic %} | ||
Country code: | ||
description: You can specify the country code (NL or BE) of the country to display on the camera. | ||
Timeframe: | ||
description: Minutes to look ahead for precipitation forecast sensors (minimum 5, maximum 120). | ||
{% endconfiguration_basic %} | ||
|
||
## Supported functionality | ||
|
||
### Entities | ||
|
||
The XY integration provides the following entities. | ||
|
||
#### Buttons | ||
|
||
- **Start backflush** | ||
- **Description**: Starts the backflush process on your machine. You got 15 seconds to turn the paddle after activation. | ||
- **Available for machines**: all | ||
|
||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
#### Numbers | ||
|
||
- **Dose** | ||
- **Description**: Dosage (in ticks) for each key | ||
- **Available for machines**: GS3 AV, Linea Mini. | ||
- **Remarks**: GS3 has this multiple times, one for each physical key (1-4), and the entities are disabled by default. | ||
|
||
#### Sensors | ||
|
||
- **Current coffee temperature** | ||
- **Description**: Current temperature of the coffee boiler. | ||
- **Available for machines**: all | ||
- **Remarks**: When the machine reaches temperature, this will be approximately 3 degrees higher than the `Coffee target temperature`, due to different measurement points. | ||
|
||
- **Current steam temperature** | ||
- **Description**: Current temperature of the steam boiler. | ||
- **Available for machines**: Linea Micra, GS3 AV, GS3 MP. | ||
- **Remarks**: - | ||
|
||
#### Selects | ||
|
||
- **Prebrew/-infusion mode** | ||
- **Description**: Whether to use prebrew, preinfusion, or neither. | ||
- **Options**: Disabled, Prebrew, Preinfusion | ||
- **Available for machines**: Linea Micra, Linea Mini, GS3 AV | ||
|
||
- **Steam level** | ||
- **Description**: The level your steam boiler should run at. | ||
- **Options**: 1, 2, 3 | ||
- **Available for machines**: Linea Micra#### Updates | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
- **Gateway firmware** | ||
- **Description**: Firmware status of the gateway. | ||
- **Available for machines**: all | ||
|
||
## Actions | ||
|
||
The integration provides the following actions. | ||
|
||
### Action: Get schedule | ||
|
||
The `my_integration.get_schedule` service is used to fetch a schedule from the integration. | ||
|
||
| Data attribute | Optional | Description | | ||
| ----------------- | -------- | ---------------------------------------------------- | | ||
| `config_entry_id` | No | The ID of the config entry to get the schedule from. | | ||
|
||
## Examples | ||
|
||
### Turning off the LEDs during the night | ||
|
||
The status LEDs on the device can be quite bright. | ||
To tackle this, you can use this blueprint to easily automate the LEDs turning off when the sun goes down. | ||
|
||
link to blueprint. | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Data updates | ||
|
||
The **My** integration fetches data from the device every 5 minutes by default. | ||
Newer devices (the ones running MyOS) have the possibility to push data. | ||
In this case, pushing data is enabled when the integration is started. If enabling data push fails, the integration uses data {% term polling %}. | ||
|
||
## Known limitations | ||
|
||
The integration does not provide the ability to reboot, which can instead be done via the manufacturer's app. | ||
|
||
## Troubleshooting | ||
|
||
### Can’t set up the device | ||
|
||
#### Symptom: “This device can’t be reached” | ||
|
||
When trying to set up the integration, the form shows the message “This device can’t be reached”. | ||
|
||
##### Description | ||
|
||
This means the settings on the device are incorrect, since the device needs to be enabled for local communication. | ||
|
||
##### Resolution | ||
|
||
To resolve this issue, try the following steps: | ||
|
||
1. Make sure your device is powered up (LEDs are on). | ||
2. Make sure your device is connected to the internet: | ||
- Make sure the app of the manufacturer can see the device. | ||
3. Make sure the device has the local communication enabled: | ||
- Check the device’s settings. | ||
- Check the device’s manual. | ||
... | ||
|
||
### I can't see my devices | ||
|
||
Make sure the devices are visible and controllable via the manufacturer's app. | ||
If they are not, check the device's power and network connection. | ||
|
||
### The device goes unavailable after a day | ||
|
||
Make sure you turned off the device's power-saving mode. | ||
|
||
## Community notes | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Note that some users have reported issues creating Home Assistant containers on ARM QNAP systems (for example, TS-233) with Container Station 3. A possible workaround is the "Docker compose" approach based on a YAML file (see section "Docker compose"). | ||
c0ffeeca7 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
## Removing the integration | ||
|
||
This integration follows standard integration removal. | ||
|
||
{% include integrations/remove_device_service.md %} | ||
|
||
After deleting the integration, go to the app of the manufacturer and remove the Home Assistant integration from there as well. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.