Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve output of diagram + BOM as technical drawing #239

Merged
merged 59 commits into from
Jun 7, 2023
Merged
Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
59 commits
Select commit Hold shift + click to select a range
8ea8248
Squash `feature/mate+autogenerate` branch
formatc1702 Oct 22, 2020
2a62dae
Resolve edge case of empty HTML tables
formatc1702 Sep 23, 2021
2d701ee
Resolve component level mate not revealing connection count
formatc1702 Sep 23, 2021
9ccd55e
Update syntax description (autogeneration, arrows)
formatc1702 Sep 23, 2021
db6f2da
Move selected test files to examples directory
formatc1702 Sep 23, 2021
50ea7f5
Fix duplicates in `syntax.md` after rebase
formatc1702 Oct 13, 2021
02a800a
Fix bug of arrows using the wrong port IDs
formatc1702 Oct 14, 2021
f0b63de
Simplify code
formatc1702 Oct 14, 2021
6b1e274
Refactor functions for harness building
formatc1702 Oct 16, 2021
eae2694
Implement template-based HTML output
formatc1702 Aug 26, 2021
95defd0
Add template metadata to demo02.yml
formatc1702 Aug 26, 2021
960f20e
Add type hint
formatc1702 Sep 28, 2021
36195e1
Apply `fontname` and `bgcolor` to output HTML
formatc1702 Sep 28, 2021
5bed6de
Consolidate code for replacing HTML placeholders
formatc1702 Sep 28, 2021
0296310
Implement `fontname` and `bgcolor`(WIP) replacement
formatc1702 Sep 28, 2021
406bdd3
Use regex-based replacement
formatc1702 Sep 28, 2021
b2a2770
Update `smart_file_resolve()`
formatc1702 Oct 2, 2021
aa9278d
Apply suggestions from code review
formatc1702 Oct 2, 2021
a59f96a
Apply suggestions from code review
formatc1702 Oct 7, 2021
b513051
Equalize line weights and simplify CSS
formatc1702 Oct 7, 2021
00be474
Replace `os.path` with `pathlib.Path` where used
formatc1702 Oct 7, 2021
a85ad89
Add explanatory comment
formatc1702 Oct 7, 2021
35e89d4
Simplify `main()`
formatc1702 Oct 7, 2021
8e59a14
Simplify and clean up `setup.py`
formatc1702 Oct 8, 2021
a810bd5
Add `wv_cli.py`, add Click requirement, change entry point
formatc1702 Oct 2, 2021
1df45ab
Implement working proof of concept
formatc1702 Oct 2, 2021
19481b2
Remove unneeded code from `wireviz.py`
formatc1702 Oct 2, 2021
77f668e
Add CLI help strings
formatc1702 Oct 2, 2021
d3e99ab
Only output requested file types (closes #60)
formatc1702 Oct 2, 2021
b53ce36
Fix entry point
formatc1702 Oct 2, 2021
a5b0fbe
Split the YAML loading and parsing functions
formatc1702 Oct 2, 2021
6a08988
Implement image path resolver
formatc1702 Oct 2, 2021
b1fa2b9
Do not output `.gv` files by default
formatc1702 Oct 2, 2021
3a181f6
Fix smart file resolver for images
formatc1702 Oct 15, 2021
3c6b902
Remove obsolete comments
formatc1702 Oct 15, 2021
0cb0a4e
Add `main()` to `wireviz.py` as fallback
formatc1702 Oct 15, 2021
5b3c2b3
Add encoding info to `wv_cli.py`
formatc1702 Oct 15, 2021
a4343ae
Sort `--format` flags alphabetically
formatc1702 Oct 15, 2021
c68d641
Update README for new CLI commands
formatc1702 Oct 15, 2021
d6d1fbc
Output help string if no arguments are received
formatc1702 Oct 15, 2021
3dae1cb
Improve `REAME.md`
formatc1702 Oct 15, 2021
fb2aae5
Split file output logic and object return logic
formatc1702 Oct 15, 2021
65b8e36
Create cache of graph to avoid generating it more than once
formatc1702 Oct 15, 2021
6f8078e
Add `black` profile for `isort`
formatc1702 Oct 15, 2021
3446154
Apply `isort`
formatc1702 Oct 15, 2021
f92985a
Apply `black`
formatc1702 Oct 15, 2021
c89cf73
Apply some manual fixes, reapply `black`
formatc1702 Oct 15, 2021
58ab5ca
Mention `isort` and `black` in contribution guidelines
formatc1702 Oct 15, 2021
c702e20
Add 'black' badge to `README.md`
formatc1702 Oct 15, 2021
d7d7854
Consolidate `wireviz.parse()` to handle `Path`, `str` and `Dict` as i…
formatc1702 Oct 16, 2021
e353070
Allow specifying output directory and file name separately
formatc1702 Oct 16, 2021
8215113
Add leading underscore to local helper functions
formatc1702 Oct 16, 2021
3aa1a2e
Write docstring for `parse()` function
formatc1702 Oct 16, 2021
b46d263
Update `build_examples.py`
formatc1702 Oct 16, 2021
5aaea65
Automatically include input file directory in list to resolve image p…
formatc1702 Oct 16, 2021
08b5124
Add support for multiple prepended files
formatc1702 Oct 16, 2021
45bcc1d
Make template separator character user-configurable
formatc1702 Oct 16, 2021
d19c260
Simplify file access operations
formatc1702 Oct 16, 2021
e31ed72
Auto-assign missing harness title if reading from file
formatc1702 Oct 16, 2021
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 89 additions & 14 deletions docs/syntax.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,22 +85,8 @@ tweak: # optional tweaking of .gv output
# loops
loops: <List> # every list item is itself a list of exactly two pins
# on the connector that are to be shorted

# auto-generation
autogenerate: <bool> # optional; defaults to false; see below

```

### Auto-generation of connectors

The `autogenerate: true` option is especially useful for very simple, recurring connectors such as crimp ferrules, splices, and others, where it would be a hassle to individually assign unique designators for every instance.

By default, when defining a connector, it will be generated once using the specified designator, and can be referenced multiple times, in different connection sets (see below).

If `autogenerate: true` is set, the connector will _not_ be generated at first. When defining the `connections` section (see below), every time the connector is mentioned, a new instance with an auto-incremented designator is generated and attached.

Since the auto-incremented and auto-assigned designator is not known to the user, one instance of the connector can not be referenced again outside the point of creation. The `autogenerate: true` option is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out. If more wires are to be attached (e.g. for a three-way splice, or a crimp where multiple wires are joined), a separate connector with `autogenerate: false` and a user-defined, unique designator needs to be used.

## Cable attributes

```yaml
Expand Down Expand Up @@ -173,6 +159,7 @@ connections:
- # Each list entry is a connection set
- <component> # Each connection set is itself a list of items
- <component> # Items must alternatingly belong to the connectors and cables sections
# Arrows may be used instead of cables
-...

- # example (single connection)
Expand All @@ -189,6 +176,18 @@ connections:
- [<connector>, ..., <connector>] # specify multiple simple connectors to attach in parallel
# these may be unique, auto-generated, or a mix of both

- # example (arrows between pins)
- <connector>: [<pin>, ..., <pin>]
- [<arrow>, ..., <arrow>] # draw arrow linking pins of both connectors
# use single line arrows (--, <--, <-->, -->)
- <connector>: [<pin>, ..., <pin>]

- # example (arrows between connectors)
- <connector>
- <arrow> # draw arrow linking the connectors themselves
# use double line arrow (==, <==, <==>, ==>)
- <connector>

...
```

Expand All @@ -199,6 +198,7 @@ connections:
- When a connection set defines multiple parallel connections, the number of specified `<pin>`s and `<wire>`s for each component in the set must match. When specifying only one designator, one is auto-generated for each connection of the set.
- `<pin>` may reference a pin's unique ID (as per the connector's `pins` attribute, auto-numbered from 1 by default) or its label (as per `pinlabels`).
- `<wire>` may reference a wire's number within a cable/bundle, its label (as per `wirelabels`) or, if unambiguous, its color.
- For `<arrow>`, see below.

### Single connections

Expand Down Expand Up @@ -249,6 +249,80 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
- `<int>-<int>` auto-expands to a range.
- `<str>` to refer to a wire's label or color, if unambiguous.

### Arrows

Arrows may be used in place of wires to join two connectors. This can represent the mating of matching connectors.

To represent joining individual pins between two connectors, a list of single arrows is used:
```yaml
connections:
-
- <connector>: [<pin>,...,<pin>]
- [<arrow>, ..., <arrow>] # --, <--, <--> or -->
- <connector>: [<pin>,...,<pin>]
```

To represent mating of two connectors as a whole, one double arrow is used:
```yaml
connections:
-
- <connector> # using connector designator only
- <arrow> # ==, <==, <==> or ==>
- <connector>
-
- ...
- <connector>: [<pin>, ...] # designator and pinlist (pinlist is ignored)
# useful when combining arrows and wires
- <arrow> # ==, <==, <==> or ==>
- <connector>: [<pin>, ...]
- ...
```

### Autogeneration of items

For very simple, recurring connectors such as crimp ferrules, splices and others, where it would be a hassle to individually assign unique designators for every instance, autogeneration may be used. Both connectors and cables can be autogenerated.

Example (see `connections` section):

```yaml
connectors:
X:
# ...
Y:
# ...
Z:
style: simple
# ...
cables:
V:
# ...
W:
# ...

connections:
- # no autogeneration (normal use)
- X: [1,2,...] # Use X as both the template and the instance designator
- V: [1,2,...] # Use V as both the template and the instance designator
# ...

- # autogeneration of named instances
- Y.Y1: [1,2,...] # Use template Y, generate instance with designator Y1
- W.W1: [1,2,...] # Use template W, generate instance with designator W1
- Y.Y2: [1,2,...] # generate more instances from the same templates
- W.W2: [1,2,...]
- Y.Y3: [1,2,...]

- # autogeneration of unnamed instances
- Y3: [1,2,...] # reuse existing instance Y3
- W.W4: [1,2,...]
- Z. # Use template Z, generate one unnamed instance
# for each connection in set
```

Since the internally assigned designator of an unnamed component is not known to the user, one instance of the connector can not be referenced again outside the point of creation (i.e. in other connection sets, or later in the same set). Autogeneration of unnamed instances is therefore only useful for terminals with only one wire attached, or splices with exactly one wire going in, and one wire going out.
If a component is to be used in other connection sets (e.g. for a three-way splice, or a crimp where multiple wires are joined), a named instance needs to be used.

Names of autogenerated components are hidden by default. While they can be shown in the graphical output using the `show_name: true` option, it is not recommended to manually use the internally assigned designator (starting with a double underscore `__`), since it might change in future WireViz versions, or when the order of items in connection sets changes.


## Metadata entries
Expand Down Expand Up @@ -300,6 +374,7 @@ For connectors with `autogenerate: true`, a new instance, with auto-generated de
mini_bom_mode: <bool> # Default = True
```


## BOM items and additional components

Connectors (both regular, and auto-generated), cables, and wires of a bundle are automatically added to the BOM,
Expand Down
28 changes: 25 additions & 3 deletions examples/demo02.yml
Original file line number Diff line number Diff line change
@@ -1,3 +1,26 @@
metadata:

title: WireViz Demo 2
pn: WV-DEMO-02

authors:
Created:
name: D. Rojas
date: 2020-05-20
Approved:
name: D. Rojas
date: 2020-05-20

revisions:
A:
name: D. Rojas
date: 2020-10-17
changelog: WireViz 0.2 release

template:
name: din-6771
sheetsize: A3

templates: # defining templates to be used later on
- &molex_f
type: Molex KK 254
Expand All @@ -22,9 +45,8 @@ connectors:
X4:
<<: *molex_f
pinlabels: [GND, +12V, MISO, MOSI, SCK]
ferrule_crimp:
F:
style: simple
autogenerate: true
type: Crimp ferrule
subtype: 0.25 mm²
color: YE
Expand Down Expand Up @@ -64,6 +86,6 @@ connections:
- W3: [1-4]
- X4: [1,3-5]
-
- ferrule_crimp
- F.
- W4: [1,2]
- X4: [1,2]
7 changes: 3 additions & 4 deletions examples/ex04.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,12 @@ cables:
category: bundle

connectors:
ferrule_crimp:
F:
style: simple
autogenerate: true
type: Crimp ferrule

connections:
-
- ferrule_crimp
- F.
- W1: [1-6]
- ferrule_crimp
- F.
25 changes: 25 additions & 0 deletions examples/ex11.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# based on @stmaxed's example in #134

connectors:
X1: &X
type: Screw connector
subtype: male
color: GN
pincount: 4
pinlabels: [A, B, C, D]
F:
style: simple
type: Ferrule
color: GY

cables:
W:
color: BK
colors: [BK, WH, BU, BN]

connections:
- # ferrules + connector X1
- W.W1: [1-4]
- F.
- -->
- X1: [1-4]
25 changes: 25 additions & 0 deletions examples/ex12.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# based on @MSBGit's example in #134

connectors:
X1: &dupont
type: Dupont 2.54mm
subtype: male
pincount: 5
color: BK
X2:
<<: *dupont
subtype: female

cables:
W:
category: bundle
colors: [RD, BK, BU, GN]
length: 0.2

connections:
-
- W.W1: [1-4]
- X1: [1-4]
- ==>
- X2: [1-4]
- W.W2: [1-4]
26 changes: 26 additions & 0 deletions examples/ex13.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# based on @formatc1702's example in #184

connectors:
X:
pincount: 4
pinlabels: [A, B, C, D]
F:
style: simple
type: ferrule

cables:
C:
wirecount: 4
color_code: DIN

connections:
-
- X.X1: [1-4]
- C.C1: [1-4]
- [F.F1, F.F2, F.F3, F.F4] # generate new instances of F and assign designators
- C.C2: [1-4]
- X.X2: [1-4]
-
- [F1, F2, F3, F4] # use previously assigned designators
- C.C3: [1-4]
- X.X3: [1-4]
55 changes: 55 additions & 0 deletions examples/ex14.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
connectors:
JSTMALE: &JST_SM # use generic names here, assign designators at generation time
type: JST SM
subtype: male
pincount: 4
pinlabels: [A, B, C, D]
JSTFEMALE:
<<: *JST_SM # easily create JSTMALE's matching connector
subtype: female
X4: # this connector is only used once, use fixed designator here already
type: Screw terminal connector
pincount: 4
color: GN
pinlabels: [W, X, Y, Z]
S:
style: simple
type: Splice
color: CU
F:
style: simple
type: Ferrule
color: GY


cables:
CABLE:
wirecount: 4
color_code: DIN
length: 0.1
WIRE:
wirecount: 1
colors: [BK]
length: 0.1

connections:
-
- JSTMALE.X1: [4-1] # use `.` syntax to generate a new instance of JSTMALE, named X1
- CABLE.W1: [1-4] # same syntax for cables
- [S., S., S.S1, S.] # splice W1 and W2 together; only wire #3 needs a user-defined designator
- CABLE.W2: [1-4]
- S. # test shorthand, auto-get required number of ferrules from context
- CABLE.W21: [1-4]
- JSTFEMALE.X2: [1-4]
- <=> # mate X2 and X3
- JSTMALE.X3: [1-4]
- CABLE.W3: [1-4]
- [F., F., F., F.]
- --> # insert ferrules into screw terminal connector
- X4: [2,1,4,3] # X4 does not require auto-generation, thus no `.` syntax here
-
- S1: [1] # reuse previously generated splice
# TODO: Make it work with `- F1` only, making pin 1 is implied
- WIRE.: [1] # We don't care about a simple wire's designator, auto-generate please!
# TODO: Make it work with `- W.W4: 1`, dropping the need for `[]`
- X2: [4]
Loading