From fd053fa0663025faba3c2865a6e36635613006b0 Mon Sep 17 00:00:00 2001 From: Seth Fischer Date: Mon, 17 Jun 2024 20:40:16 +1200 Subject: [PATCH] docs: vmc daughter board directed graph --- .github/workflows/build.yml | 5 + .github/workflows/linkcheck.yml | 5 + .readthedocs.yaml | 2 + docs/conf.py | 4 + docs/index.rst | 2 +- docs/reference/vmc-header.rst | 10 - docs/reference/vmc-interfaces.dot | 155 +++++++++ docs/reference/vmc-interfaces.rst | 17 + src/osr_elec/pinout/vmc_header/data.py | 377 +++++++++++----------- src/osr_elec/pinout/vmc_header/diagram.py | 5 +- src/osr_elec/pinout/vmc_header/styles.css | 12 + 11 files changed, 396 insertions(+), 198 deletions(-) delete mode 100644 docs/reference/vmc-header.rst create mode 100644 docs/reference/vmc-interfaces.dot create mode 100644 docs/reference/vmc-interfaces.rst diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6d782f2..2773eb3 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -19,6 +19,11 @@ jobs: with: python-version: "3.11" + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y graphviz + - name: Install Poetry run: | curl -sSL https://install.python-poetry.org | python3 - diff --git a/.github/workflows/linkcheck.yml b/.github/workflows/linkcheck.yml index a7d83bd..da796b3 100644 --- a/.github/workflows/linkcheck.yml +++ b/.github/workflows/linkcheck.yml @@ -16,6 +16,11 @@ jobs: with: python-version: "3.11" + - name: Install system dependencies + run: | + sudo apt-get update + sudo apt-get install -y graphviz + - name: Install Poetry run: | curl -sSL https://install.python-poetry.org | python3 - diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 6088174..20ed3a6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -4,6 +4,8 @@ build: os: ubuntu-20.04 tools: python: "3.11" + apt_packages: + - graphviz jobs: post_checkout: - git fetch --unshallow || true diff --git a/docs/conf.py b/docs/conf.py index 735226b..ec989ce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -23,6 +23,7 @@ def canonical_url() -> str: exclude_patterns = ["_build"] extensions = [ "osr_sphinx", + "sphinx.ext.graphviz", "sphinx_argparse_cli", "sphinx_design", "sphinx_rtd_theme", @@ -68,6 +69,9 @@ def canonical_url() -> str: cadquery_include_source = False +graphviz_output_format = "svg" + + ogp_image = "_static/og-image-main.png" ogp_site_url = canonical_url() ogp_social_cards = { diff --git a/docs/index.rst b/docs/index.rst index 8e22d5d..96690d3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -113,7 +113,7 @@ Specifications :maxdepth: 1 :hidden: - reference/vmc-header + reference/vmc-interfaces .. toctree:: :caption: End matter diff --git a/docs/reference/vmc-header.rst b/docs/reference/vmc-header.rst deleted file mode 100644 index 6c4d560..0000000 --- a/docs/reference/vmc-header.rst +++ /dev/null @@ -1,10 +0,0 @@ -================================== -Vehicle management computer pinout -================================== - -GPIO configuration ------------------- - -.. osr:pinout-diagram:: vmc_header - - Raspberry Pi header interface configuration and peripheral connection. diff --git a/docs/reference/vmc-interfaces.dot b/docs/reference/vmc-interfaces.dot new file mode 100644 index 0000000..539764b --- /dev/null +++ b/docs/reference/vmc-interfaces.dot @@ -0,0 +1,155 @@ +digraph spi_to_uart { + rankdir="LR" + splines=ortho + node [ + shape=rect + style=filled + fillcolor="#FFFFFFFF" + ] + + // SPI + spi0 [ + label="SPI0" + tooltip="Pins 19, 21, 23, 24, and 26." + fillcolor="#B645B0FF" + width=0.9 + height=3 + ] + ce0 [ + label="CE0" + tooltip="Pin 24." + fillcolor="#B645B0FF" + height=1.2 + ] + ce1 [ + label="CE1" + tooltip="Pin 26." + fillcolor="#B645B0FF" + height=1.2 + ] + spi_to_uart [ + label="SPI to UART\nconverter" + tooltip="SPI to UART converter." + fillcolor="#50C878FF" + height=0.8 + ] + spi_to_can [ + label="SPI to CAN\nconverter" + tooltip="SPI to CAN converter." + fillcolor="#50C878FF" + height=0.8 + ] + can [ + label="CAN" + tooltip="Controller Area Network." + fillcolor="#E6570AFF" + width=0.9 + ] + uart_a [ + label="UART A" + tooltip="UART A." + fillcolor="#E6570AFF" + width=0.9 + ] + uart_b [ + label="UART B" + tooltip="UART B (RS-485)." + ] + rs_485 [ + label="RS-485" + tooltip="RS-485." + fillcolor="#E6570AFF" + width=0.9 + ] + spi0 -> ce0 + spi0 -> ce1 + ce0 -> spi_to_uart [ label="SPI0 CE0" ] + ce1 -> spi_to_can [ label="SPI0 CE1" ] + spi_to_can -> can [ label="CAN TTL" ] + spi_to_uart -> uart_a [ label="UART" ] + spi_to_uart -> uart_b [ label="UART" ] + uart_b -> rs_485 + + // robot signal light + gpio17 [ + label="GPIO17" + tooltip="Pin 11." + fillcolor="#B645B0FF" + ] + low_side_switch [ + label="Low-side switch" + tooltip="Low-side switch." + ] + rsl [ + label="RSL" + tooltip="Robot signal light LED and header." + fillcolor="#E6570AFF" + width=0.9 + ] + gpio17 -> low_side_switch [ label="Digital out" ] + low_side_switch -> rsl + + // I2C header + i2c_out [ + label="I2C" + tooltip="Five pin header with Pimoroni Breakout Garden pinout." + fillcolor="#E6570AFF" + width=0.9 + height=2 + ] + i2c1_in [ + label="I2C1" + tooltip="Pins 3 and 5." + fillcolor="#B645B0FF" + width=0.9 + height=1 + ] + gpio4 [ + label="GPIO4" + tooltip="Pin 7." + fillcolor="#B645B0FF" + width=0.9 + ] + i2c1_in -> i2c_out [ label="SDA" ] + i2c1_in -> i2c_out [ label="SCL" ] + gpio4 -> i2c_out [ label="Digital out" ] + + // UART header + uart_in [ + label="UART" + tooltip="Pins 8 and 10." + fillcolor="#B645B0FF" + width=0.9 + height=1 + ] + uart_out [ + label="UART" + tooltip="UART header." + fillcolor="#E6570AFF" + width=0.9 + height=1 + ] + uart_in -> uart_out [ label="TXD" ] + uart_in -> uart_out [ label="RXD" ] + + // ID EEPROM + i2c_id [ + label="I2C ID" + tooltip="I2C ID." + fillcolor="#B645B0FF" + width=0.9 + ] + id_eeprom [ + label="ID EEPROM" + tooltip="Pins 27 and 28." + width=0.9 + ] + i2c_id -> id_eeprom [ label="SDA" ] + i2c_id -> id_eeprom [ label="SCL" ] + + + {rank = same; spi0 gpio17 i2c1_in gpio4 uart_in} + {rank = same; ce0 ce1} + {rank = same; spi_to_uart spi_to_can} + {rank = same; uart_a rs_485 can rsl i2c_out uart_out} +} diff --git a/docs/reference/vmc-interfaces.rst b/docs/reference/vmc-interfaces.rst new file mode 100644 index 0000000..ba9da63 --- /dev/null +++ b/docs/reference/vmc-interfaces.rst @@ -0,0 +1,17 @@ +====================================== +Vehicle management computer interfaces +====================================== + +GPIO configuration +------------------ + +.. osr:pinout-diagram:: vmc_header + + Raspberry Pi header interface configuration and peripheral connection. + + +Interfaces and peripherals +-------------------------- + +.. graphviz:: vmc-interfaces.dot + :caption: Raspberry Pi HAT interfaces and peripherals diff --git a/src/osr_elec/pinout/vmc_header/data.py b/src/osr_elec/pinout/vmc_header/data.py index 277f380..020ffee 100644 --- a/src/osr_elec/pinout/vmc_header/data.py +++ b/src/osr_elec/pinout/vmc_header/data.py @@ -1,185 +1,192 @@ -"""Data for Vehicle Management Computer GPIO header pinout diagram.""" - -legend = [ - ("Pin №", "pin"), - ("Power 5V", "pwr5v"), - ("Power 3V3", "pwr3v3"), - ("Ground", "gnd"), - ("Interface", "interface"), - ("Peripheral", "peri"), - ("No connection", "nc"), -] - -pin_body = {"body": {"width": 40}} -peripheral_body = {"body": {"width": 100}} - -odd_pins = [ - [ - ("1", "pin", pin_body), - ("3V3", "pwr3v3"), - ], - [ - ("3", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("5", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("7", "pin", pin_body), - ("GPIO4 DO", "interface"), - ("RSL", "peri", peripheral_body), - ], - [ - ("9", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("11", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("13", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("15", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("17", "pin", pin_body), - ("3V3", "pwr3v3"), - ], - [ - ("19", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("21", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("23", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("25", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("27", "pin", pin_body), - ("I2C ID_SD", "interface"), - ("ID EEPROM", "peri", peripheral_body), - ], - [ - ("29", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("31", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("33", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("35", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("37", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("39", "pin", pin_body), - ("GND", "gnd"), - ], -] - -even_pins = [ - [ - ("2", "pin", pin_body), - ("5V", "pwr5v"), - ], - [ - ("4", "pin", pin_body), - ("5V", "pwr5v"), - ], - [ - ("6", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("8", "pin", pin_body), - ("UART TXD", "interface"), - ("UART", "peri", peripheral_body), - ], - [ - ("10", "pin", pin_body), - ("UART RXD", "interface"), - ("UART", "peri", peripheral_body), - ], - [ - ("12", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("14", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("16", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("18", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("20", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("22", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("24", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("26", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("28", "pin", pin_body), - ("I2C ID_SC", "interface"), - ("ID EEPROM", "peri", peripheral_body), - ], - [ - ("30", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("32", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("34", "pin", pin_body), - ("GND", "gnd"), - ], - [ - ("36", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("38", "pin", pin_body), - ("NC", "nc"), - ], - [ - ("40", "pin", pin_body), - ("NC", "nc"), - ], -] +"""Data for Vehicle Management Computer GPIO header pinout diagram.""" + +legend = [ + ("Pin №", "pin"), + ("Power 5V", "pwr5v"), + ("Power 3V3", "pwr3v3"), + ("Ground", "gnd"), + ("Interface", "interface"), + ("Peripheral", "peri"), + ("Protocol converter", "proconv"), + ("No connection", "nc"), +] + +pin_body = {"body": {"width": 40}} +interface_body = {"body": {"width": 100}} +peripheral_body = {"body": {"width": 100}} + +odd_pins = [ + [ + ("1", "pin", pin_body), + ("3V3", "pwr3v3", interface_body), + ], + [ + ("3", "pin", pin_body), + ("I2C1 SDA", "interface", interface_body), + ("I2C header", "peri", peripheral_body), + ], + [ + ("5", "pin", pin_body), + ("I2C1 SCL", "interface", interface_body), + ("I2C header", "peri", peripheral_body), + ], + [ + ("7", "pin", pin_body), + ("GPIO4 DO", "interface", interface_body), + ("I2C header", "peri", peripheral_body), + ], + [ + ("9", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("11", "pin", pin_body), + ("GPIO17 DO", "interface", interface_body), + ("RSL", "peri", peripheral_body), + ], + [ + ("13", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("15", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("17", "pin", pin_body), + ("3V3", "pwr3v3", interface_body), + ], + [ + ("19", "pin", pin_body), + ("SPI0 MOSI", "interface", interface_body), + ], + [ + ("21", "pin", pin_body), + ("SPI0 MISO", "interface", interface_body), + ], + [ + ("23", "pin", pin_body), + ("SPI0 SCLK", "interface", interface_body), + ], + [ + ("25", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("27", "pin", pin_body), + ("I2C ID_SD", "interface", interface_body), + ("ID EEPROM", "peri", peripheral_body), + ], + [ + ("29", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("31", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("33", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("35", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("37", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("39", "pin", pin_body), + ("GND", "gnd", interface_body), + ], +] + +even_pins = [ + [ + ("2", "pin", pin_body), + ("5V", "pwr5v", interface_body), + ], + [ + ("4", "pin", pin_body), + ("5V", "pwr5v", interface_body), + ], + [ + ("6", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("8", "pin", pin_body), + ("UART TXD", "interface", interface_body), + ("UART", "peri", peripheral_body), + ], + [ + ("10", "pin", pin_body), + ("UART RXD", "interface", interface_body), + ("UART", "peri", peripheral_body), + ], + [ + ("12", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("14", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("16", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("18", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("20", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("22", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("24", "pin", pin_body), + ("SPI0 CE0", "interface", interface_body), + ("UART{A,B}", "proconv", peripheral_body), + ], + [ + ("26", "pin", pin_body), + ("SPI0 CE1", "interface", interface_body), + ("CAN", "proconv", peripheral_body), + ], + [ + ("28", "pin", pin_body), + ("I2C ID_SC", "interface", interface_body), + ("ID EEPROM", "peri", peripheral_body), + ], + [ + ("30", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("32", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("34", "pin", pin_body), + ("GND", "gnd", interface_body), + ], + [ + ("36", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("38", "pin", pin_body), + ("NC", "nc", interface_body), + ], + [ + ("40", "pin", pin_body), + ("NC", "nc", interface_body), + ], +] diff --git a/src/osr_elec/pinout/vmc_header/diagram.py b/src/osr_elec/pinout/vmc_header/diagram.py index 8a4bb57..3fdec63 100644 --- a/src/osr_elec/pinout/vmc_header/diagram.py +++ b/src/osr_elec/pinout/vmc_header/diagram.py @@ -8,14 +8,15 @@ # this is a collection of definition files rather than a Python module import data # type: ignore[import-not-found] # isort: skip -diagram = Diagram_2Rows(685, 730, 650, "diagram") +diagram = Diagram_2Rows(710, 730, 650, "diagram") diagram.add_stylesheet("styles.css", embed=True) -graphic = diagram.panel_01.add(Group(310, 30)) +graphic = diagram.panel_01.add(Group(322, 30)) hardware = graphic.add(Image("pin-header-2x20-p2.54mm-vertical.svg", embed=True)) hardware.add_coord("pin_1", 60, 15) hardware.add_coord("pin_2", 0, 15) +hardware.add_coord("spi_to_uart", 60, 0) hardware.add_coord("pin_pitch_v", 0, 30) hardware.add_coord("pin_pitch_h", 30, 0) diff --git a/src/osr_elec/pinout/vmc_header/styles.css b/src/osr_elec/pinout/vmc_header/styles.css index 9aa6c50..d01866f 100644 --- a/src/osr_elec/pinout/vmc_header/styles.css +++ b/src/osr_elec/pinout/vmc_header/styles.css @@ -105,6 +105,18 @@ text { fill: rgb(230, 87, 10); } +.proconv .pinlabel__body { + fill: rgb(80, 200, 120); +} + +.proconv .pinlabel__leader { + stroke: rgb(80, 200, 120); +} + +.proconv .swatch__body { + fill: rgb(80, 200, 120); +} + .panel__inner { fill: #fff; }