AllSpice-Demos/Add-on-template
14
Fork 0
Files Issues 1 Design Reviews Actions NEW Releases Activity

Create boilerplate template from example #1

Merged
AllSpiceAlice merged 11 commits from dd/dev into main 2024-07-22 01:14:25 +00:00
Conversation 0 Commits 11 Files Changed 10 +178 -131
1 changed files with 178 additions and 131 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 4f8ac8b817 - Show all commits

311
README.md
View File

@ -1,141 +1,188 @@
# Generate BOM for E-CAD Projects # AllSpice Actions Add-on template
Generate a BOM output file for an Altium project on AllSpice Hub using [AllSpice Actions](https://learn.allspice.io/docs/actions-cicd). This Add-on shows you how to create an Add-on, and how to set up the files to make an API to pass inputs to the Add-on.
## Table of Contents
- [Usage](#usage)
- [Inputs](#inputs)
- [Outputs](#outputs)
- [Example Workflow](#example-workflow)
- [License](#license)
## Usage ## Usage
Add the following steps to your actions: ### Calling this add-on
This Add-on can be called from an external repository workflow file.
There is an example workflow file in this repository:
[.allspice/workflows/add-on-workflow-example.yml](.allspice/workflows/add-on-workflow-example.yml)
You can copy this workflow file to another repository and use it to call this Add-on template.
### Define API in action.yml
The file [action.yml](action.yml) describes how to connect your workflow call of the add-on to the actual script and specifies how parameters are used.
This is considered an API contract.
Below is the `action.yml` file for this repo. You can see that the `inputs` section maps inputs to input variables.
The second section composes the args from inputs and other values and passes it to the Dockerfile.
```yaml
name: "Hardware DevOps Action"
description: >
A generic AllSpice Action Add-on for hardware development tasks such as schematic review,
PCB review, ECO review, and release. This action demonstrates defining parameters
for these tasks and utilizing GitHub context information.
inputs:
source_file:
description: >
Path to the source file or directory from the root of the repo. For example,
the path to a schematic or PCB file.
required: true
output_file_name:
description: "Name of the output file"
required: true
default: "output.txt"
config_file:
description: >
Path to a configuration file for the task.
required: true
task_type:
description: >
The type of hardware task to perform. Options include 'Schematic-Review',
'PCB-Review', 'ECO-Review', 'Release'.
default: "Schematic-Review"
additional_params:
description: >
Any additional parameters required for the task, provided as a JSON string.
default: "{}"
runs:
using: "docker"
image: "Dockerfile"
args:
- "--source_file"
- "${{ inputs.source_file}}"
- "--output_file"
- "${{ github.workspace}}/${{ inputs.output_file_name }}"
- "--config_file"
- ${{ inputs.config_file }}
- "--task_type"
- ${{ inputs.task_type }}
- "--additional_params"
- ${{ inputs.additional_params }}
- "--source_ref"
- ${{ allspice.sha }}
- "--server_url"
- ${{ allspice.server_url }}
- "--allspice_token"
- ${{ secrets.ALLSPICE_TOKEN }}
env:
GITHUB_TOKEN: ${{ github.token }}
```
### Define Add-on script
[`Add-on-script.py`](Add-on-script.py)
This is the program that you will use to perform your Add-on. In this case, we use Python and the py-allspice API wrapper.
The first part of the program is parsing the arguments from the API contract, and the second part runs your actual Add-on. In this template example the Python script performs a connection test to AllSpice, and displays the parameters passed from the calling Workflow file.
### Define Dockerfile
`Dockerfile`
The Dockerfile specifies how to set up the environment and what file to run as the Add-on script.
In this repo template, we load Python 3.12, install modules from requirements.py, and thn run Add-on-script.py.
```Dockerfile
FROM python:3.12-bookworm
COPY requirements.txt /requirements.txt
COPY Add-on-script.py /Add-on-script.py
RUN pip install -r /requirements.txt
ENTRYPOINT [ "/Add-on-script.py" ]
```
### requirements.txt
The requirements.txt file specifies which Python modules to load and which version to load.
module-name=version#
`py-allspice` AllSpice’s native Python wrapper to the AllSpice API.
`pyyaml` A YAML markdown language processor. Helps parse workflow.yml files.
```
py-allspice==3.3.0
pyyaml~=6.0
```
### Testing files
This repo has an optional Action workflow that checks the syntax of Add-on-script.py. This is helpful because Python is an interpreted language.
You do not need these files to run your Add-on, however using tests will help you spot errors.
- `.allspice/dependabot.yml` - Instructions for repository workflow tests.
- `.allspice/workflows/test.yml` - Workflow to test this repo on design review.
- Lints 3 different versions of python (Checks syntax)
- `pyproject.toml` - Linter setup. Specifies how the repository workflow tests will check the syntax of this repository
- `requirements-test.txt` - the requirements for the test workflow.
## Add-on input API
You can customize your Add-on inputs to match your own workflow. These are some example inputs that are helpful for running Add-ons.
You can have as many or as few inputs as you need for your workflow.
- `source_file`: The path to the source file used for the task. Example: `Archimajor.PrjPcb`, `Schematics/Beagleplay.dsn`.
- `task_type`: The type of hardware task to perform. Options include `Schematic-Review`, `PCB-Review`, `ECO-Review`, `Release`. (default: `Schematic-Review`)
- `source_ref`: The git reference the task should be performed for (e.g., branch name, tag name, commit SHA). (default: `main`)
- `server_url`: The URL of your AllSpice server instance.
- `output_file`: The path to the output file. If absent, the output will be printed to the command line.
- `additional_params`: Any additional parameters required for the task, provided as a JSON string. (default: `{}`)
- `allspice_token`: Your AllSpice application token. Generate a token at: https://hub.allspice.io/user/settings/applications
- `config_file`: Path to the config file.
- `input_file`: Path to the input file.
## Outputs
The outputs are dependent on the task performed and will be printed to the command line or saved to the specified `output_file`.
In this template repo, there are no actual outputs, however the name of the output is displayed to demnostrate the correct passing of inputs to the script.
## Example Workflow
Here is the file [./allspice/workflows/add-on-workflow-example.yml](./allspice/workflows/add-on-workflow-example.yml)
This shows how to call the Add-on in this repo.
```yaml ```yaml
# Checkout is only needed if columns.yml is committed in your Altium project repo. name: Example AllSpice Add-on Template
- name: Checkout
uses: actions/checkout@v3
- name: Generate BOM on: [push, pull_request]
uses: https://hub.allspice.io/Actions/generate-bom@v0.4
jobs:
hardware-devops:
runs-on: ubuntu-latest
steps:
- name: Checkout code
uses: actions/checkout@v4
- name: Run Hardware DevOps Action
uses: https://hub.allspice.io/AllSpice-Demos/Add-on-template@v0.1
with: with:
# The path to the project file in your repo (.PrjPcb for Altium, .DSN for OrCad). source_path: ".allspice/examples/input.txt"
source_path: Archimajor.PrjPcb output_file_name: "output.txt"
# [optional] A path to a YAML file mapping columns to the component config_file: ".allspice/examples/config.yml"
# attributes they are from. task_type: "Schematic-Review"
# Default: 'columns.yml' additional_params: '{"SCH_VER":"3"}'
columns: .allspice/columns.yml env:
# [optional] The path to the output file that will be generated. ALLSPICE_TOKEN: ${{ allspice.token }}
# 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.](https://learn.allspice.io/docs/yaml)
The format of this YAML file is as follows:
```yml
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:
```yml
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 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.
## 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:
```yaml
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.4
with:
project_path: Archimajor.PrjPcb
columns: .allspice/columns.yml
group_by: "Part ID"
```
Which will generate a BOM squashed by components with matchin Part IDs.
## Variants
To generate the BOM for a variant of the project, pass the `--variant` argument
to the script. For example:
```yaml
- name: Generate BOM
uses: https://hub.allspice.io/Actions/generate-bom@v0.4
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.