Document sensors and diagnostic sensors in NUT #38163
Conversation
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
📝 WalkthroughWalkthroughThe changes introduce a new "Supported functionality" section in the NUT integration documentation, detailing the capabilities of the integration by outlining available sensor metrics. This includes general sensors, such as alarms and battery charge, as well as diagnostic sensors like ambient temperature and battery capacity, each with descriptions. The previous "UPS Status - human-readable version" section has been removed, enhancing the document's clarity and organization. Changes
🪧 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
🧹 Nitpick comments (4)
source/_integrations/nut.markdown (4)
50-57: New "Supported functionality" Section Introduced
The new section clearly introduces the supported sensors and diagnostic sensors for the NUT integration. The note block succinctly explains that only the available sensors (as reported by the NUT server) are added to Home Assistant.
Consider adding a brief explanation or a link to further details on what “variables” are (e.g., linking to the official NUT documentation) to further assist end users in understanding the scope.
58-81: Enhanced Sensors Documentation
The "Sensors" section now presents a clear description alongside a well-formatted table of available sensor types. The table is informative and covers a broad set of measurements.
- Suggestion: The "Watts" sensor (line 78) has an empty description. It may help users if a short explanation (e.g., "Power consumption" or similar) is added.
- Verification: Also, please verify that the sensor names are sorted alphabetically as indicated by the PR objectives.
83-96: Outlet Sensors Table Consistency
The table for outlet sensors is comprehensive and clearly outlines the sensor details for individual outlets.
- Suggestion: To fully align with the PR objective of alphabetical ordering, please double-check that the outlet sensor rows are arranged alphabetically by name.
97-112: Comprehensive Diagnostic Sensors Section
This section provides detailed information on diagnostic sensors, including guidance on which sensors are enabled by default and how to enable others. The accompanying note about "opaque by mfg" is especially helpful for understanding manufacturer-specific values.
- Suggestion: As with the "Sensors" section, consider verifying and, if necessary, reordering the diagnostic sensors in alphabetical order to maintain consistency with PR objectives.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
source/_integrations/nut.markdown (2)
58-82: Clear and Concise Sensors SectionThe "Sensors" subsection is well structured. It starts with a brief description and then presents a neatly formatted table listing the sensor name, unit, and description. One minor suggestion: consider adding a short description for the "Watts" sensor if a meaningful metric exists.
113-228: Comprehensive Diagnostic Sensors TableThis extensive table lists diagnostic sensors along with their units and descriptions. The alphabetical ordering (with minor grouping based on naming conventions) aids readability. As a nitpick, it might be worth reviewing individual sensor descriptions for completeness and consistency.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/nut.markdown(1 hunks)
🔇 Additional comments (4)
source/_integrations/nut.markdown (4)
50-57: New "Supported functionality" Section AddedThis block cleanly introduces the new section that outlines the capabilities of the NUT integration. The note block immediately provides context on how variables are retrieved from the NUT server. Overall, this addition enhances the documentation clarity.
83-96: Outlet Sensor Details and External ReferenceThe text following the sensors table clearly differentiates sensors provided per outlet and explains their specific utility. Including the link to the official NUT variable names documentation helps users find more detailed information.
97-111: Diagnostic Sensors Description and NoteThe diagnostic sensors section is introduced well. The description explains that these sensors are disabled by default (to reduce storage overhead) and the accompanying note clarifies the "opaque by mfg" terminology effectively.
229-235: Individually Monitored Outlet SensorsThe table for outlet-specific diagnostic sensors is clear and the use of backticks for the placeholder
nameimproves clarity. This small, focused table complements the main diagnostic sensors list very well.
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
source/_integrations/nut.markdown (2)
92-103: Clear Diagnostic Sensors Section with Minor TypoThe "Diagnostic sensors" section is well introduced with an important note that details the default-disabled state of most diagnostic sensors. Please fix the typo on line 98 ("diganostic") to "diagnostic" to maintain consistency.
-Most of this integration's diagnostic sensors are disabled by default -to reduce storage overhead for Home Assistant. The diganostic sensors +Most of this integration's diagnostic sensors are disabled by default +to reduce storage overhead for Home Assistant. The diagnostic sensors
111-225: Comprehensive Diagnostic Sensor List with Minor TyposThis section provides an extensive and detailed list of diagnostic sensors, which is valuable for users needing deep insights. A few minor corrections are suggested for clarity:
Line 116: Correct the spacing error in the phrase "t he thresholds".
- **Ambient temperature status**\*: Ambient temperature status relative to t he thresholds + **Ambient temperature status**\*: Ambient temperature status relative to the thresholdsLine 174: Remove the unnecessary comma for smoother reading.
- **Low battery voltage (V)**: Minimum battery voltage, that triggers FSD status + **Low battery voltage (V)**: Minimum battery voltage that triggers FSD statusAdditionally, please review any similar minor duplications flagged by static analysis (e.g., lines 68, 83–85, 170, and 218) to ensure consistency and clarity throughout the list.
🧰 Tools
🪛 LanguageTool
[grammar] ~115-~115: This phrase is duplicated. You should probably use “Ambient temperature” only once.
Context: ...holds - Ambient temperature (°C)*: Ambient temperature - Ambient temperature status*: Ambient temperature status ...(PHRASE_REPETITION)
[grammar] ~116-~116: Check that the noun ‘thresholds’ after the pronoun ‘he’ is correct. You may need to use a different part of speech, or use ‘the’ instead.
Context: ...mbient temperature status relative to t he thresholds - Apparent power (VA): Current valu...(PRP_VB)
[duplication] ~170-~170: Possible typo: you repeated a word.
Context: ... Interval to wait before restarting the load - Load shutdown timer (secs): Time before th...(ENGLISH_WORD_REPEAT_RULE)
[typographical] ~175-~175: Make sure that the comma (,) is correct. Do not use a comma before a dependent clause that starts with ‘that’.
Context: ...y voltage (V)**: Minimum battery voltage, that triggers FSD status - **Low voltage tra...(COMMA_THAT_NOUN)
[duplication] ~218-~218: Possible typo: you repeated a word.
Context: ...: Interval to wait before rebooting the UPS - UPS shutdown delay (secs): Interval to wa...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/nut.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/nut.markdown
[duplication] ~68-~68: Possible typo: you repeated a word.
Context: ...nt - Input load (%): Load on (ePDU) input - Input voltage (V): Input voltage - **Load (...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~83-~83: Possible typo: you repeated a word.
Context: ...et NAME current (A)**: Current of named outlet - Outlet NAME description: Description of name...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~84-~84: Possible typo: you repeated a word.
Context: ...AME description**: Description of named outlet - Outlet NAME power (VA): Apparent power of na...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~85-~85: Possible typo: you repeated a word.
Context: ...E power (VA)**: Apparent power of named outlet - Outlet NAME real power (W): Real power of na...
(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~115-~115: This phrase is duplicated. You should probably use “Ambient temperature” only once.
Context: ...holds - Ambient temperature (°C)*: Ambient temperature - Ambient temperature status*: Ambient temperature status ...
(PHRASE_REPETITION)
[grammar] ~116-~116: Check that the noun ‘thresholds’ after the pronoun ‘he’ is correct. You may need to use a different part of speech, or use ‘the’ instead.
Context: ...mbient temperature status relative to t he thresholds - Apparent power (VA): Current valu...
(PRP_VB)
[duplication] ~170-~170: Possible typo: you repeated a word.
Context: ... Interval to wait before restarting the load - Load shutdown timer (secs): Time before th...
(ENGLISH_WORD_REPEAT_RULE)
[typographical] ~175-~175: Make sure that the comma (,) is correct. Do not use a comma before a dependent clause that starts with ‘that’.
Context: ...y voltage (V)**: Minimum battery voltage, that triggers FSD status - **Low voltage tra...
(COMMA_THAT_NOUN)
[duplication] ~218-~218: Possible typo: you repeated a word.
Context: ...: Interval to wait before rebooting the UPS - UPS shutdown delay (secs): Interval to wa...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (7)
source/_integrations/nut.markdown (7)
50-57: Add "Supported functionality" SectionThe new section clearly outlines the integration’s capabilities with an informative note block. The formatting is consistent with Home Assistant documentation standards and replaces the removed section appropriately.
58-61: Introduce "Sensors" SubsectionThe "Sensors" subsection is introduced clearly with a brief description that sets the context for the following sensor list. The content is succinct and meets the documentation objectives.
62-76: Organized Sensor ListThe sensors are presented in a bullet list that appears to be in alphabetical order, which aligns with the PR objective to organize them by name. The relationship between the virtual "Status" and its corresponding "Status data" sensor is also clearly explained.
🧰 Tools
🪛 LanguageTool
[duplication] ~68-~68: Possible typo: you repeated a word.
Context: ...nt - Input load (%): Load on (ePDU) input - Input voltage (V): Input voltage - **Load (...(ENGLISH_WORD_REPEAT_RULE)
80-87: Outlet Sensor DetailsThe outlet sensors use "Outlet NAME" as a placeholder effectively, indicating that these items are dynamically created based on configuration. This approach is clear and user friendly.
🧰 Tools
🪛 LanguageTool
[duplication] ~83-~83: Possible typo: you repeated a word.
Context: ...et NAME current (A)**: Current of named outlet - Outlet NAME description: Description of name...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~84-~84: Possible typo: you repeated a word.
Context: ...AME description**: Description of named outlet - Outlet NAME power (VA): Apparent power of na...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~85-~85: Possible typo: you repeated a word.
Context: ...E power (VA)**: Apparent power of named outlet - Outlet NAME real power (W): Real power of na...(ENGLISH_WORD_REPEAT_RULE)
88-91: Additional Information with Documentation LinkThis note provides a helpful link to official variable names documentation, enhancing user understanding regarding the available sensor values. The reference is clear and well integrated.
105-109: Diagnostic Sensor Value NoteThe note block explaining manufacturer-specific ("opaque by mfg") sensor values is concise and helpful. It clearly informs users about potential variations, which is important for troubleshooting.
226-229: Outlet Diagnostic SensorsThe additional diagnostic sensor for individually monitored outlets is separated into its own section. The use of the "Outlet NAME" placeholder continues to clearly signal dynamically generated sensor names, which maintains consistency with the rest of the documentation.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
source/_integrations/nut.markdown (3)
58-91: Sensors Subsection Enhancement
This subsection provides a comprehensive list of available sensors. A couple of minor improvements to consider:
- For Input load (%) (line 68), the phrase "Load on (ePDU) input" may be refined to avoid any ambiguity for some readers.
- In the outlet sensor entries (lines 83–86), the repeated use of "named outlet" could be streamlined—for example, by rephrasing to "Current measured" and "Outlet description" to reduce redundancy.
🧰 Tools
🪛 LanguageTool
[duplication] ~68-~68: Possible typo: you repeated a word.
Context: ...nt - Input load (%): Load on (ePDU) input - Input voltage (V): Input voltage - **Load (...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~83-~83: Possible typo: you repeated a word.
Context: ...et NAME current (A)**: Current of named outlet - Outlet NAME description: Description of name...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~84-~84: Possible typo: you repeated a word.
Context: ...AME description**: Description of named outlet - Outlet NAME power (VA): Apparent power of na...(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~85-~85: Possible typo: you repeated a word.
Context: ...E power (VA)**: Apparent power of named outlet - Outlet NAME real power (W): Real power of na...(ENGLISH_WORD_REPEAT_RULE)
113-116: Ambient Temperature Sensor Descriptions
The descriptions for Ambient temperature (°C) and Ambient temperature status are clear but a bit repetitive. Consider rephrasing them to, for example, "Measured ambient temperature" and "Temperature status relative to thresholds" to tighten the language.🧰 Tools
🪛 LanguageTool
[grammar] ~115-~115: This phrase is duplicated. You should probably use “Ambient temperature” only once.
Context: ...holds - Ambient temperature (°C)*: Ambient temperature - Ambient temperature status*: Ambient temperature status ...(PHRASE_REPETITION)
168-171: Refine Delay Sensor Wording
For sensors such as Load restart delay (secs) (line 169) and UPS reboot delay (secs) (line 217), the descriptive phrasing ("Interval to wait before…") is a bit redundant when paired with the sensor names. A more concise wording (e.g., "Time before restart" or "Reboot wait time") could improve clarity.Also applies to: 217-218
🧰 Tools
🪛 LanguageTool
[duplication] ~169-~169: Possible typo: you repeated a word.
Context: ... Interval to wait before restarting the load - Load shutdown timer (secs): Time before th...(ENGLISH_WORD_REPEAT_RULE)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
source/_integrations/nut.markdown(1 hunks)
🧰 Additional context used
🪛 LanguageTool
source/_integrations/nut.markdown
[duplication] ~68-~68: Possible typo: you repeated a word.
Context: ...nt - Input load (%): Load on (ePDU) input - Input voltage (V): Input voltage - **Load (...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~83-~83: Possible typo: you repeated a word.
Context: ...et NAME current (A)**: Current of named outlet - Outlet NAME description: Description of name...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~84-~84: Possible typo: you repeated a word.
Context: ...AME description**: Description of named outlet - Outlet NAME power (VA): Apparent power of na...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~85-~85: Possible typo: you repeated a word.
Context: ...E power (VA)**: Apparent power of named outlet - Outlet NAME real power (W): Real power of na...
(ENGLISH_WORD_REPEAT_RULE)
[grammar] ~115-~115: This phrase is duplicated. You should probably use “Ambient temperature” only once.
Context: ...holds - Ambient temperature (°C)*: Ambient temperature - Ambient temperature status*: Ambient temperature status ...
(PHRASE_REPETITION)
[duplication] ~169-~169: Possible typo: you repeated a word.
Context: ... Interval to wait before restarting the load - Load shutdown timer (secs): Time before th...
(ENGLISH_WORD_REPEAT_RULE)
[duplication] ~217-~217: Possible typo: you repeated a word.
Context: ...: Interval to wait before rebooting the UPS - UPS shutdown delay (secs): Interval to wa...
(ENGLISH_WORD_REPEAT_RULE)
🔇 Additional comments (4)
source/_integrations/nut.markdown (4)
50-51: New Section Addition: "Supported functionality"
The addition of the "Supported functionality" section clearly groups sensor-related details for the NUT integration, enhancing the overall organization and readability of the documentation.
52-56: Note Block Clarity
The note block explains that the integration only adds sensors available on your device via the NUT protocol. It’s concise and informative.
92-110: Diagnostic Sensors Section Structure
The "Diagnostic sensors" section is well organized. The note blocks clearly state that most diagnostic sensors are disabled by default and explain the manufacturer-specific ("opaque by mfg") values, which is very helpful for users.
290-295: Overall Documentation Consistency
The updated documentation overall adheres well to Home Assistant’s standards. The segmentation into supported devices, functionality, sensor categories, and diagnostic sensors is logical. Please verify that the ordering (alphabetically or by grouping) of sensor entries aligns with both the official NUT documentation and Home Assistant’s guidelines.
Proposed change
The current instructions for NUT do not generally define the sensors or diagnostic sensors. Add a new "Supported functionality" section and sub-sections for both "Sensors" and "Diagnostic sensors". Create lists of all available sensors including the name, units (if specified) and a brief description. Use the NUT documentation as the brief description as much as possible to avoid confusing users, though those descriptions are not always the most helpful.
Move and rewrite the special "Status" virtual sensor description for easier readability.
Dynamically created sensors per outlet are listed separately since the name is based on the end user's configuration. Provide a link to the official NUT document describing variable names.
For diagnostic sensors, explain that most sensors are disabled by default and provide a link to instructions for enabling a sensor. Use same terminology for consistency with NUT documentation. Include a note regarding "opaque by mfg" used in the NUT documentation.
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.nextbranch.Summary by CodeRabbit
Summary by CodeRabbit