# HBox_PCB — Guide for External Collaborators

**Project:** EinarBoard / HBOX watchdog (Helgen Technologies)
**Repository:** KiCad hardware design files only
**Contact:** Leo Rodríguez — leo@helgen.tech

---

## 1. What this repository is

The complete KiCad design history of the HBOX watchdog board, versions v3 through v6.

- **Active design: `hbox-watchdog-v6.*`** — this is the only version under development.
- `hbox-watchdog-v3/v4/v5.*` are frozen history. Do not modify them.
- Files ending in `-PROD` are snapshots of boards that were actually fabricated. Never touch these.
- Symbol and footprint libraries (`Drogheda-v6.kicad_sym`, `Drogheda-v6.pretty/`, `sym-lib-table`, `fp-lib-table`) live inside the repo with project-relative paths, so a clone is self-contained — no external library setup needed.
- `docs/` contains the **EinarBoard v6 Copper Plan — Placement & EMC Guide** (English and Spanish). Read its §0 (EMC laws) and §8 (master proximity table) before proposing any placement or routing change.

## 2. Getting access

1. Ask Helgen to create an account for you on the Git server `git.helgen.online` and to grant you access to `Helgen-Services/HBox_PCB`.
2. Log in to the web interface and add your **SSH public key** under your account settings.
3. Note that SSH runs on **port 222**, not 22.

## 3. Cloning

SSH (recommended):

```bash
git clone ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
cd HBox_PCB
```

HTTPS (if your network blocks port 222):

```bash
git clone https://git.helgen.online/Helgen-Services/HBox_PCB.git
```

For a read-only review, a shallow clone is much faster (the repo carries 3D STEP/STL models and full history):

```bash
git clone --depth 1 ssh://git@git.helgen.online:222/Helgen-Services/HBox_PCB.git
```

## 4. Tooling

- **KiCad 10.x is required.** The project is saved in the KiCad 10 format.
  - Do **not** open the files with KiCad 9 or older.
  - Do **not** let a newer major version migrate/re-save the files without agreeing with Helgen first.
- Open `hbox-watchdog-v6.kicad_pro`; the schematic and PCB hang off it.

## 5. Ground rules — KiCad files and git

KiCad's `.kicad_sch` and `.kicad_pcb` are single large text files. Concurrent edits do not merge cleanly, so:

1. **One editor at a time.** Announce before you start editing, and say when you are done.
2. **Pull before opening KiCad. Never pull while the project is open in KiCad.** Close KiCad first, pull, reopen.
3. **Never commit:**
   - lock files (`~*.lck`)
   - backup files (`*bak`, `*-bak*`, autosave files)
   - `*.kicad_prl` (per-user display preferences — your local one will change constantly; leave it out of your commits)
   - fabrication outputs or reports you generated locally
4. **Do not run** "Update PCB from Schematic", global re-annotation, or library/format migrations unless that is the agreed task — they generate huge diffs that bury real changes.
5. Keep commits small and single-purpose.

## 6. Contribution workflow

Never commit to `main` directly.

```bash
# start from up-to-date main
git checkout main
git pull

# create your branch
git checkout -b review/<yourname>/<topic>     # e.g. review/ana/emc-g2

# ... work in KiCad, then close KiCad and check what changed
git status
git diff --stat

# stage only the intended files
git add hbox-watchdog-v6.kicad_pcb
git commit -m "v6 PCB: <what you changed> (<why>)"

# publish and open a Pull Request to main in the web interface
git push -u origin review/<yourname>/<topic>
```

Before opening the Pull Request, refresh your branch:

```bash
git fetch origin
git rebase origin/main
```

Helgen reviews and merges. Never force-push to `main`.

## 7. Review-only feedback (no file edits)

If your role is review rather than editing, do not modify files at all: open an **Issue** in the web interface. Reference parts by their reference designator (`U25`, `C149`, `J12`…) and, where relevant, the Copper Plan section number (e.g. "§8, U25 group"). Screenshots of the KiCad view are welcome.

## 8. Questions

Anything unclear — ask before pushing. A five-minute question is cheaper than untangling a bad merge of a 1.5 MB board file.