Balance bot

balance-bot

A two-wheel self-balancing robot. This repo currently holds the hardware design: a passive motherboard PCB that every module plugs into.

100 × 80mm, 2-layer, routed and poured, DRC-clean. Every image here is generated by just render from the board file — nothing is drawn by hand, including the routing.

• ESP32-S3-DevKitC-1 — controller, socketed
• TB6612FNG breakout — dual motor driver, socketed
• GY-521 / MPU6050 — 6-axis IMU, socketed
• 2S Li-ion — 7.4V nominal, XT30 in, charged off-board
• 2 × N20 encoder motors — 6-pin JST-PH each, winding and encoder together

The schematic is Python. hardware/balance_bot.py is the single source of truth for the netlist and the pin map — nothing is transcribed by hand between them, so they cannot drift apart.

Getting started

just bootstrap    # clone KiCad symbol libraries, sync the venv
just check        # build the netlist, run the design rules

just check writes build/balance_bot.net and regenerates docs/pinmap.md. KiCad is not needed for any of that — only for laying out the board.

The netlist is committed on purpose. It is deterministic, so git diff on it shows exactly what a change to the schematic did to the connectivity.

Visualising it

just view     # -> build/board.html

Every socket rendered pin by pin, with click-to-trace net highlighting — the view you want when wiring the thing up or checking a module pinout. Generated from the circuit, so it cannot go stale.

just svg      # -> build/schematic.svg   (needs: pnpm add -g netlistsvg)

A schematic-style drawing with proper symbols, refdes and values. Good for spotting a wrong part; not a schematic you would hand to someone, because SKiDL feeds netlistsvg pin numbers rather than pin names and emits no net labels. See hardware/schematic_svg.py for why patching that around makes it worse.

SKiDL's generate_schematic hangs on this circuit — don't bother. For a real board, use KiCad.

Layout

1. just check
2. just route — places, routes, pours ground and runs DRC, no GUI involved
3. Open it in Pcbnew only to look at it

Re-running just check after a schematic change and re-importing updates the board without disturbing what is already placed — refdes are pinned in the source rather than auto-numbered.

Read next

• docs/workflow.md — how this board was designed, the tooling gotchas, what the checks catch and what they miss, and how to start the next one
• docs/design.md — architecture, power budget, the decisions worth knowing about, and what to verify before ordering boards
• docs/mechanical.md — board envelope and mounting, for designing the chassis
• docs/fab.md — PCBWay order parameters and what gets uploaded
• docs/pinmap.md — generated pin assignments
• docs/bom.md — shopping list

Board

just board      # generate hardware/balance_bot.kicad_pcb from the netlist
just netclasses # trace widths, derived from the currents in docs/design.md
just route      # board -> DSN -> Freerouting -> SES -> board -> pour -> DRC
just pour       # ground plane on both layers, stitched (part of `just route`)
just plot       # look at the placement
just drc        # headless design rule check
just fab        # DRC, then Gerbers + drill -> build/balance-bot-fab.zip

just board places every footprint, draws the outline and mounting holes, and assigns all 38 nets. just route then calls it, autoroutes, pours ground and runs DRC — so the board is regenerated from source each time rather than edited in place, and re-running gives the same board.

That holds only while every track came out of the autorouter. The moment you hand-route anything in Pcbnew, just board and just route both destroy it, and from that point the .kicad_pcb is the artifact — schematic changes go in through Pcbnew's netlist re-import instead.

Placement is checked in the script rather than by eye: every courtyard is tested against every other and against the mounting-hole keepouts, and the build fails on a clash. That includes the modules that plug in on top: a socket's courtyard is its pin row, while the module is a PCB many times the size, so the check uses the module outline instead. Flat SMD may sit underneath; through-hole parts may not.

just fab runs DRC first and refuses to produce an upload package if it fails — so an unrouted or violating board cannot reach PCBWay.

Status

Schematic complete and checked. Board placed, clear, routed and poured: all 99 connections routed, ground on both layers stitched into one plane, and DRC reports 0 violations and 0 unconnected items. just fab produces an upload package. No firmware yet.

Routing is generated, not drawn — just route runs the whole chain and is reproducible, so the board can be regenerated from source rather than preserved. That is the opposite of the usual advice and the reason the warning about never re-running just board is now narrower than it was: it holds only once something is hand-routed.

Top	Bottom

The bottom is the clearer look at the routing: gold pads, traces, and the regular grid of stitching vias tying the two ground planes together. Most of what looks like bare board on both sides is ground pour.

The placement was solved against the checks rather than drawn: the floorplan is a design decision — USB left, motors and battery bottom, switch right, IMU centred laterally — and each passive then sits as close to what it serves as the module outlines allow. The module outlines are still assumed, not measured, and the whole layout rests on them. See the checklist in docs/design.md before ordering.

100 × 80mm, 2-layer, hand-soldered; motors mount to the chassis rather than the board. See docs/mechanical.md to design the chassis in parallel.