Test_6/README.md

# KiBot_Template

Template for a KiCad project using the KiBot Workflow

## TODO
Things that are still open or not implemented in the template:
- [ ] Verify the Blender settings hold over multiple board sizes, otherwise add a statement here about how to configure
- [ ] Generate Panel Fabpacks (CI Post-Processing Steps)
- [x] Validate ERC/DRC ruleset in the template and add JLCPCB `kicad_dru` files
- [ ] The Worksheet Frame situation is still broken. Need to do more focused testing with the `dev` image to see if it can be debugged.

At this point it seems like the best course of action right now is to finalize the PCB and SCH templates themselves--namely the ERC/DRC rulesets--and from there start sort of from scratch with the KiBot scripts, building it back up to something useful. Now that all the moving parts are in place, it is clear there is much optimization needed to make it useful. It's also worth revisiting (again) if it makes sense to actually keep all of the generated files in the repo proper or to use Action Assets to hold some of the items. There might be a mix-and-match strategy here.

## GETTING STARTED

1. Create a new repository using the `pdm/KiBot_Template` as the template. Make sure to select the `Git Content (Default Branch)` option to copy the files and default `main` branch into the new repository.
2. Check out the new repository (`pdm/A99-9000` in this example) and run the bootstrapping script to set up the Asymworks KiCad library, add the `dev` working branch, and rename the project based on the current directory.
    ```shell
    $ git clone https://git.asymworks.com/pdm/A99-9000
    $ cd A99-9000
    $ source kibot/scripts/bootstrap.sh
    Created Development Branch
    Added Asymworks KiCad Library
    Renamed KiCad Project to "A99-9000.kicad_pro"
    ```
3. The Gitea action will run on the server in response to the bootstrap script pushing the `dev` branch. Wait for it to complete and then run `git pull` to finish setting up the project.

## USAGE

1. Open KiCad and start drafting the schematic. The KiBot script will start in the `DRAFT` state, which generates the Schematic Netlist, PDF, and BOM. After each `git push`, assuming the KiBot script ran successfully, run a `git pull` to download the generated outputs.
2. Once the schematic is done and the PCB has been initialized with parts and a board outline, change the `kibot_draft` parameter in `.gitea/workflows/ci.yaml` to `false`. This will cause the KiBot script to run in `WORKING` mode, which generates all outputs. It will error out if the board outline does not exist.
3. When the board is ready to review, create a release branch named `review/rev-XX` where `XX` is the revision code. The revision code should start at `NC` (or `100`) and from there increment as specified in the Asymworks product management guidelines. KiBot will run in `REVIEW` mode when a release branch exists.
4. When the board is ready to release, create a Pull Request from the review branch into `main`. Merge the PR and create a tag named `release/rev-XX`. KiBot will run on the `main` branch and create the Gitea Release from the release tag.
5. Continue with the next revision by merging `main` back into `dev`.

## 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](#directory-structure). The folders marked as optional are not mandatory for the project to work, as long as the relevant file paths are correct. You should then go through the same steps as in [GETTING STARTED](#getting-started) and [USAGE](#usage).

### Schematic

You should select [`templates/Asymworks_SCH.kicad_wks`](templates/Asymworks_Sch.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 20. You are free to add new text variables in [`kibot/yaml/kibot_pre_set_text_variables`](kibot_yaml/kibot_pre_set_text_variables.yaml#L69).

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

The `${RELEASE_DATE}` text variable will be replaced by the tag release date (for example, `${RELEASE_DATE} = 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_blender_3d_angled_top` and `kibot_image_blender_3d_angled_bottom`.

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

***

### PCB

The layer names of the PCB should follow the ones defined in [kibot_main.yaml](kibot/yaml/kibot_main.yaml#L754). 

```
  LAYER_TITLE_PAGE: AssyTitlePage
  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.

### Summary in table format

| **Layer**                     | **Description**                                                                                    | **Changes/Included Items**                                                                                                    |
|-------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| **AssyTitlePage**             | First page of the assembly document.                                                               | Add groups: `kibot_image_png_3d_viewer_angled_top` and `kibot_image_png_3d_viewer_angled_bottom`.                             |
| **User.Comments**             | Reserved for project-specific comments.                                                            | Not used by default; customize as needed.                                                                                     |
| **F.DNP / B.DNP**             | Holds red crosses for components marked as *Do Not Populate*.                                      | Keep these layers empty.                                                                                                      |
| **DrillMap**                  | Draws drill map drawings and tables in the fabrication document, aligned by default with the PCB.  | Add group: `kibot_table_csv_drill_table`.                                                                                     |
| **F.TestPoint / B.TestPoint** | Highlights testpoint locations in the fabrication document.                                        | Keep these layers empty.                                                                                                      |
| **F.AssemblyText**            | Contains component count, assembly notes, drawings, and 3D renders for the top side of the PCB.    | Add group: `kibot_table_csv_comp_count` (table) and `kibot_image_png_3d_viewer_top` (image). Include `${ASSEMBLY_NOTES}` text.|
| **B.AssemblyText**            | Holds assembly drawings and 3D render for the bottom side of the PCB.                              | Add group: `kibot_image_png_3d_viewer_bottom` for the 3D render.                                                              |
| **F.Dimensions**              | Holds PCB stackup, dimensions, impedance table, and fabrication notes.                             | Add groups: `kibot_fancy_stackup` (stackup), `kibot_table_csv_impedance_table` (impedance table), and `${FABRICATION_NOTES}`. |
| **B.Dimensions**              | Holds dimensions of the PCB, seen from the backside.                                               | Use KiCad **Dimensions** tool to add details.                                                                                 |
| **F.TestPointList**           | Lists testpoint locations and nets for the top layer.                                              | Add group: `kibot_table_csv_testpoints_top`. Use slicing (e.g., `[:32]`) for multiple tables.                                 |
| **B.TestPointList**           | Lists testpoint locations and nets for the bottom layer.                                           | Add group: `kibot_table_csv_testpoints_bottom`. Adjust left-side placements for inverted print alignment.                     |

## 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.

```
├─ design               # Misc design and analysis (optional)
├─ html                 # HTML files for generated webpage
│
├─ kibot
│  ├─ colors            # Color theme for KiCad
│  ├─ fonts             # Fonts used in the project
│  ├─ scripts           # External scripts used with KiBot
│  ├─ templates         # Templates for KiBot generated reports
│  └─ yaml              # KiBot YAML config files
│
├─ lib                  # Footprint and symbol libraries
│  ├─ asymworks         # Asymworks KiCad library
│  └─ ...               # Additional libraries (optional)
│
├─ mfg
│  ├─ assembly          # Assembly documents (BoM, pos, notes)
│  ├─ fab               # Fabrication documents (ZIP, notes)
│  │  ├─ drill-tables   # CSV drill tables
│  │  └─ gerbers        # Gerbers
│  │
│  └─ jlcpcb            # JLCPCB documents (Gerber, BOM, CPL)
│
├─ models               # Generated 3D models (step, gITF)
├─ notes                # Drawing note text templates
├─ panels               # KiKit panel definitions and outputs
├─ renders              # 2D and 3D PCB renders
├─ schematic            # PDF of schematic
├─ sheets               # Schematic sheets
├─ templates            # Title block templates
└─ test
   └─ testpoints        # Testpoints tables      
```

## CREDITS

[@set-soft](https://github.com/set-soft) for his amazing work on [KiBot](https://github.com/INTI-CMNB/KiBot/tree/master). Check out the [documentation](https://kibot.readthedocs.io/en/latest/) for more!

[@nguyen-v](https://github.com/nguyen-v) for the original version of this CI workflow [KDT_Hierarchical_KiBot](https://github.com/nguyen-v/KDT_Hierarchical_KiBot?tab=readme-ov-file#pcb).

## RESOURCES

- [(Outdated) Best practices and tips for good schematics](https://www.youtube.com/watch?v=_ZjyeltLMAg)

- [GitHub Actions Documentation](https://docs.github.com/en/actions)

- [KiBot Documentation](https://kibot.readthedocs.io/en/latest/)

- [KiBot Repository](https://github.com/INTI-CMNB/KiBot)

- [KiBot Report Sample](https://github.com/INTI-CMNB/KiBot/blob/master/kibot/resources/report_templates/report_full.txt)

- [KiCost Documentation](https://hildogjr.github.io/KiCost/docs/_build/singlehtml/index.html)

- [KiCost Repository](https://github.com/hildogjr/KiCost)

- [KiRI Repository](https://github.com/leoheck/kiri)