From 0b57c8ff2f9a82801e2e086af91397d5299ccbf5 Mon Sep 17 00:00:00 2001
From: Seth Fischer <seth@fischer.nz>
Date: Fri, 19 Apr 2024 21:43:35 +1200
Subject: [PATCH] docs: vmc pinout diagram

---
 .editorconfig                                 |   3 +
 docs/index.rst                                |   7 +
 docs/reference/vmc-header.rst                 |  10 +
 pyproject.toml                                |   3 +-
 src/osr_elec/__init__.py                      |   1 +
 src/osr_elec/pinout/__init__.py               |   1 +
 src/osr_elec/pinout/vmc_header/__init__.py    |   1 +
 src/osr_elec/pinout/vmc_header/data.py        | 185 ++++++++++++++++++
 src/osr_elec/pinout/vmc_header/diagram.py     |  54 +++++
 .../pin-header-2x20-p2.54mm-vertical.svg      |  54 +++++
 src/osr_elec/pinout/vmc_header/styles.css     | 110 +++++++++++
 11 files changed, 428 insertions(+), 1 deletion(-)
 create mode 100644 docs/reference/vmc-header.rst
 create mode 100644 src/osr_elec/__init__.py
 create mode 100644 src/osr_elec/pinout/__init__.py
 create mode 100644 src/osr_elec/pinout/vmc_header/__init__.py
 create mode 100644 src/osr_elec/pinout/vmc_header/data.py
 create mode 100644 src/osr_elec/pinout/vmc_header/diagram.py
 create mode 100644 src/osr_elec/pinout/vmc_header/pin-header-2x20-p2.54mm-vertical.svg
 create mode 100644 src/osr_elec/pinout/vmc_header/styles.css

diff --git a/.editorconfig b/.editorconfig
index 0e30bb3..05f14bd 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -18,5 +18,8 @@ trim_trailing_whitespace = false
 [*.py]
 max_line_length = 88
 
+[*.svg]
+max_line_length = 120
+
 [Makefile]
 indent_style = tab
diff --git a/docs/index.rst b/docs/index.rst
index 0a08f4c..8e22d5d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -108,6 +108,13 @@ Specifications
 
     bom/parts
 
+.. toctree::
+    :caption: Reference
+    :maxdepth: 1
+    :hidden:
+
+    reference/vmc-header
+
 .. toctree::
     :caption: End matter
     :maxdepth: 1
diff --git a/docs/reference/vmc-header.rst b/docs/reference/vmc-header.rst
new file mode 100644
index 0000000..6c4d560
--- /dev/null
+++ b/docs/reference/vmc-header.rst
@@ -0,0 +1,10 @@
+==================================
+Vehicle management computer pinout
+==================================
+
+GPIO configuration
+------------------
+
+.. osr:pinout-diagram:: vmc_header
+
+    Raspberry Pi header interface configuration and peripheral connection.
diff --git a/pyproject.toml b/pyproject.toml
index 59fbb9d..0feb715 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,6 +4,7 @@ version = "0.1.0"
 description = "Quarter-scale Mars rover based on the NASA Mars 2020 Mission Perseverance Rover"
 packages = [
     {include = "osr_common", from = "src"},
+    {include = "osr_elec", from = "src"},
     {include = "osr_mechanical", from = "src"},
     {include = "osr_sphinx", from = "src"},
     {include = "osr_warehouse", from = "src"},
@@ -108,7 +109,7 @@ ignore_errors = true
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
-module = "pinout.manager"
+module = "pinout.*"
 ignore_missing_imports = true
 
 [[tool.mypy.overrides]]
diff --git a/src/osr_elec/__init__.py b/src/osr_elec/__init__.py
new file mode 100644
index 0000000..fede6c4
--- /dev/null
+++ b/src/osr_elec/__init__.py
@@ -0,0 +1 @@
+"""OSR electrical design."""
diff --git a/src/osr_elec/pinout/__init__.py b/src/osr_elec/pinout/__init__.py
new file mode 100644
index 0000000..403bcfd
--- /dev/null
+++ b/src/osr_elec/pinout/__init__.py
@@ -0,0 +1 @@
+"""OSR pinout diagrams."""
diff --git a/src/osr_elec/pinout/vmc_header/__init__.py b/src/osr_elec/pinout/vmc_header/__init__.py
new file mode 100644
index 0000000..3e75b37
--- /dev/null
+++ b/src/osr_elec/pinout/vmc_header/__init__.py
@@ -0,0 +1 @@
+"""Vehicle Management Computer GPIO header pinout diagram."""
diff --git a/src/osr_elec/pinout/vmc_header/data.py b/src/osr_elec/pinout/vmc_header/data.py
new file mode 100644
index 0000000..277f380
--- /dev/null
+++ b/src/osr_elec/pinout/vmc_header/data.py
@@ -0,0 +1,185 @@
+"""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"),
+    ],
+]
diff --git a/src/osr_elec/pinout/vmc_header/diagram.py b/src/osr_elec/pinout/vmc_header/diagram.py
new file mode 100644
index 0000000..8a4bb57
--- /dev/null
+++ b/src/osr_elec/pinout/vmc_header/diagram.py
@@ -0,0 +1,54 @@
+"""Vehicle Management Computer GPIO header pinout diagram."""
+
+from pinout.components.layout import Diagram_2Rows
+from pinout.components.legend import Legend
+from pinout.components.pinlabel import PinLabelGroup
+from pinout.core import Group, Image
+
+# 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.add_stylesheet("styles.css", embed=True)
+
+graphic = diagram.panel_01.add(Group(310, 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("pin_pitch_v", 0, 30)
+hardware.add_coord("pin_pitch_h", 30, 0)
+
+# labels for even pins
+graphic.add(
+    PinLabelGroup(
+        x=hardware.coord("pin_1").x,
+        y=hardware.coord("pin_1").y,
+        pin_pitch=hardware.coord("pin_pitch_v", raw=True),
+        label_start=(60, 0),
+        label_pitch=(0, 30),
+        labels=data.even_pins,
+    )
+)
+
+# labels for odd pins
+graphic.add(
+    PinLabelGroup(
+        x=hardware.coord("pin_2").x,
+        y=hardware.coord("pin_2").y,
+        pin_pitch=hardware.coord("pin_pitch_v", raw=True),
+        label_start=(60, 0),
+        label_pitch=(0, 30),
+        scale=(-1, 1),
+        labels=data.odd_pins,
+    )
+)
+
+legend = diagram.panel_02.add(
+    Legend(
+        data.legend,
+        x=8,
+        y=8,
+        max_height=80,
+    )
+)
diff --git a/src/osr_elec/pinout/vmc_header/pin-header-2x20-p2.54mm-vertical.svg b/src/osr_elec/pinout/vmc_header/pin-header-2x20-p2.54mm-vertical.svg
new file mode 100644
index 0000000..1f4393f
--- /dev/null
+++ b/src/osr_elec/pinout/vmc_header/pin-header-2x20-p2.54mm-vertical.svg
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE svg PUBLIC '-//W3C//DTD SVG 1.1 Basic//EN' 'http://www.w3.org/Graphics/SVG/1.1/DTD/svg11-basic.dtd'>
+<svg id="svg" width="60px" height="600px" baseProfile="basic" version="1.1"
+     viewBox="0 0 60 600" xmlns="http://www.w3.org/2000/svg"
+     xmlns:xlink="http://www.w3.org/1999/xlink">
+  <defs>
+    <g id="header_pin">
+      <polygon id="body" points="0,6 6,0 24,0 30,6 30,24 24,30 6,30 0,24" fill="#404040" stroke="none"/>
+      <rect id="pin" x="11" y="11" width="8" height="8" fill="#8c8663" stroke="none"/>
+    </g>
+  </defs>
+  <!-- odd pins -->
+  <use id="pin_1" xlink:href="#header_pin" transform="translate(0,0)"/>
+  <use id="pin_3" xlink:href="#header_pin" transform="translate(0,30)"/>
+  <use id="pin_5" xlink:href="#header_pin" transform="translate(0,60)"/>
+  <use id="pin_7" xlink:href="#header_pin" transform="translate(0,90)"/>
+  <use id="pin_9" xlink:href="#header_pin" transform="translate(0,120)"/>
+  <use id="pin_11" xlink:href="#header_pin" transform="translate(0,150)"/>
+  <use id="pin_13" xlink:href="#header_pin" transform="translate(0,180)"/>
+  <use id="pin_15" xlink:href="#header_pin" transform="translate(0,210)"/>
+  <use id="pin_17" xlink:href="#header_pin" transform="translate(0,240)"/>
+  <use id="pin_19" xlink:href="#header_pin" transform="translate(0,270)"/>
+  <use id="pin_21" xlink:href="#header_pin" transform="translate(0,300)"/>
+  <use id="pin_23" xlink:href="#header_pin" transform="translate(0,330)"/>
+  <use id="pin_25" xlink:href="#header_pin" transform="translate(0,360)"/>
+  <use id="pin_27" xlink:href="#header_pin" transform="translate(0,390)"/>
+  <use id="pin_29" xlink:href="#header_pin" transform="translate(0,420)"/>
+  <use id="pin_31" xlink:href="#header_pin" transform="translate(0,450)"/>
+  <use id="pin_33" xlink:href="#header_pin" transform="translate(0,480)"/>
+  <use id="pin_35" xlink:href="#header_pin" transform="translate(0,510)"/>
+  <use id="pin_37" xlink:href="#header_pin" transform="translate(0,540)"/>
+  <use id="pin_39" xlink:href="#header_pin" transform="translate(0,570)"/>
+  <!-- even pins -->
+  <use id="pin_2" xlink:href="#header_pin" transform="translate(30,0)"/>
+  <use id="pin_4" xlink:href="#header_pin" transform="translate(30,30)"/>
+  <use id="pin_6" xlink:href="#header_pin" transform="translate(30,60)"/>
+  <use id="pin_8" xlink:href="#header_pin" transform="translate(30,90)"/>
+  <use id="pin_10" xlink:href="#header_pin" transform="translate(30,120)"/>
+  <use id="pin_12" xlink:href="#header_pin" transform="translate(30,150)"/>
+  <use id="pin_14" xlink:href="#header_pin" transform="translate(30,180)"/>
+  <use id="pin_16" xlink:href="#header_pin" transform="translate(30,210)"/>
+  <use id="pin_18" xlink:href="#header_pin" transform="translate(30,240)"/>
+  <use id="pin_20" xlink:href="#header_pin" transform="translate(30,270)"/>
+  <use id="pin_22" xlink:href="#header_pin" transform="translate(30,300)"/>
+  <use id="pin_24" xlink:href="#header_pin" transform="translate(30,330)"/>
+  <use id="pin_26" xlink:href="#header_pin" transform="translate(30,360)"/>
+  <use id="pin_28" xlink:href="#header_pin" transform="translate(30,390)"/>
+  <use id="pin_30" xlink:href="#header_pin" transform="translate(30,420)"/>
+  <use id="pin_32" xlink:href="#header_pin" transform="translate(30,450)"/>
+  <use id="pin_34" xlink:href="#header_pin" transform="translate(30,480)"/>
+  <use id="pin_36" xlink:href="#header_pin" transform="translate(30,510)"/>
+  <use id="pin_38" xlink:href="#header_pin" transform="translate(30,540)"/>
+  <use id="pin_40" xlink:href="#header_pin" transform="translate(30,570)"/>
+</svg>
diff --git a/src/osr_elec/pinout/vmc_header/styles.css b/src/osr_elec/pinout/vmc_header/styles.css
new file mode 100644
index 0000000..9aa6c50
--- /dev/null
+++ b/src/osr_elec/pinout/vmc_header/styles.css
@@ -0,0 +1,110 @@
+/*
+Styles for VMC GPIO header pinout diagram.
+*/
+
+text {
+    font-family: Verdana, Georgia, sans-serif;
+    font-size: 14px;
+    font-weight: normal;
+}
+
+.pinlabel__leader {
+    stroke-width: 2;
+    fill: none;
+}
+
+.pinlabel__text {
+    dominant-baseline: central;
+    fill: #fff;
+    font-weight: bold;
+    stroke-width: 0;
+    text-anchor: middle;
+}
+
+.pin .pinlabel__body {
+    fill: rgb(128, 128, 128);
+}
+
+.pin .pinlabel__leader {
+    stroke: rgb(128, 128, 128);
+}
+
+.pin .swatch__body {
+    fill: rgb(128, 128, 128);
+}
+
+.nc .swatch__body {
+    fill: rgb(220, 220, 220);
+}
+
+.nc .pinlabel__body {
+    fill: rgb(220, 220, 220);
+}
+
+.nc .pinlabel__leader {
+    stroke: rgb(220, 220, 220);
+}
+
+.pwr5v .pinlabel__body {
+    fill: rgb(173, 0, 0);
+}
+
+.pwr5v .pinlabel__leader {
+    stroke: rgb(173, 0, 0);
+}
+
+.pwr5v .swatch__body {
+    fill: rgb(173, 0, 0);
+}
+
+.pwr3v3 .pinlabel__body {
+    fill: rgb(181, 137, 0);
+}
+
+.pwr3v3 .pinlabel__leader {
+    stroke: rgb(181, 137, 0);
+}
+
+.pwr3v3 .swatch__body {
+    fill: rgb(181, 137, 0);
+}
+
+.gnd .pinlabel__body {
+    fill: rgb(0, 0, 0);
+}
+
+.gnd .pinlabel__leader {
+    stroke: rgb(0, 0, 0);
+}
+
+.gnd .swatch__body {
+    fill: rgb(0, 0, 0);
+}
+
+.interface .pinlabel__body {
+    fill: rgb(182, 69, 176);
+}
+
+.interface .pinlabel__leader {
+    stroke: rgb(182, 69, 176);
+}
+
+.interface .swatch__body {
+    fill: rgb(182, 69, 176);
+}
+
+.peri .pinlabel__body {
+    fill: rgb(230, 87, 10);
+}
+
+.peri .pinlabel__leader {
+    stroke: rgb(230, 87, 10);
+}
+
+.peri .swatch__body {
+    fill: rgb(230, 87, 10);
+}
+
+.panel__inner {
+    fill: #fff;
+}