7.9 KiB
Generate BOM for E-CAD Projects
Generate a BOM output file for Altium, OrCAD or System Capture projects on AllSpice Hub using AllSpice Actions.
Usage
Add the following steps to your actions:
# Checkout is only needed if columns.yml is committed in your Altium project repo.
- name: Checkout
uses: actions/checkout@v3
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.5
with:
# The path to the project file in your repo.
# .PrjPcb for Altium, .DSN for OrCad, .SDAX for System Capture.
source_path: Archimajor.PrjPcb
# [optional] A path to a YAML file mapping columns to the component
# attributes they are from.
# Default: 'columns.yml'
columns: .allspice/columns.yml
# [optional] The path to the output file that will be generated.
# Default: 'bom.csv'
output_file_name: bom.csv
# [optional] A comma-separated list of columns to group the BOM by. If empty
# or not present, the BOM will be flat.
# Default: ''
group_by: "Part ID"
# [optional] The variant of the project to generate the BOM for. If empty
# or not present, the BOM will be generated for the default variant.
# Default: ''
variant: ""
Customizing the Attributes Extracted by the BOM Script
This script relies on a YAML file to specify the columns in the BOM and which
attributes or properties of the components they are populated from. This file is
typically called columns.yml
and can be checked into your repo. To learn more
about YAML, check out the AllSpice Knowledge Base.
The format of this YAML file is as follows:
columns:
- name: "Manufacturer"
part_attributes:
- "Manufacturer"
- "MANUFACTURER"
- name: "Part Number"
part_attributes:
- "PART"
- "MANUFACTURER #"
- "_part_id"
- name: "Designator"
part_attributes: "Designator"
- name: "Description"
part_attributes:
- "PART DESCRIPTION"
- "_description"
First, you have the key columns:
which is mapped to a list. Each element of
the list has two key/value pairs. The first is name
, which will be the column
name in the output file. Next, you have part_attributes
. This can either be
just a string (like in the case of the Designator
column) or a list of strings
(like in the other cases).
If part_attributes
is a string, that property or attribute of the component
is used as the value for that column. If that property is not present
in a particular part, that column will be blank for that part. If
part_attributes
is a list, those properties will be checked in the order they
are defined for each part. The first property found is used as the value for
that column in the row for that part. So if both PART
and MANUFACTURER #
are
defined, it will use PART
.
An example for OrCad columns.yml
file content is:
columns:
- name: "Part Number"
part_attributes:
- "Part Number"
- "_name"
- name: "Designator"
part_attributes: "Part Reference"
- name: "Type"
part_attributes: "Part Type"
- name: "Value"
part_attributes: "Value"
By default, the action will pick up a columns.yml
file from the working
directory. If you want to keep it in a different place or rename it, you can
pass the --columns
argument to the step in the workflow to specify where it
is.
Py-allspice injected attributes
Note that py-allspice also adds a few static attributes, which are taken from
the part itself, and not from the properties or attributes. For Altium projects,
_part_id
and _description
are available, which correspond to the Library
Reference and Description fields of the component. For OrCAD and System Capture
projects, _name
is available, which corresponds to the name of the component.
The underscore is added ahead of the name to prevent these additional attributes from overriding any of your own.
Customizing sorting, filtering and grouping
If you need more control over the BOM, you can configure each column with the following attributes. You can mix and match as many of these configuration options as you want.
Sorting
Add the sort
attribute to a column to sort the BOM by that column. The value
of the attribute should be asc
or desc
.
columns:
- name: "Part Number"
part_attributes:
# - "Part Number"
- "_name"
sort: "asc"
If multiple columns have the sort
attribute, the BOM will be sorted by the
columns in the order they are defined.
The default is no sorting. In that case, the order of the BOM is not specified.
Filtering
To filter the BOM based on a column, add a Regular Expression pattern to the
remove_rows_matching
attribute of a column. As the name indicates, every row
where the value of the specified column matches this regex will be removed from
the BOM.
columns:
- name: "Part Number"
part_attributes:
- "Part Number"
- "_name"
# This will remove all rows where the part number has either "TP", "MTG" or
# "FID" anywhere in it, i.e. will remove all the test points, mounting
# holes and fiducials.
remove_rows_matching: "TP|MTG|FID"
Since this is a regular expression, you can make fairly complex filters. You can read more about regular expressions here.
By default, there is no filtering.
Grouped Values Configuration
You can use the grouped_values_sort
, grouped_values_separator
and
grouped_values_allow_duplicates
attributes to configure the grouped values of
a column. To understand these better, consider the case of a BOM which is grouped
by Part Number, and you want to have a column that lists all the Designators of
a part with the same Part Number. You want the designators to be separated by
a space, and you want them sorted in ascending order. You also want repeated
designators to appear in the list.
columns:
- name: "Part Number"
part_attributes:
- "Part Number"
- "_name"
- name: "Designators"
part_attributes: "Designator"
grouped_values_sort: "asc"
grouped_values_separator: " "
grouped_values_allow_duplicates: true
By default:
- Grouped values are not sorted, and the order is not specified.
- Grouped values are separated by a comma.
- Grouped values do not allow duplicates.
Skip in output
If you need an attribute to just filter, sort or group by, but not show in the
BOM output, you can use the skip_in_output
attribute.
columns:
- name: "BOM Ignore"
part_attributes:
- "BOM_IGNORE"
remove_rows_matching: ".*"
skip_in_output: true
Group By
You can also group lines by a column value. The most common is _part_id
. You
can combine this with the columns YAML example above, like so:
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.5
with:
project_path: Archimajor.PrjPcb
columns: .allspice/columns.yml
group_by: "Part ID"
Which will generate a BOM squashed by components with matching Part IDs.
Variants
To generate the BOM for a variant of the project, pass the --variant
argument
to the script. For example:
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.5
with:
project_path: Archimajor.PrjPcb
columns: .allspice/columns.yml
output_file_name: bom-lite.csv
variant: "LITE"
When no variant is given, the BOM is generated without considering any variants.
SSL
If your instance is running on a self-signed certificate, you can tell the action
to use your certificate by setting the REQUESTS_CA_BUNDLE
environment variable.
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.5
with:
project_path: Archimajor.PrjPcb
columns: .allspice/columns.yml
output_file_name: bom.csv
variant: "LITE"
env:
REQUESTS_CA_BUNDLE: /path/to/your/certificate.cert