Create reference document and improve tutorials#530
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR expands and reorganizes the project’s documentation (adding a library-construction quick reference and a hierarchical layout tutorial), while also cleaning up and modernizing parts of the electronics library and updating example/test fixtures to match the new tutorials and naming conventions.
Changes:
- Added new reference/tutorial markdown docs and refreshed several “getting started” guides (including removing the optimization tutorial).
- Updated examples/tests and their golden netlists/svgpcb outputs (including new switch-matrix-focused blinky examples and removal of older ones).
- Library cleanup and convention updates (eg,
Stm32f103_48→Stm32f103with deprecation, switch footprint path update, and category/base-class refinements; default linear regulator refinement added).
Reviewed changes
Copilot reviewed 63 out of 100 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| reference_library.md | New quick reference for library block construction and core primitives. |
| README.md | Updates example code to use Stm32f103 naming. |
| getting_started_schimport.md | Adds a “Dragons be Ahead” warning for library construction complexity. |
| getting_started_optimization.md | Removes optimization tutorial page. |
| getting_started_library.md | Simplifies/modernizes library tutorial content and examples. |
| getting_started_hierarchy_layout.md | New hierarchical PCB layout tutorial for KiCad netlist-based flows. |
| getting_started_advanced.md | Updates advanced tutorial to generator_param / ArgParameter style. |
| examples/TofArray/TofArray.net.ref | Updates golden netlist metadata for Stm32f103 rename. |
| examples/TestBlinkySwitchMatrixRefined/TestBlinkySwitchMatrixRefined.svgpcb.js | Updates generated svgpcb output for refined switch-matrix example. |
| examples/TestBlinkySwitchMatrixRefined/TestBlinkySwitchMatrixRefined.net.ref | Updates golden netlist for refined switch-matrix example. |
| examples/TestBlinkySwitchMatrix/TestBlinkySwitchMatrix.svgpcb.js | Adds generated svgpcb output for new switch-matrix example. |
| examples/TestBlinkySwitchMatrix/TestBlinkySwitchMatrix.net.ref | Adds golden netlist for new switch-matrix example. |
| examples/TestBlinkyRgb/TestBlinkyRgb.svgpcb.js | Adds generated svgpcb output for RGB/neopixel variant. |
| examples/TestBlinkyRegulated/TestBlinkyRegulated.svgpcb.js | Adds generated svgpcb output for regulated variant. |
| examples/TestBlinkyPinned/TestBlinkyPinned.svgpcb.js | Adds generated svgpcb output for pinned/assigned-IO variant. |
| examples/TestBlinkyMicro/TestBlinkyMicro.svgpcb.js | Removes older generated svgpcb output. |
| examples/TestBlinkyImplicit/TestBlinkyImplicit.svgpcb.js | Updates implicit-connect example generated svgpcb output. |
| examples/TestBlinkyExpanded/TestBlinkyExpanded.svgpcb.js | Removes older generated svgpcb output. |
| examples/TestBlinkyComplete/TestBlinkyComplete.svgpcb.js | Removes older generated svgpcb output. |
| examples/TestBlinkyChain/TestBlinkyChain.svgpcb.js | Removes older generated svgpcb output. |
| examples/TestBlinkyBasicBattery/TestBlinkyBasicBattery.svgpcb.js | Removes older battery example svgpcb output. |
| examples/TestBlinkyBasicBattery/TestBlinkyBasicBattery.net.ref | Removes older battery example golden netlist. |
| examples/test_tofarray.py | Updates refinement to Stm32f103. |
| examples/test_swd_debugger.py | Updates refinement to Stm32f103. |
| examples/test_robotcrawler.py | Updates refinement to Stm32f103. |
| examples/test_blinky.py | Reworks blinky tests/examples to align with new tutorials and switch-matrix focus. |
| examples/test_ble_joystick.py | Cleans up refinements and switches refinement base class usage. |
| examples/test_basickeyboard.py | Removes old basic keyboard example test. |
| examples/SwdDebugger/SwdDebugger.net.ref | Updates golden netlist metadata for Stm32f103 rename. |
| examples/RobotCrawler/RobotCrawler.net.ref | Updates golden netlist metadata for Stm32f103 rename. |
| examples/PcbBot/PcbBot.net.ref | Updates Kailh socket footprint path in golden netlist. |
| examples/Keyboard/Keyboard.net.ref | Updates Kailh socket footprint path in golden netlist. |
| examples/JacdacKeyswitch/JacdacKeyswitch.svgpcb.js | Updates generated svgpcb output (placement/limits changes). |
| examples/JacdacKeyswitch/JacdacKeyswitch.net.ref | Updates Kailh socket footprint path in golden netlist. |
| examples/DeskController/DeskController.net.ref | Updates Kailh socket footprint path in golden netlist. |
| edg/vendor_parts/Switches.py | Updates Kailh socket footprint to PCM path and refreshes docstring. |
| edg/vendor_parts/init.py | Switches vendor-parts exports to import from Switches.py. |
| edg/parts/power/motor/StepperDriver_A4988.py | Updates driver blocks to implement MotorDriver base category. |
| edg/parts/power/FuelGauge_Max17048.py | Marks Max17048 as Sensor. |
| edg/parts/microcontroller/Stm32f103.py | Renames primary class to Stm32f103 and adds deprecated alias Stm32f103_48. |
| edg/parts/microcontroller/init.py | Exports both Stm32f103 and deprecated Stm32f103_48. |
| edg/parts/interface/Rf_Sx1262.py | Marks Pe4259 as InternalSubcircuit. |
| edg/parts/human_interface/Neopixel.py | Switches Neopixel input model from deprecated vdd to pwr. |
| edg/parts/analog/opamp/Ina826.py | Marks Ina826 as Sensor. |
| edg/electronics_model/SubboardBlock.py | Marks subboard blocks as non-library; categorizes SubboardConnectorPair. |
| edg/electronics_interfaces/CircuitPackingBlock.py | Marks packed pseudo-blocks as InternalSubcircuit. |
| edg/circuits/VoltageComparator.py | Categorizes VoltageComparator as Analog. |
| edg/circuits/SwitchMatrix.py | Categorizes SwitchMatrix as HumanInterface and simplifies derived class bases. |
| edg/circuits/PowerCircuits.py | Categorizes RampLimiter as PowerConditioner. |
| edg/circuits/BootstrapCapacitor.py | Marks BootstrapCapacitor as InternalBlock. |
| edg/BoardTop.py | Adds default refinement mapping LinearRegulator → Ams1117. |
| edg/abstract_parts/Neopixel.py | Replaces vdd alias with deprecated property returning pwr. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+22
to
+24
| - `FloatExpr`: numeric variable | ||
| - Suppers standard numeric operations | ||
| - `RangeExpr`: range (interval) variable |
Comment on lines
+68
to
+70
| - The first argument to chain may be a port or block with an `InOut` or `Output`-tagged port. | ||
| - Middle elements must be a block with an `InOut`-tagged port, or `Input`- and `Output`-tagged ports. | ||
| - The last argument to chain may be a port or block with an `InOut` or `Input`-tageed port. |
Comment on lines
+94
to
+99
| - `VoltageLink`: voltage rail | ||
| - `VoltageSource(voltage_out, current_limits)`: voltage source | ||
| - `VoltageSink(voltage_limits, current_draw)`: voltage sink (power input) | ||
| - `DigitalLink`: low-speed (up to ~100 MHz) digital signals, modeling voltage limits and input / output thresholds | ||
| - `DigitalSource(voltage_out, current_limits, output_thresholds)`: digital output-only pin | ||
| - `output_thresholds` is the range of (maximum low output, minimum high output) |
|
|
||
| ## Requirements | ||
|
|
||
| The example uses the Keyswitch Kicad Library, available on the KiCad Plugin and Content Manager. |
This was referenced Jul 4, 2026
Closed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Library cleanup: