Swd debug

KiCad 8/9 Template for CI/CD with KiBot

A KiCad 8/9 template for automated, professional documentation generation with Continuous Integration and Continuous Development (CI/CD) using KiBot.

A video tutorial for setting up this template is available here.

An example project using this template can be found here.

[!NOTE] This file will be overridden by a KiBot run.

TABLE OF CONTENTS

• TABLE OF CONTENTS
• FEATURES
• GETTING STARTED
• USAGE
  • CI/CD Workflow and Semantic Versioning
  • Running Locally
  • Calculating Board Costs (KiCost)
  • Visualizing Outputs in a Webpage
• PROJECT CONVERSION GUIDE
  • Folders
  • Schematic
  • PCB
  • Summary in table format
• DIRECTORY STRUCTURE
• CREDITS
• RESOURCES
• CONTRIBUTING

FEATURES

• Automated fabrication document: Example. The stackup table, fabrication notes, drill drawings/tables, testpoint tables/highlighting are all automated.

• Automated assembly document: Example. The images, tables, DNP crosses, texts are all automated.

• Automated table of contents in schematic

• Automated 3D images of the PCB in various documents

• Synchronised CHANGELOG.md with Revision History page of the schematic

• Automated README.md: images and other board information

• Various outputs such as gerbers, 3D renders, ERC/DRC reports, BoM, Diff visualizer

• Modern webpage for visualizing the generated files and documents

• Robust workflow with two branches and semantic versioning

• Releases with changelog and assets

• Can be run locally with Docker

GETTING STARTED

1. Go to your KiCad templates folder

   Windows:

   cd "C:\Program Files\KiCad\8.0\share\kicad\template"

   Linux:

   cd ~/.local/share/kicad/8.0/template

2. Clone the repository

   git clone https://github.com/nguyen-v/KDT_Hierarchical_KiBot.git

