Upstream/esphome-docs
1
0
Fork 0
mirror of https://github.com/esphome/esphome-docs.git synced 2025-02-23 02:51:38 +01:00
Code Issues Projects Releases Wiki Activity

pin schema and other fixes (#1047)

Browse Source
This commit is contained in:
Guillermo Ruffino 2021-03-08 22:53:04 -03:00 committed by GitHub
parent 234810e6f5
commit 979e0a2d57
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 86 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
components/mcp230xx.rst
View File

@ -61,13 +61,15 @@ Configuration variables:
Useful when the MCP23008's power supply is greater than 3.3 volts. Note that this pin
will require a pull-up resistor (to 3.3 volts) when this mode is enabled.
Pin Configuration Variables:
Pin configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **mcp23xxx** (**Required**, :ref:`config-id`): The id of the MCP23008 component.
- **interrupt** (*Optional*): Set this pin to trigger the INT pin on the component. Can be one of ``CHANGE``, ``RISING``, ``FALLING``.
- All other options from :ref:`Pin Schema <config-pin_schema>`
- **number** (**Required**, integer): The pin number.
- **inverted** (*Optional*, boolean): If all read and written values
should be treated as inverted. Defaults to ``False``.
- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``.
.. _mcp23016-label:
@ -118,10 +120,10 @@ Configuration variables:
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x20``.
Pin Configuration Variables:
Pin configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **mcp23016** (**Required**, :ref:`config-id`): The id of the MCP23016 component.
- **mcp23xxx** (**Required**, :ref:`config-id`): The id of the MCP23016 component.
- All other options from :ref:`Pin Schema <config-pin_schema>`
@ -180,7 +182,7 @@ Configuration variables:
Useful when the MCP23017's power supply is greater than 3.3 volts. Note that these pins
will require pull-up resistors (to 3.3 volts) when this mode is enabled.
Pin Configuration Variables:
Pin configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **mcp23xxx** (**Required**, :ref:`config-id`): The id of the MCP23017 component.

13
components/pcf8574.rst
View File

@ -47,13 +47,24 @@ not work.
inverted: False
Configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~
************************
- **id** (**Required**, :ref:`config-id`): The id to use for this PCF8574 component.
- **address** (*Optional*, int): The I²C address of the driver.
Defaults to ``0x21``.
- **pcf8575** (*Optional*, boolean): Whether this is a 16-pin PCF8575. Defaults to ``False``.
Pin configuration variables:
****************************
- **pcf8574** (**Required**, :ref:`config-id`): The id of the PCF8574 component of the pin.
- **number** (**Required**, integer): The pin number.
- **inverted** (*Optional*, boolean): If all read and written values
should be treated as inverted. Defaults to ``False``.
- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``.
See Also
--------

12
components/sn74hc595.rst
View File

@ -52,11 +52,21 @@ Configuration variables:
- **oe_pin** (*Optional*, :ref:`Pin Schema <config-pin_schema>`): Pin connected to SN74HC595 OE pin
- **sr_count** (*Optional*, int): Number of daisy-chained shift registers, up-to 4. Defaults to ``1``.
Pin configuration variables:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- **sn74hc595** (**Required**, :ref:`config-id`): The id of the SN74HC595 component of the pin.
- **number** (**Required**, integer): The pin number.
- **inverted** (*Optional*, boolean): If all written values should be treated as inverted.
Defaults to ``False``.
See Also
--------
- :doc:`switch/gpio`
- :doc:`binary_sensor/gpio`
- `Serial to Parallel Shifting-Out with a 74HC595 <https://www.arduino.cc/en/tutorial/ShiftOut>`
- `Serial to Parallel Shifting-Out with a 74HC595 <https://www.arduino.cc/en/tutorial/ShiftOut>`__
- :apiref:`sn74hc595/sn74hc595.h`
- :ghedit:`Edit`

15
components/sx1509.rst
View File

@ -109,7 +109,7 @@ Attention should be paid to the capabilities of the I/O pins.
+-----+------------------+-----+--------+
Binary Sensor
-------------
=============
To use the individual keys on the keypad you need to add individual binary_sensor entries in the config.
@ -134,6 +134,10 @@ Configuration variables:
- **row** (**Required**, int): The row number for this key on the keypad.
- **col** (**Required**, int): The column number for this key on the keypad.
Pin configuration variables:
----------------------------
With the following configuration items you may use the individual pins of the SX1509 as the pins for binary_sensor, switch, or output.
The outputs can in turn be used to add PWM-enabled lights like the monochromatic light.
@ -177,7 +181,14 @@ The outputs can in turn be used to add PWM-enabled lights like the monochromatic
name: "light0"
output: sx1509_output
- All other options from :ref:`Output <config-output>`.
- **sx1509** (**Required**, :ref:`config-id`): The id of the SX1509 component of the pin.
- **number** (**Required**, integer): The pin number.
- **inverted** (*Optional*, boolean): If all read and written values
should be treated as inverted. Defaults to ``False``.
- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT``,
``INPUT_PULLUP`` or ``OUTPUT``.
And naturally you may use all automation functions with these SX1509 binary_sensors, switches and output (lights).

62
schema_doc.py
View File

@ -8,6 +8,7 @@ from docutils import nodes
SCHEMA_PATH = "../esphome_devices/schema.json"
CONFIGURATION_VARIABLES = "Configuration variables:"
PIN_CONFIGURATION_VARIABLES = "Pin configuration variables:"
COMPONENT_HUB = "Component/Hub"
props_missing = 0
@ -77,7 +78,10 @@ CUSTOM_DOCS = {
"guides/automations": {"Global Variables": "properties/globals"},
"guides/configuration-types": {
"Color": "properties/color",
"Pin Schema": "definitions/PIN.GPIO_FULL_INPUT_PIN_SCHEMA",
"Pin Schema": [
"definitions/PIN.INPUT_INTERNAL",
"definitions/PIN.OUTPUT_INTERNAL",
],
},
"components/climate/ir_climate": {
"IR Remote Climate": [
@ -111,6 +115,12 @@ CUSTOM_DOCS = {
"Clockless": "properties/light/fastled_clockless",
"SPI": "properties/light/fastled_spi",
},
"components/mcp230xx": {
PIN_CONFIGURATION_VARIABLES: [
"definitions/PIN.INPUT_mcp23xxx",
"definitions/PIN.OUTPUT_mcp23xxx",
]
},
"components/mqtt": {
"MQTT Component Base Configuration": "definitions/CONFIG.MQTT_COMMAND_COMPONENT_SCHEMA",
},
@ -220,6 +230,8 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
# this is empty, not much to do
raise nodes.SkipChildren
self.props_section_title = list(node.traverse(nodes.title))[0].astext()
# Document first paragraph is description of this thing
description = self.getMarkdownParagraph(node)
@ -280,15 +292,14 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
def visit_title(self, node):
title_text = node.astext()
if self.props_section_title is None:
self.props_section_title = title_text
if "interval" in title_text:
title_text = title_text
if self.custom_doc is not None and title_text in self.custom_doc:
if isinstance(self.custom_doc[title_text], list):
self.multi_component = self.custom_doc[title_text]
self.filled_props = False
self.props = None
# TODO: add same markdown description to each?
return
@ -319,7 +330,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
if title_text == CONFIGURATION_VARIABLES:
if not self.props and self.multi_component is None:
raise ValueError(
f"Found a Configuration variables: title after {self.previous_title_text}. Unkown object."
f'Found a "{CONFIGURATION_VARIABLES}": title after {self.previous_title_text}. Unkown object.'
)
if title_text == "Over SPI" or title_text == "Over I²C":
@ -419,6 +430,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
self.json_component = c
try:
self.props = self.find_props(self.json_component)
self.multi_component = None
except KeyError:
raise ValueError(
"Cannot find props for component " + component_name
@ -491,6 +503,20 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
return
raise ValueError("Cannot find Effect " + title_text)
if title_text == PIN_CONFIGURATION_VARIABLES:
self.multi_component = []
if self.app.jschema["definitions"].get(f"PIN.INPUT_{self.path[-1]}"):
self.multi_component.append(f"definitions/PIN.INPUT_{self.path[-1]}")
if self.app.jschema["definitions"].get(f"PIN.OUTPUT_{self.path[-1]}"):
self.multi_component.append(f"definitions/PIN.OUTPUT_{self.path[-1]}")
self.accept_props = True
self.filled_props = False
self.props = None
if len(self.multi_component) == 0:
raise ValueError(
f'Found a "{PIN_CONFIGURATION_VARIABLES}" entry but could not find pin schema'
)
def depart_title(self, node):
if self.filled_props:
self.filled_props = False
@ -517,28 +543,30 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
def visit_Text(self, node):
if self.multi_component:
return
if node.astext() == "Configuration variables:":
if node.astext() == CONFIGURATION_VARIABLES:
if not self.props:
self.find_props_previous_title()
if not self.props:
raise ValueError(
f'Found a "Configuration variables:" entry for unknown object after {self.previous_title_text}'
f'Found a "{CONFIGURATION_VARIABLES}" entry for unknown object after {self.previous_title_text}'
)
self.accept_props = True
raise nodes.SkipChildren
def depart_Text(self, node):
pass
def visit_paragraph(self, node):
if node.astext() == "Configuration variables:":
if not self.props:
if node.astext() == CONFIGURATION_VARIABLES:
if not self.props and not self.multi_component:
self.find_props_previous_title()
if not self.props:
if not self.props and not self.multi_component:
raise ValueError(
f'Found a "Configuration variables:" entry for unknown object after {self.previous_title_text}'
f'Found a "{CONFIGURATION_VARIABLES}" entry for unknown object after {self.previous_title_text}'
)
self.accept_props = True
raise nodes.SkipChildren
def depart_paragraph(self, node):
@ -602,8 +630,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
self.filled_props = True
try:
self.current_prop = self.update_prop(node, self.props)
# print(
# f'{self.current_prop} updated from {node.rawsource[:40]}')
except Exception as e:
raise ValueError(f"In '{self.previous_title_text}' {str(e)}")
@ -700,9 +726,8 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
k = str(prop_name)
jprop = props.get(k)
if not jprop:
# do not fail for common properties,
# however this should check prop is valid upstream
# Create docs for common properties when descriptions are overriden
# in the most specific component.
if k in [
"id",
@ -734,7 +759,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
# climate
"receiver_id",
]:
return
jprop = props[k] = {}
else:
raise ValueError(f"Cannot find property {k}")
@ -742,9 +767,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor):
if param_type:
desc = param_type + ": " + desc
# if '$ref' in jprop:
# self.get_ref(jprop)["markdownDescription"] = desc
# else:
jprop["markdownDescription"] = desc
global props_documented
props_documented = props_documented + 1