Canary

Canary — first-vent detector for lithium batteries

Status: designed and verified in simulation, not yet built. Every gate below passes on this revision; no board has been assembled or powered yet.

Revisions

This folder always holds the latest revision; an ordered revision stays at its order tag (docs/versioning.md).

What it is

A 60 × 40 mm board you put next to (or on) an e-bike or scooter battery while it charges. It watches for the first vent — the moment a failing cell boils off electrolyte as solvent vapour and CO₂ — which comes before self-heating, thermal runaway and smoke. A smoke alarm reacts at the end of that chain; Canary is built to react near its start.

Grid storage and EV packs already carry off-gas detectors (Honeywell BES, Li-ion Tamer). The battery charging in a hallway has nothing. Canary is that detector as an open, cheap, USB-powered board you can order fully assembled.

It fuses three kinds of evidence and needs two at once to alarm:

ALARM = gas and CO₂ (one strong), or heat and any gas evidence, or strong heat alone; held 3 s before it sounds, latched for at least 60 s. Outputs: green breathing (watching), amber (one kind of evidence), red flashing + 100 dB 4 kHz sounder in the smoke-alarm T3 pattern. The button self-tests in normal state and hushes for 2 minutes in alarm — the hush ends early if the evidence gets worse.

Product video: a narrated 4-minute explainer, built by video/ and published rather than committed (video/README.md).

The real firmware, on a simulated ATmega328P with virtual sensors, catching a vent at 400 s (alarm 7.6 s later) — sim/hil/:

Requirements, and whether they are met

How to order (PCBWay, fully assembled)

1. PCB: upload production/canary-gerbers.zip.
   • 2 layers, FR-4, 1.6 mm, 60 × 40 mm, 1 design
   • Min track/spacing 6/6 mil (the design's tightest gap is 0.2 mm), min hole 0.3 mm
   • Solder mask yellow, silkscreen black (white is fine if black is not offered on yellow)
   • Surface finish ENIG (fine-pitch DFN sensors)
   • The board has three internal routed slots (1.0 mm wide): they are intended, not errors.
2. Assembly: turnkey, top side only, 43 placements / 27 unique parts.
   • BOM: production/canary-bom-pcbway.csv (MPN, maker, LCSC # for reference, notes)
   • Centroid: production/canary-cpl.csv; drawing: production/canary-assembly.pdf
   • J1 (USB-C) has four plated shell slots — pin-in-paste/hand-solder as PCBWay prefers.
   • Sensirion parts (U3 SGP40, U4 SHT40, U5 SCD41): no washing, no conformal coating.
3. Programming (PCBWay offers it; ask in the order notes): flash production/canary.hex to U2 (ATmega328P) through the Tag-Connect TC2030 pads (J2, standard 6-pin AVR ISP pinout), with fuses lfuse 0xE2, hfuse 0xD9, efuse 0xFD (internal 8 MHz, no clock divider, brown-out 2.7 V). To do it yourself: a USBasp + TC2030-IDC-NL cable, then make -C firmware flash.

Case

enclosure/print/canary-v1-bumper.stl is an optional printed frame (PLA/PETG, no supports, 64 × 44 × 5 mm). The board presses in from below; its underside stays flush with the frame's so the thermal tab still lies on the pack, and the USB-C, probe connector and the sensor head's air path stay open.

Bring-up

1. Plug a USB-C cable from any phone charger. Green blinks for 90 s (gas sensor warm-up), then breathes slowly.
2. Press TEST/HUSH: green, amber, red sweep, a short beep, and the SGP40 self-test runs. A fault shows as an amber double blink with a chirp every minute.
3. Telemetry: TXD pad, 3.3 V, 38400 8N1, one line a second (t= st= tp= ... sraw= co2= rate= dtdt= e= f=).
4. Use: lay the board on the pack with the thermal tab touching it (or plug a 10 kΩ B3950 NTC probe into the JST-PH and tape it to the pack), the sensor head ("AIR IN") facing the air above the pack.

Limits — read these

• Not a certified safety device. Keep your smoke alarm.
• The thresholds are not yet validated against a real venting cell. The simulated worlds use stated assumptions (SGP40 drop of thousands of ticks, CO₂ rising by thousands of ppm within a minute, accelerating self-heating), based on how first vent is described for commercial off-gas detectors. A real abuse test (a cell vented beside the board, in a safe facility) is the next step, and the thresholds in firmware/src/detect.h may move.
• No battery backup: if the outlet loses power, Canary is off.
• Placement matters: the gas and CO₂ sensors need the vent plume to reach them; inside a closed bag or a frame with no airflow, use the probe and expect slower gas detection.
• The ATmega328P has no USB: firmware updates need an ISP programmer.
• 3D models for SGP40, SHT40, SCD41, the sounder and the JST connector are simple dimensioned boxes made by src/models3d.py (KiCad 10.0.6 ships none).

Files

How to build

Needs docker (kicad/kicad:10.0.6-full), Java + xvfb (Freerouting 1.9.0 at /opt/fr/freerouting-1.9.0.jar or FREEROUTING_JAR), avr-gcc, Python 3.

python3 src/make.py                 # schematic, ERC, netlist gate, place, route, DRC gate, fab
python3 src/make.py sch finish fab  # without re-routing (the routed board in out/ is reused)
make -C firmware                    # firmware only
cd sim/hil && gcc -O2 -I<simavr>/simavr/sim ... && python3 scenarios.py   # see sim/hil/README.md

Routing is done by Freerouting and is not bit-for-bit repeatable, so the committed canary.kicad_pcb is the design of record: CI rebuilds the fab outputs from it and checks they match what is committed.