Skip to the content
2 layers69 × 49.9 mmCarrier, the printed circuit board in 3D

Household car km tracker: FastAPI + SQLite service on a Raspberry Pi, with ESP32 device API

Size
69 × 49.9 mm
Copper layers
2
Thickness
1.6 mm
Parts
30
Nets
26
Pads
96
Tracks, vias
142, 35
Pours
6
Routed
Yes
KiCad
KiCad 10.0 (file 20260206)
Created
6 Oct 2026
Updated
6 Oct 2026

Overview

Carrier is an open-source printed circuit board by SantiBarrios2002, from the SantiBarrios2002/car-km repository on GitHub. It is a 2-layer board of 69 × 49.9 mm with 30 parts on 26 nets, routed with 142 tracks and 35 vias.

It is built around the TPS3808G01DBVR-TP, M2.5 and SS34, with the SMAJ5.0A among its other parts. Its parts include 8 resistors, 5 connectors, 4 capacitors, 2 diodes and 1 IC.

Main components

4

README

README.md

car-km — household car kilometre tracker

Logs every ride of the family car automatically and works out who drove how many kilometres each month.

A small device in the car reads distance from the OBD-II port over Bluetooth and records each ride. Tapping an NFC fob says who is driving. Rides are uploaded over WiFi to a Raspberry Pi at home, and the family uses a phone web app to see monthly totals, assign untapped rides ("that was me") and export CSV.

text
 car                                              home
┌──────────────────────────────────────┐        ┌───────────────────────────────┐
│ Vgate iCar Pro ─BLE─► ESP32-S3 module │  WiFi  │ Raspberry Pi                  │
│ (OBD-II speed)        + carrier PCB   │ ─────► │ FastAPI + SQLite (app/)       │
│ PN532 NFC ─I²C─►      (supercap hold- │  HTTP  │ web app at /, device API      │
│ (who drives)           up, 5 V input) │        │ at /api/  ◄── family phones   │
└──────────────────────────────────────┘        └───────────────────────────────┘

Status

PartWhereState
Pi service + web appapp/In use on the family Pi.
Carrier PCBhardware/carrier/Schematic done (ERC clean); first-pass board placed, autorouted and passing DRC. Not reviewed, not ordered.
Car device firmwarefirmware/Not started. Conventions are already fixed in CLAUDE.md.

Next step: pre-order checks for the carrier PCB

None of these have been done yet. They come before anything is sent to a fab; details and commands are in hardware/README.md.

  1. Review the board in KiCad: placement, power trace widths, the autorouted tracks.
  2. Check the 3D fit against Waveshare's STEP model (stack height, standoffs, cable paths).
  3. Re-run ERC and DRC after any changes.
  4. Export the Gerber and drill files and inspect them in a Gerber viewer.

Repository layout

text
app/                  Pi service: FastAPI + SQLite, web app and device API
  main.py             all routes (web app + device API), sections marked with # ----
  db.py               schema and SQLite helpers
  static/index.html   the whole web app: one file, vanilla JS, Spanish/English
install.sh            Pi install: venv, systemd unit, nightly backup cron (safe to re-run)
car-km.service        systemd unit template used by install.sh
hardware/             car device hardware: Waveshare module + custom carrier PCB
  README.md           hardware design document: start here for the electronics
  carrier/            KiCad 10 project (schematic + PCB)
  bom-rev2.csv        bill of materials
  vendor/             Waveshare schematic and mechanical drawing (PDF)
CLAUDE.md             working notes for Claude Code and contributors: conventions, hard rules, hardware facts

data/ (database, device token, firmware images, backups) is created at runtime and is not committed.

Pi service

Install on the Pi

bash
git clone <this repo> ~/car-km
cd ~/car-km && chmod +x install.sh && ./install.sh

The script creates a venv, installs a systemd unit (car-km.service, port 8080) and a nightly SQLite backup cron, then prints the Tailscale URL to share with the family. Logs: journalctl -u car-km -f.

Using it

  • Open http://<pi-tailscale-name>:8080 on a phone (see Links). On iOS, Share → Add to Home Screen makes it feel like an app.
  • The first visit asks ¿Quién eres?; the answer is remembered on that phone.
  • Ajustes: add the people. Optionally log the real odometer reading once; after that a ride can be logged by typing the new odometer reading instead of km.
  • Apuntar: km (or odometer) → Guardar. Rides can be back-dated.
  • Resumen: monthly totals per person, with unassigned rides highlighted and a Fui yo button; the CSV button exports the month.
  • Language (es/en) and €/km are set in Ajustes.

Links (family setup)

WhereURL
Anywhere, phone with Tailscalehttp://iot-hub.tail8fe499.ts.net:8080
Same, by Tailscale IP (if the name doesn't resolve)http://100.102.81.29:8080
Home WiFi, no Tailscale neededhttp://192.168.1.140:8080
API docshttp://iot-hub.tail8fe499.ts.net:8080/api/docs

Giving family members access (Tailscale)

At home the LAN link works for anyone on the WiFi. From outside, each person needs Tailscale. Prefer sharing the Pi over inviting people into the tailnet: someone you share with can reach only iot-hub, not your other devices.

  1. In https://login.tailscale.com/admin/machines, open the ⋯ menu on iot-hub → Share… and copy the invite link.
  2. Send it to the person. They install Tailscale (iOS/Android), sign in with their own Google/Apple/Microsoft account and open the link. They get their own free tailnet with iot-hub in it.
  3. On their phone: Tailscale on → open the link above → Share / ⋮ → Add to Home Screen.
  4. To revoke: admin console → Machines → iot-hub → Share… (or the Sharing tab) and remove them.

Alternatively, Users → Invite users makes them full tailnet members. That's simpler when they have many devices, but by default they can then reach every machine, so restrict them in Access controls.

Device API (used by the car device)

MethodPathAuthPurpose
POST/api/rides/batchbearerJSON array of rides; idempotent on (device_id, start_ts)
GET/api/fobsnone (also used by the web app)fob → user map; send If-None-Match with the last ETag to get a 304
GET/api/timebearerserver unix time, for setting the RTC
GET/api/firmwarebearerlatest firmware.bin; send X-Version to get a 304 when current

Bearer = Authorization: Bearer <token>. The token is in data/device_token, created on first start and shown in Ajustes. OTA images go in data/firmware/ (firmware.bin + version.txt).

Ride object:

json
{"device_id":"meriva-1","start_ts":1759742400,"end_ts":1759744230,"km":23.4,
 "fob_uid":"04A1B2C3D4E580","source":"obd","fw":"0.3.1","end_reason":"brownout"}

Interactive docs at /api/docs.

Development

bash
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/uvicorn app.main:app --reload --port 8081

Port 8081 lets the dev server run alongside the live service on 8080. Run from the repo root: the default paths under data/ are relative to the working directory.

Security model

There are no logins: the app is reachable only on the home LAN and over Tailscale, and a household km log doesn't need more. The device API uses a bearer token. Don't expose port 8080 to the internet; if wider access is ever needed, put it behind Tailscale Serve or a reverse proxy with authentication.

Parts

30
QtyValueFootprintReferences
3M2.5MountingHole:MountingHole_2.7mm_M2.5_PadH2, H3, H4
210kResistor_SMD:R_0805_2012MetricR4, R5
25F 2.7VCapacitor_THT:CP_Radial_D8.0mm_P3.50mmC1, C4
25k1Resistor_SMD:R_0805_2012MetricR6, R7
2SS34Diode_SMD:D_SMAD1, D2
1100k 1%Resistor_SMD:R_0805_2012MetricR1
1100nCapacitor_SMD:C_0805_2012MetricC3
110u 16VCapacitor_SMD:C_0805_2012MetricC2
111k3 1%Resistor_SMD:R_0805_2012MetricR2
122R 1WResistor_SMD:R_2512_6332MetricR3
14k7Resistor_SMD:R_0805_2012MetricR8
1BAT->VCAP (closed)Jumper:SolderJumper-2_P1.3mm_Bridged_RoundedPad1.0x1.5mmJP2
1M2.5 NPTHMountingHole:MountingHole_2.7mm_M2.5H1
1PTC 1.1A holdFuse:Fuse_1812_4532MetricF1
1SMAJ5.0ADiode_SMD:D_SMATVS1
1TPS3808G01DBVPackage_TO_SOT_SMD:SOT-23-6U2
1UART debugConnector_PinHeader_2.54mm:PinHeader_1x03_P2.54mm_VerticalJ4
1USB-C power onlyConnector_USB:USB_C_Receptacle_HRO_TYPE-C-31-M-12J1
1USB_5VTestPoint:TestPoint_Pad_D1.5mmTP1
1VCAPTestPoint:TestPoint_Pad_D1.5mmTP2
1bypass D1 (closed)Jumper:SolderJumper-2_P1.3mm_Bridged_RoundedPad1.0x1.5mmJP1
1to PN532 (I2C)Connector_JST:JST_PH_S5B-PH-K_1x05_P2.00mm_HorizontalJ2
1to module J1 (BAT)Connector_Molex:Molex_PicoBlade_53261-0271_1x02-1MP_P1.25mm_HorizontalJ5
1to module J8Connector_JST:JST_SH_SM12B-SRSS-TB_1x12-1MP_P1.00mm_HorizontalJ3

Similar boards

  • 6 layers110 × 96 mmAssembly preview, the printed circuit board in 3D

    Assembly preview

    ripclap/rm520n-carrier

    KiCad RM520N-GL carrier with 2.5 GbE, passive PoE, dual SIM interfaces and independent LoRa management.

    446 partsCERN-OHL-P-2.0
  • 4 layers122 × 76 mmESP iRadio, the printed circuit board in 3D

    ESP iRadio

    hghaken/ESP-iRadio

    ESP32 internet radio with Bluetooth A2DP output (headphones/speaker), 1.69" display and web control

    122 partsGPL-3.0
  • 4 layers40 × 60 mmTrinketcore, the printed circuit board in 3D

    Trinketcore

    alph4345/test

    TrinketCore puts everything a small rechargeable gadget needs on one 40 × 60 mm board, ready to order assembled from PCBWay:

    113 parts
  • 4 layers68 × 68 mmTile, the printed circuit board in 3D

    Tile

    Bruhdows/klink

    Klink is a magnetic tile system for building programmable machines. First up: a marble run with sensors, buttons, lights, gates, splitters and an elevator.

    122 parts
  • 4 layers54 × 42 mmNmos ldo board, the printed circuit board in 3D

    Nmos ldo board

    ChenSiyun1234/nmos-ldo-board

    Discrete NMOS LDO, 1.0 V at 1 A. 4-layer KiCad board, ngspice and thermal sims.

    59 parts
  • 6 layers104 × 104 mmFC REV A, the printed circuit board in 3D

    FC REV A

    desanv01/Flight-Controller-V1

    STM32H743 flight controller: staged design, six-layer PCB implementation, manufacturing data and engineering history.

    330 parts
  • 6 layers40 × 32 mmCollar tracker, the printed circuit board in 3D

    Collar tracker

    gokselozgur5/pcb-design-collar-tracker

    Small GPS and cellular dog-collar tracker. KiCad sources, DFM evidence and ongoing nano-SIM layout work.

    71 parts
  • 4 layers50 × 40 mmRAPS-5 V1, the printed circuit board in 3D

    RAPS-5 V1

    itsTasos/RAPS-5

    Dual-input power module with independent LiPo protection, buck conversion and ideal-diode OR-ing.

    96 parts

Questions

How big is the Carrier PCB?

It measures 69 × 49.9 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Carrier use?

30 parts, built around the TPS3808G01DBVR-TP, M2.5, SS34 and SMAJ5.0A. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the Carrier KiCad files?

From the SantiBarrios2002/car-km repository on GitHub, at the commit this page was made from: the board is hardware/carrier/carrier.kicad_pcb and its schematic hardware/carrier/carrier.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the Carrier design in my own project?

Its repository states no licence, so its author keeps all rights: ask SantiBarrios2002 before reusing the design.