diff --git a/components/mcp230xx.rst b/components/mcp230xx.rst index 27564f6e0..23e80cb21 100644 --- a/components/mcp230xx.rst +++ b/components/mcp230xx.rst @@ -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 ` - +- **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 ` @@ -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. diff --git a/components/pcf8574.rst b/components/pcf8574.rst index 199455c22..f4a94b42b 100644 --- a/components/pcf8574.rst +++ b/components/pcf8574.rst @@ -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 -------- diff --git a/components/sn74hc595.rst b/components/sn74hc595.rst index 0bae6b13c..787c9aa5b 100644 --- a/components/sn74hc595.rst +++ b/components/sn74hc595.rst @@ -52,11 +52,21 @@ Configuration variables: - **oe_pin** (*Optional*, :ref:`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 ` +- `Serial to Parallel Shifting-Out with a 74HC595 `__ - :apiref:`sn74hc595/sn74hc595.h` - :ghedit:`Edit` diff --git a/components/sx1509.rst b/components/sx1509.rst index 32b563376..0da937534 100644 --- a/components/sx1509.rst +++ b/components/sx1509.rst @@ -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 `. + +- **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). diff --git a/schema_doc.py b/schema_doc.py index fc3f9c54f..2a1322e39 100644 --- a/schema_doc.py +++ b/schema_doc.py @@ -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