3. Usage

CI/CD Workflow and Semantic Versioning

This template is meant to be used in a CI/CD environment on GitHub. The workflow is as follows:

• Any custom font used in the project must be added to the kibot_resources/fonts folder.

• There are two branches, a main and a dev branch. The dev branch is the working branch. The main should only be used for pull requests and releases.

• Changes should be recorded in the CHANGELOG.md file, and should respect semantic versioning guidelines for hardware. The changes of the current version should be added under the [Unreleased] section.

• The variant variable in .github/workflows/ci.yaml should be selected according to the project progress.

    # Used variant. We assume:
    # DRAFT: only schematic in progress, will only generate schematic PDF, netlist and BoM
    # PRELIMINARY: will generate both schematic and PCB documents, but no ERC/DRC
    # CHECKED: will generate both schematic and PCB documents, with ERC/DRC
    # RELEASED: similar to CHECKED, automatically selected when pushing a tag to master
  
    kibot_variant: CHECKED  
  

• You should work locally on the dev branch. When a change is made, the changes should be pushed to GitHub which will trigger the KiBot workflow. The generated files will be committed and pushed back to the repository.

• After a successful KiBot run on the remote repository, you should pull back the changes into your local repository.

• To avoid conflicts, you should avoid modifying the .kicad_pro file locally before pulling from the remote (after the completion of a KiBot run). Otherwise, you will need to solve merge conflicts when pulling the file.

• To synchronise the Revision History of the schematic with the CHANGELOG.md file, you should create new text variables in kibot_pre_set_text_variables.yaml. The text variables should then be added in the text boxes of the Revision History sheet.

  - variable: '@RELEASE_TITLE_VAR@x.x.x'
    command: '@GET_TITLE_CMD@ x.x.x'
  - variable: '@RELEASE_BODY_VAR@x.x.x'
    command: '@GET_BODY_CMD@ x.x.x'
  

• When ready for a release, you should open a pull request and merge the changes into main. Currently the workflow is set not to trigger on pull requests, as we assume the changes coming from dev are up-to-date.

• To create a release, push a tag on the main branch with the version number (for example x.x.x = 1.1.1):

  git checkout main
  git pull
  git tag x.x.x
  git push origin x.x.x
  

  This will start a KiBot run with the variant set as RELEASED. When the run completes, it also creates a release with assets and updates the CHANGELOG.md file (renames the [Unreleased] section with the pushed tag and creates a new [Unreleased] section).

• After a release, you will need to update your main branch and rebase your dev branch with the main branch:

  git fetch origin
  git pull
  

  And you will also need to rebase your dev branch to the main branch:

  git checkout dev
  git rebase main
  

Note

You are free to modify the .github/workflows/ci.yaml file to suit your workflow needs.

---

Running Locally

KiBot can be installed if you want to run some of the scripts locally. If you only plan to use it in a CI/CD workflow, this step can be skipped. Installation steps can be found on the official documentation. The easiest way to install KiBot if custom development is not required is with dockers.

1. Install and run Docker Desktop

2. Run the script docker_kibot_windows.bat or docker_kibot_linux.sh depending on your platform in kibot_resources/scripts. Currently tested on Windows and WSL2.

Windows:

.\docker_kibot_windows.bat

Linux:

./docker_kibot_linux.sh

This should pull and start a docker running the dev branch of KiBot, on KiCad 8. You should have access to your local files.

Once in the docker, you can use the kibot_launch.sh script to generate and visualize outputs.

When running the script with no arguments, it will default to the CHECKED variant and generate all outputs. A variant can be set with the -v flag. If a custom variant is used (i.e. other than the default variants DRAFT, PRELIMINARY, CHECKED, RELEASED), the outputs will be generated in the Variants folder.

Each default variant will have different KiBot flags, which is useful for different phases of the project:

1. DRAFT

   Only schematic in progress, will only generate schematic PDF, netlist and BoM

2. PRELIMINARY

   Will generate both schematic and PCB documents, but no ERC/DRC

3. CHECKED

   Will generate both schematic and PCB documents, with ERC/DRC

4. RELEASED

   Similar to CHECKED, automatically selected when pushing a tag to main (CI/CD)

Warning

When generating outputs locally, it could conflict with the outputs generated by the remote CI/CD workflow. In this case, you should decide how to resolve the conflicts.

---

Calculating Board Costs (KiCost)

KiCost is used to estimate costs and get a nice XLSX spreadsheet with part specs. In this project, we run KiCost locally to avoid too many API calls. Also, DigiKey's API doesn't seem to work in a CI/CD environment. To run KiCost, you will need to create a file kicost_config_local.yaml in kicost_yaml. You can use the kicost_config_local_template.yaml file as a base. Once you have filled in the API keys for the desired manufacturers, KiCost can be run with:

./kibot_launch.sh --costs

This will create a spreadsheet in Manufacturing/Assembly folder.

You can also specify a variant if desired:

./kibot_launch.sh -v <VARIANT> --costs

For more information, please have a look at the official documentation

Caution

KiCost expects the MPN (Manufacturer Part Number) and Manufacturer fields to be named in a certain way. To cater for different naming conventions, we rename user-defined fields to KiCost-compatible fields in the KiBot run. You can set your user-defined field for MPN and Manufacturer in the kibot_yaml/kibot_main.yaml by editing the MPN_FIELD and MAN_FIELD definitions.

---

Visualizing Outputs in a Webpage

The outputs of KiBot can be visualized in a webpage (excepted for the DRAFT variant). This can be done by running:

./kibot_launch.sh --server

And opening http://localhost:8000 in your favorite browser. The server can be shut down with:

./kibot_launch.sh --stop-server

Tip

You can also give the port as an argument if you want to use another port.