enphase envoy docs quality improvement #36128
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 Walkthrough📝 WalkthroughWalkthroughThe documentation for the Enphase Envoy integration has been extensively revised to improve clarity and detail regarding its functionality and supported devices. Key updates include a clear distinction between older and newer models, the addition of sections on supported and unsupported devices, expanded prerequisites, and new requirements for manual input. The data updates section has been restructured, and the integration's actions have been redefined with detailed examples. Additionally, the troubleshooting and diagnostics report sections have been enhanced for better user guidance. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Integration
participant Envoy
User->>Integration: Configure Envoy
Integration->>Envoy: Send configuration details (host, username, password)
Envoy-->>Integration: Acknowledge configuration
Integration->>Envoy: Request data updates
Envoy-->>Integration: Provide data based on polling interval
Integration->>User: Display data
User->>Integration: Request troubleshooting
Integration->>Envoy: Enable debug logs
Envoy-->>Integration: Provide log information
Integration->>User: Display logs and diagnostics report
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (9)
source/_integrations/enphase_envoy.markdown (9)
26-26: Fix grammatical error in introductionThe possessive form "its" should be used instead of the contraction "it's".
-The **Enphase Envoy** {% term integration %} is used to integrate with the [Enphase IQ Gateway](https://enphase.com/en-us/products-and-services/envoy-and-combiner), a communication device for [Enphase](https://enphase.com/homeowners) solar inverters and batteries. In this documentation, as well as in integration entity names, the Enphase IQ Gateway is commonly referred to as `Envoy`, a name from the conception times of this integration and retained for it's compact format. +The **Enphase Envoy** {% term integration %} is used to integrate with the [Enphase IQ Gateway](https://enphase.com/en-us/products-and-services/envoy-and-combiner), a communication device for [Enphase](https://enphase.com/homeowners) solar inverters and batteries. In this documentation, as well as in integration entity names, the Enphase IQ Gateway is commonly referred to as `Envoy`, a name from the conception times of this integration and retained for its compact format.🧰 Tools
🪛 LanguageTool
[grammar] ~26-~26: Is an article like ‘a’ or ‘an’ missing?
Context: ... of this integration and retained for it's compact format. ## Supported devices ...(BE_NN)
32-33: Fix abbreviation formatThe abbreviation "i.e." should include periods after each letter.
-Older and newer <abbr title="IQ Gateway">Envoy</abbr> models that only have production metrics (ie. Envoy-R (LCD), Envoy-S (not metered)) -Newer <abbr title="IQ Gateway">Envoy</abbr> models that offer both production and consumption metrics (ie. Envoy-S Metered equipped with <abbr title="current transformers">CT</abbr>). +Older and newer <abbr title="IQ Gateway">Envoy</abbr> models that only have production metrics (i.e., Envoy-R (LCD), Envoy-S (not metered)) +Newer <abbr title="IQ Gateway">Envoy</abbr> models that offer both production and consumption metrics (i.e., Envoy-S Metered equipped with <abbr title="current transformers">CT</abbr>).🧰 Tools
🪛 LanguageTool
[uncategorized] ~32-~32: The abbreviation “i.e.” (= that is) requires two periods.
Context: ...dels that only have production metrics (ie. Envoy-R (LCD), Envoy-S (not metered)) -...(I_E)
[uncategorized] ~33-~33: The abbreviation “i.e.” (= that is) requires two periods.
Context: ...oth production and consumption metrics (ie. Envoy-S Metered equipped with <abbr tit...(I_E)
38-38: Fix grammar in unsupported devices sectionCorrect the verb form after "does not".
-This integration does not works with: +This integration does not work with:🧰 Tools
🪛 LanguageTool
[grammar] ~38-~38: The auxiliary verb ‘do’ requires the base form of the verb.
Context: ...rted devices This integration does not works with: - Older Envoy models running fir...(DID_BASEFORM)
69-69: Fix subject-verb agreementThe verb should be plural to match the plural subject.
-Options to enable/disable are listed below. Neither of these are set by default nor need to be set for proper functioning of the integration. Setting these is only required in described circumstances. +Options to enable/disable are listed below. Neither of these are set by default nor need to be set for proper functioning of the integration. Setting these options is only required in described circumstances.🧰 Tools
🪛 LanguageTool
[grammar] ~69-~69: The verb ‘is’ is singular. Did you mean: “this is” or “these are”?
Context: ...functioning of the integration. Setting these is only required in described circumstance...(SINGULAR_VERB_AFTER_THESE_OR_THOSE)
75-75: Improve readability of connection descriptionRemove unnecessary comma and restructure the sentence for better clarity.
-Always use a new connection when requesting data from the Envoy: - description: "No/Yes <br> Some older Envoy firmware may exhibit connection issues when using the, by default enabled, keep-alive connection and report failures. When set, this option disables the use of keep-alive and builds a new connection at each data request. This makes the communication more reliable for these firmware versions. Reported for the Envoy-R, but may apply to other older firmware versions as well." +Always use a new connection when requesting data from the Envoy: + description: "No/Yes <br> Some older Envoy firmware may exhibit connection issues when using the default keep-alive connection and report failures. When set, this option disables the use of keep-alive and builds a new connection at each data request. This makes the communication more reliable for these firmware versions. Reported for the Envoy-R, but may apply to other older firmware versions as well."🧰 Tools
🪛 LanguageTool
[grammar] ~75-~75: Articles like ‘the’ are rarely followed by punctuation. A word may be missing after ‘the’, or the punctuation mark may not be necessary.
Context: ...ay exhibit connection issues when using the, by default enabled, keep-alive connecti...(THE_PUNCT)
161-163: Fix typos and formatting in data updates sectionRemove word repetition and add hyphen for time period.
-The integration collects data by default every 60 seconds. To customize the collection interval interval, refer to [defining a custom polling interval](/common-tasks/general/#defining-a-custom-polling-interval). +The integration collects data by default every 60 seconds. To customize the collection interval, refer to [defining a custom polling interval](/common-tasks/general/#defining-a-custom-polling-interval). -Envoy installations without installed <abbr title="current transformers">CT</abbr>, collect individual solar inverter data every 5 minutes. This collection does not occur for each inverter at the same time in the 5 min period. +Envoy installations without installed <abbr title="current transformers">CT</abbr>, collect individual solar inverter data every 5 minutes. This collection does not occur for each inverter at the same time in the 5-min period.🧰 Tools
🪛 LanguageTool
[duplication] ~161-~161: Possible typo: you repeated a word
Context: ...60 seconds. To customize the collection interval interval, refer to [defining a custom polling in...(ENGLISH_WORD_REPEAT_RULE)
[uncategorized] ~163-~163: When a number forms part of an adjectival compound, use a hyphen.
Context: ...r each inverter at the same time in the 5 min period. Shortening the collection inter...(MISSING_HYPHEN)
193-193: Remove trailing spacesRemove trailing spaces for consistent formatting.
-These actions turn on, off or toggle +These actions turn on, off or toggle -This action changes the: +This action changes the:Also applies to: 240-240
🧰 Tools
🪛 Markdownlint (0.35.0)
193-193: Expected: 0 or 2; Actual: 1
Trailing spaces(MD009, no-trailing-spaces)
274-274: Fix preposition usageUse the correct preposition with "accompanied".
-Firmware is pushed to the Envoy by Enphase, while 'not always communicated in detail upfront'. This may result in sudden changes in the Envoy behavior and is always accompanied with an outage while Envoy is being updated. +Firmware is pushed to the Envoy by Enphase, while 'not always communicated in detail upfront'. This may result in sudden changes in the Envoy behavior and is always accompanied by an outage while Envoy is being updated.🧰 Tools
🪛 LanguageTool
[grammar] ~274-~274: The usual collocation for “accompany” is “by”, not “with”.
Context: ...ges in the Envoy behavior and is always accompanied with an outage while Envoy is being updated....(ACCOMPANY_WITH)
165-165: Fix punctuationAdd missing comma before "however".
-With installed <abbr title="current transformers">CT</abbr>, data granularity increases and shortening the collection interval can provide more details. The Envoy however, has no unlimited resources and shortening the collection interval may result in dropped connections, Envoy freeze or restarts. +With installed <abbr title="current transformers">CT</abbr>, data granularity increases and shortening the collection interval can provide more details. The Envoy, however, has no unlimited resources and shortening the collection interval may result in dropped connections, Envoy freeze or restarts.🧰 Tools
🪛 LanguageTool
[formatting] ~165-~165: Consider inserting a comma before ‘however’.
Context: ... interval can provide more details. The Envoy however, has no unlimited resources and shorteni...(HOWEVER_MISSING_COMMA)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/enphase_envoy.markdown(5 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/enphase_envoy.markdown
[grammar] ~26-~26: Is an article like ‘a’ or ‘an’ missing?
Context: ... of this integration and retained for it's compact format. ## Supported devices ...
(BE_NN)
[uncategorized] ~32-~32: The abbreviation “i.e.” (= that is) requires two periods.
Context: ...dels that only have production metrics (ie. Envoy-R (LCD), Envoy-S (not metered)) -...
(I_E)
[uncategorized] ~33-~33: The abbreviation “i.e.” (= that is) requires two periods.
Context: ...oth production and consumption metrics (ie. Envoy-S Metered equipped with <abbr tit...
(I_E)
[grammar] ~38-~38: The auxiliary verb ‘do’ requires the base form of the verb.
Context: ...rted devices This integration does not works with: - Older Envoy models running fir...
(DID_BASEFORM)
[grammar] ~69-~69: The verb ‘is’ is singular. Did you mean: “this is” or “these are”?
Context: ...functioning of the integration. Setting these is only required in described circumstance...
(SINGULAR_VERB_AFTER_THESE_OR_THOSE)
[grammar] ~75-~75: Articles like ‘the’ are rarely followed by punctuation. A word may be missing after ‘the’, or the punctuation mark may not be necessary.
Context: ...ay exhibit connection issues when using the, by default enabled, keep-alive connecti...
(THE_PUNCT)
[duplication] ~161-~161: Possible typo: you repeated a word
Context: ...60 seconds. To customize the collection interval interval, refer to [defining a custom polling in...
(ENGLISH_WORD_REPEAT_RULE)
[uncategorized] ~163-~163: When a number forms part of an adjectival compound, use a hyphen.
Context: ...r each inverter at the same time in the 5 min period. Shortening the collection inter...
(MISSING_HYPHEN)
[formatting] ~165-~165: Consider inserting a comma before ‘however’.
Context: ... interval can provide more details. The Envoy however, has no unlimited resources and shorteni...
(HOWEVER_MISSING_COMMA)
[grammar] ~274-~274: The usual collocation for “accompany” is “by”, not “with”.
Context: ...ges in the Envoy behavior and is always accompanied with an outage while Envoy is being updated....
(ACCOMPANY_WITH)
[style] ~279-~279: ‘in brief’ might be wordy. Consider a shorter alternative.
Context: ... forth between the interfaces resulting in brief outages every 30 minutes. If you experi...
(EN_WORDINESS_PREMIUM_IN_BRIEF)
[uncategorized] ~287-~287: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...e is intermittent, this may take a while and it may grow the log file quite a bit. ...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~289-~289: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...t. If you're expecting features to show but they are not shown, make sure to reload...
(COMMA_COMPOUND_SENTENCE)
🪛 Markdownlint (0.35.0)
source/_integrations/enphase_envoy.markdown
193-193: Expected: 0 or 2; Actual: 1
Trailing spaces
(MD009, no-trailing-spaces)
240-240: Expected: 0 or 2; Actual: 1
Trailing spaces
(MD009, no-trailing-spaces)
292-292: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
292-292: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
363-363: null
Files should end with a single newline character
(MD047, single-trailing-newline)
361-361: null
Link fragments should be valid
(MD051, link-fragments)
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
source/_integrations/enphase_envoy.markdown (4)
57-76: Improve formatting in configuration blocks for better readability.While the content is accurate, the formatting could be improved for better readability.
Consider adding line breaks between configuration items:
{% configuration_basic %} Host: description: "The name or IP address of the Envoy to configure. <br> Will be pre-filled if the Envoy was auto-discovered" Username: description: "For firmware version 7.0 and later, enter your Enlighten cloud username <br> For firmware before 7.0, enter username *installer* without a password." Password: description: "For firmware version 7.0 and later, enter your Enlighten cloud password <br> For firmware before 7.0, with username *installer*, leave blank." {% endconfiguration_basic %}🧰 Tools
🪛 LanguageTool
[uncategorized] ~69-~69: You might be missing the article “the” here.
Context: ...tting these options is only required in described circumstances. {% configuration_basic ...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
161-165: Fix grammatical issues and improve clarity.There are some grammatical issues and opportunities for improved clarity:
- Add missing articles and commas:
-Specify one single entity from the envoy device as target of the action +Specify one single entity from the envoy device as the target of the action -Updating one entity will update all entities of the Envoy and the related devices like the inverters +Updating one entity will update all entities of the Envoy and the related devices, like the inverters
- Consider restructuring the paragraph about CT installations for better readability:
-With installed CT, data granularity increases and shortening the collection interval can provide more details. +With installed CTs, data granularity increases, and shortening the collection interval can provide more detailed information.🧰 Tools
🪛 LanguageTool
[uncategorized] ~161-~161: You might be missing the article “the” here.
Context: ... single entity from the envoy device as target of the action using the `+ choose entit...(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~161-~161: Possible missing comma found.
Context: ...l entities of the Envoy and the related devices like the inverters; there is no need to...(AI_HYDRA_LEO_MISSING_COMMA)
274-275: Consider highlighting the firmware limitation more prominently.The firmware limitation in version 8.2.4225 is a critical issue that affects core functionality.
Consider adding a warning note block:
+{% warning %} As of Envoy firmware 8.2.4225 the Envoy does no longer support setting battery modes, Enable/Disable charge from grid or changing reserve battery level through the local REST API used by HA. Until a resolution is found, you will need to use the Enphase APP to control these. +{% endwarning %}
287-293: Fix formatting and grammatical issues in troubleshooting section.There are several minor issues to address:
- Add missing commas:
-When reporting the issue include the debug log file +When reporting the issue, include the debug log file
- Fix emphasis formatting:
-_download of debug log file will start automatically_ +*download of debug log file will start automatically*🧰 Tools
🪛 LanguageTool
[uncategorized] ~287-~287: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...e is intermittent, this may take a while and it may grow the log file quite a bit. ...(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~289-~289: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...t. If you're expecting features to show but they are not shown, make sure to reload...(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~292-~292: A comma might be missing here.
Context: ...art automatically_). When reporting the issue include the debug log file as well as a...(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
🪛 Markdownlint (0.35.0)
292-292: Expected: asterisk; Actual: underscore
Emphasis style(MD049, emphasis-style)
292-292: Expected: asterisk; Actual: underscore
Emphasis style(MD049, emphasis-style)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (1)
source/_integrations/enphase_envoy.markdown(5 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/enphase_envoy.markdown
[uncategorized] ~69-~69: You might be missing the article “the” here.
Context: ...tting these options is only required in described circumstances. {% configuration_basic ...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~161-~161: You might be missing the article “the” here.
Context: ... single entity from the envoy device as target of the action using the `+ choose entit...
(AI_EN_LECTOR_MISSING_DETERMINER_THE)
[uncategorized] ~161-~161: Possible missing comma found.
Context: ...l entities of the Envoy and the related devices like the inverters; there is no need to...
(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~279-~279: A comma might be missing here.
Context: ...ry to switch back and forth between the interfaces resulting in brief outages every 30 min...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
[style] ~279-~279: ‘in brief’ might be wordy. Consider a shorter alternative.
Context: ... forth between the interfaces resulting in brief outages every 30 minutes. If you experi...
(EN_WORDINESS_PREMIUM_IN_BRIEF)
[uncategorized] ~287-~287: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...e is intermittent, this may take a while and it may grow the log file quite a bit. ...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~289-~289: Use a comma before ‘but’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...t. If you're expecting features to show but they are not shown, make sure to reload...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~292-~292: A comma might be missing here.
Context: ...art automatically_). When reporting the issue include the debug log file as well as a...
(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)
🪛 Markdownlint (0.35.0)
source/_integrations/enphase_envoy.markdown
292-292: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
292-292: Expected: asterisk; Actual: underscore
Emphasis style
(MD049, emphasis-style)
360-360: null
Link fragments should be valid
(MD051, link-fragments)
🔇 Additional comments (3)
source/_integrations/enphase_envoy.markdown (3)
26-40: LGTM! Clear and well-structured device support information.
The introduction and device support sections are well-organized and provide clear information about supported and unsupported devices. Good use of HTML abbreviations for technical terms improves readability.
78-83: LGTM! Clear removal instructions.
The removal instructions are concise and clear.
187-270: LGTM! Well-documented actions with clear examples.
The actions section provides comprehensive documentation with good examples.
Proposed change
Update Enphase Envoy documentation with bronze and silver integration quality scale standard items for documentation.
This update adds a number of missing descriptions, moves some around and extends some others. Missing Gold scale items and overall document optimization will be done in a subsequent PR.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit