Example (click to view):
Generating pinouts requires:
- Device connector photo (.jpg)
- Pinout metadata file in YAML format
Multiple .yaml files within a directory are put into the same index.html page.
The results will be in a folder named "pinouts".
If you include the directory field within the info section of the yaml, the page will be placed within that subdirectory of the "pinouts" directory.
If none of the .yaml files within a directory have the directory field, the title field will be used instead.
If none of the .yaml files within a directory have either field, they will be placed in a subdirectory structure matching that from which the action was run.
Example:
Suppose you have two .yaml files at foo/bar/baz/
You run the action from foo/
If one or both of the files has the directory field set to quux, the index.html will be found at pinouts/quux/index.html
If neither file has the directory field set, but one or both has the title field set to Magic Board, the index.html will be found at pinouts/Magic Board/index.html
If neither file has either field set, the index.html will be found at pinouts/bar/baz/index.html
Each YAML file contains two sections: 'pins' and 'info'
The 'pins' section contains a list of pins, each having the following fields:
| field | description |
|---|---|
| pin | a numeric id corresponding to the physical pin on the connector |
| type | optional - a short code to allow pins to be grouped and colored by type |
| color | optional - if your mapping has this field, a toggle will appear to switch between color-coding by type or this field. It should contain CSS colors, but you can add spaces if you like; e.g. "light green" |
You can also add arbitrary fields with information for the table, and list them, along with a title for the column, in the columns section of your worflow file.
The 'info' section contains information which is used to generate the interactive pinout. It contains the following fields:
| field | description |
|---|---|
| cid | a short name for the connector, to be used in the URL when linking to a particular pin, for pages with more than one connector |
| image | subsection which contains image source and pin coordinates |
| title | the title for the page. Only one connector for a particular board needs this field |
| directory | the target directory for the page. Only one connector for a particular board needs this field |
| board_url | a URL for documentation, which will be placed as a link on the top of the page. Only one connector for a particular board needs this field |
| name | a human-readable name for the connector |
| order | an index to order the connectors on the page. The lower the number, the nearer the top of the page. If the 'order' field is not present, order is undefined, but will probably be sorted alphabetically by the file name |
The 'image' subsections contains the following fields
| field | description |
|---|---|
| file | the image filename, which is stored in the same directory as the YAML |
| pins | subsection with a list of the pins' locations on the image. Its fields are 'pin', which matches to an 'id' in the main 'pins' section, 'x' and 'y', which are the coordinates on the image |
| import | replaces 'file' and 'pins' - References a YAML file which has 'image' as its top-level section, and has 'file' and 'pins' fields. The file path is relative to the referenced YAML file. |
You can find the YAML files that generated the example image above at this link.
pins:
- pin: 1
type: 12V
function: 12V Supply from main relay output
- pin: 2
type: pgnd
function: Power GND
- pin: 3
type: ls
function: Idle solenoid
- pin: 4
type: etb
function: ETB+
info:
title: Big Magic Box
directory: big_magic
name: Main Connector
board_url: https://example.com/documentation
cid: c1
image:
file: connector.jpg
pins:
- pin: 1
x: 1508
y: 958
- pin: 2
x: 1508
y: 787
- pin: 3
x: 1508
y: 616
- pin: 4
x: 1508
y: 445
Look at action.yaml for a list and description of inputs to interactive-pinout.
There is a warnings option to set how warnings are handled, and more options to give finer control over certain types of warnings.
| field | trigger |
|---|---|
warning-no-cid |
A missing cid field in the info section |
warning-no-connectors |
No definition files were found |
warning-no-image |
A missing file field in the image subsection of the info section |
warning-no-pins |
No pins found in definition file |
warning-dupe |
More than one pin that share the same pin field in a single mapping |
Listed below are the possible values for these fields.
| value | behavior |
|---|---|
| false | Print warning |
| notice | Print warning and put notice on workflow summary page |
| error | Cause the workflow to fail immediately |
| skip | Skip generating this pinout, but proceed with any other pinouts |
If a specific warning-* field is not set, the value from the warnings field is used. You can use this to set the default behavior for warnings, and override specific types of warnings with their own field.
For a real-life example, see how rusEFI uses interactive-pinouts in Github Actions.
- name: Generate Pinouts
uses: chuckwagoncomputing/interactive-pinout
with:
mapping-path: firmware/config/boards/*/connectors/*.yaml
warnings: skip
columns: |
{
"pin":"Pin Number",
"ts_name":"TS Name",
"type":"Type",
"function":"Typical Function",
"color":"Pigtail Color"
}
print-columns: |
[
"function"
]
templates: |
{
"___": "pin"
}
colors: |
{
"12v":"yellow";
"12V":"yellow";
"5v":"red",
"5V":"red",
"at":"green",
"av":"brown",
"can":"blue",
"din":"lime",
"etb":"darkcyan",
"gnd":"darkgreen",
"gp_high":"aqua",
"gp_low":"aquamarine",
"gp_pp":"cyan",
"hall":"darkolivegreen",
"hl":"gold",
"hs":"indigo",
"ign":"magenta",
"inj":"maroon",
"ls":"lightgreen",
"mr":"firebrick",
"pgnd":"coral",
"sgnd":"olive",
"usb":"lightseagreen",
"vr":"sienna"
}
The parameters in the workflow can also be passed to main.sh as environment variables instead. Here is the complete list of variables:
MAPPING_PATH
WARNINGS
WARNING_NO_CID
WARNING_NO_CONNECTORS
WARNING_NO_IMAGE
WARNING_NO_PINS
WARNING_DUPE
COLS
PRINT_COLS
INFO_COL
TEMPLATES
COLORS
DEBUG
After exporting these environment variables, execute main.sh. Example:
$ export MAPPING_PATH="firmware/config/boards/*/connectors/*.yaml"
$ export WARNINGS="skip"
$ export COLS='{"pin":"Pin Number","ts_name":"TS Name","type":"Type","function":"Typical Function","color":"Pigtail Color"}'
$ export PRINT_COLS='["function"]'
$ export COLORS='{"12v":"yellow";"12V":"yellow";"5v":"red","5V":"red","at":"green","av":"brown","can":"blue","din":"lime","etb":"darkcyan","gnd":"darkgreen","gp_high":"aqua","gp_low":"aquamarine","gp_pp":"cyan","hall":"darkolivegreen","hl":"gold","hs":"indigo","ign":"magenta","inj":"maroon","ls":"lightgreen","mr":"firebrick","pgnd":"coral","sgnd":"olive","usb":"lightseagreen","vr":"sienna"}'
$ bash ../interactive-pinout/main.sh