3. Install the fonts inside of kibot_resources/fonts if not already installed on the system.

   Linux:

   cp -i KDT_Hierarchical_KiBot/kibot_resources/fonts/*.ttf ~/.fonts/
   fc-cache

4. A custom color theme (Altium_Theme.json) is also provided in kibot_resources/colors. You should move this file to your KiCad Themes folder.

   Windows:

   xcopy "KDT_Hierarchical_KiBot\kibot_resources\colors\Altium_Theme.json" "C:\Users\%USERNAME%\AppData\Roaming\kicad\8.0\colors\" /-Y

   Linux:

   cp -i KDT_Hierarchical_KiBot/kibot_resources/colors/Altium_Theme.json ~/.config/kicad/8.0/colors/

[!NOTE] In the steps above, replace 8.0 with 9.0 for KiCad 9

5. Create a new project with:

   File → New Project From Template and select KDT_Hierarchical_KiBot

[!CAUTION] Under Linux, the .github folder from the template needs to be copied at the root of the project directory, as it is not copied when creating a project from a template in KiCad.

6. Create a new dev branch. This will be the working branch.

   git checkout -b dev

7. Modify the following fields in kibot_main.yaml according to your project:

     # Metadata ===================================================================
   
     PROJECT_NAME: Project Name
     BOARD_NAME: Board Name
   
     COMPANY: Company Name
     DESIGNER: Author
   
     LOGO: 'Logos/dummy_logo.png'
     GIT_URL: 'https://github.com/nguyen-v/KDT_Hierarchical_KiBot'
   
     # Preflight ==================================================================
   
     CHECK_ZONE_FILLS: false
     STACKUP_TABLE_NOTE: external layer thicknesses are specified after plating
   
     # BoM ========================================================================
   
     MPN_FIELD: 'Manufacturer Part Number'
     MAN_FIELD: 'Manufacturer'
   
     # Drill table and drill map parameters =======================================
   
     GROUP_ROUND_SLOTS: true  # whether or not to group round holes and slots

   Show 25 more lines

8. The files inside of kibot_resources/templates should also be modified according to your project. These include Assembly and Fabrication notes, Impedance table and README file templates.

9. Edit the *.kicad_dru if necessary according to your design rules. Right now, it has been set for PCBWay 6-layer PCBs with 2oz outer 1oz inner, focusing on lowest cost.

10. Edit the kibot_out_csv_bom.yaml, kibot_out_html_bom.yaml and kibot_out_xlsx_bom.yaml files according to the component fields that you use. You can refer to the KiCost Documentation for the field names.

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.

[!NOTE] KiCad 9 allows for fonts to be embedded in the schematic. However, it is still good practice to add the fonts in the folder mentioned.

• 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  

• The kicad_version variable in .github/workflows/ci.yaml should be selected according to the desired KiCad version. Supported versions are 8 and 9.

• 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 to be up-to-date with the remote:

  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. This should pull and start a docker running the dev branch of KiBot. You should have access to your local files.

KiCad 8

Windows:

.\docker_kibot_windows.bat

Linux:

./docker_kibot_linux.sh

KiCad 9

Windows:

.\docker_kibot_windows.bat -v 9

Linux:

./docker_kibot_linux.sh -v 9

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

./kibot_launch.sh

You can get more information about the usage with

./kibot_launch.sh --help

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.

PROJECT CONVERSION GUIDE

This section will describe the necessary steps to convert an existing project to work with this template. This will also give more insights into how the template works in general. For more information, you should refer to the template.

Folders

You should keep the folder structure as defined in DIRECTORY STRUCTURE. The folders marked as optional are not mandatory for the project to work, as long as the relevant file paths are correct (e.g. logos). You should then go through the same steps as in GETTING STARTED and USAGE.

Schematic

You should select Templates/KDT_Template_GIT.kicad_wks as your Drawing Sheet in:

File → Page Settings → Drawing Sheet

On the same page, The Revision and Company fields should be set to ${REVISION} and ${COMPANY} and exported to all sheets.

For an automated table of contents, you should copy the root page of the template into your project, or use the ${SHEET_NAME_X} text variables. These variables will be replaced by the sheet name (page X) when running KiBot. Currently the maximum number of pages is set to 40. You are free to add new text variables in kibot_yaml/kibot_pre_set_text_variables.

The ${VARIANT} text variable is replaced by the current variant name (e.g. DRAFT or RELEASED).

The ${RELEASE_DATE} and ${RELEASE_DATE_NUM} will be replaced by the tag release date and are just the same date in different formats (for example, ${RELEASE_DATE} = 17-Dec-2024 and ${RELEASE_DATE_NUM} = 2024-12-17).

To get 3D pictures of the PCB in the schematic, you can create text boxes with the desired size, with the following names: kibot_image_png_3d_viewer_angled_top and kibot_image_png_3d_viewer_angled_bottom.

You can add any image generated by a KiBot output using by changing the name to kibot_image_<output_name>.

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 (${RELEASE_TITLE_VAR<VERSION>} and ${RELEASE_BODY_VAR<VERSION>) 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'

PCB

The layer names of the PCB should follow the ones defined in kibot_main.yaml.

  LAYER_TITLE_PAGE: TitlePage
  LAYER_DNP_TOP: F.DNP
  LAYER_DNP_BOTTOM: B.DNP
  LAYER_DRILL_MAP: DrillMap
  LAYER_TP_LIST_TOP: F.TestPointList
  LAYER_TP_LIST_BOTTOM: B.TestPointList
  LAYER_ASSEMBLY_TEXT_TOP: F.AssemblyText
  LAYER_ASSEMBLY_TEXT_BOTTOM: B.AssemblyText
  LAYER_DNP_CROSS_TOP: F.DNP
  LAYER_DNP_CROSS_BOTTOM: B.DNP

The layer names can be set in

File → Board Setup → Board Stackup → Board Editor Layers

Each layer has a specific function, and must be setup in a particular way.

In the following explanation, when a group must be created, this can be done using KiCad's Draw Rectangle tool, and then a group can be created with:

Right-Click → Grouping → Group Items

Pressing E then allows you to rename the group. The size and position of the group usually determines the size and location of the element to be drawn. To change the font inside a group, you can create a textbox with the desired font in the group. You can set the border width to 0.

TitlePage

This is used for the first page of the assembly document. Here, you should add Top View and Bottom View texts and under these text, you can create two named groups with the location and size that you desire. The groups should be named kibot_image_png_3d_viewer_angled_top and kibot_image_png_3d_viewer_angled_bottom.

[!TIP] You can add any image generated by a KiBot output using by changing the name to kibot_image_<output_name>.

User.Comments

Currently not used, you can use it for your project.

F.DNP and B.DNP

These are used to hold the red crosses for components marked as Do Not Populate. The layers for those should be kept empty.

DrillMap

This layer is used to draw drill map drawings and drill tables in the fabrication document. You should create a named group called kibot_table_csv_drill_table and place it where the drill tables should be drawn for each drill layer pair. The drill drawing is by default aligned with the PCB.

F.TestPoint and B.TestPoint

These layers are used to highlight testpoint locations in the fabrication document. They should be left as empty.

F.AssemblyText

This layer is used to hold information about the number of components, assembly notes, assembly drawing and 3D render of the top of the PCB. For the number of components, you should create a group named kibot_table_csv_comp_count. Assembly notes should be added using the text variable ${ASSEMBLY_NOTES}. The 3D render can be added by creating a group named kibot_image_png_3d_viewer_top.

B.AssemblyText

This layer hold the assembly drawing and 3D render for the backside of the PCB. For the 3D render, you should add a group named kibot_image_png_3d_viewer_bottom.

F.Dimensions

This layer holds information about the PCB stackup and dimensions, impedance table and fabrication notes. The PCB stackup can be added by creating a group named kibot_fancy_stackup. The impedance table with a group named kibot_table_csv_impedance_table and the fabrication notes are included with the text variable ${FABRICATION_NOTES}.

[!NOTE] The text variable ${FABRICATION_NOTE} is dependent on the kibot_resources/templates/fabrication_notes.txt file. Modify it to your needs.

B.Dimensions

This layer contains information about the dimensions of the PCB, seen from the backside. Similarly to the front side, you can use KiCad's Dimensions tool to add some dimensions.

F.TestPointList

This layer is used to hold information about the testpoints locations and nets. You can add testpoint tables by creating a group named kibot_table_csv_testpoints_top. It is also possible to use python slicing to separate the table into multiple tables, by using slice operators in the name. For example: kibot_table_csv_testpoints_top[:32] and kibot_table_csv_testpoints_top[32:] in two different groups would create two tables with the first one including the first 32 testpoints and the second one every testpoint after that.

Test point locations are computed from the drill origin, which can be set with:

Place → Drill/Place File Origin.

[!TIP] It is usually good practice to set the origin at the bottom left of the board.

B.TestPointList

Similar to the front testpoint layer. The group should be named kibot_table_csv_testpoints_bottom. Note that because PCB is inverted for this layer during print, if the group is placed on the left side it will be printed on the right side.

Summary in table format

DIRECTORY STRUCTURE

The following directory structure is used in the template. Folders marked as 'optional' are not crucial for KiBot to work. Other folders will be generated automatically during a KiBot run.

├─ Computations       # Misc calculations (optional)
├─ HTML               # HTML files for generated webpage
├─ Images             # Pictures and renders
│
├─ kibot_resources
│  ├─ colors          # Color theme for KiCad
│  ├─ fonts           # Fonts used in the project
│  ├─ scripts         # External scripts used with KiBot
│  └─ templates       # Templates for KiBot generated reports
│
├─ kibot_yaml         # KiBot YAML config files
├─ KiRI               # KiRI (PCB diff viewer) files
│
├─ lib                # Footprint and symbol libraries (optional)
│  ├─ 3d_models       # Component 3D models
│  ├─ lib_fp          # Footprint libraries
│  └─ lib_sym         # Symbol libraries
│
├─ Logos              # Logos (optional)
│
├─ Manufacturing
│  ├─ Assembly        # Assembly documents (BoM, pos, notes)
│  │
│  └─ Fabrication     # Fabrication documents (ZIP, notes)

CREDITS

@set-soft for his amazing work on KiBot. Check out the documentation for more!

RESOURCES

• Video Tutorial for this template

• Example project (from the video tutorial)

• Example project (Amulet)

• (Outdated) Best practices and tips for good schematics

• GitHub Actions Documentation

• KiBot Documentation

• KiBot Repository

• KiCost Documentation

• KiCost Repository

• KiRI Repository

CONTRIBUTING

Feel free to open a pull request if you have any cool features to add!