Troubleshooting
Written from the design before any helmet exists. Each symptom lists what the hardware and firmware report, the likely causes in order, and what to try. Everything here is unverified on hardware; real failure modes will replace the guesses after the first builds.
Where to look first: the app's head map and traces (a live RMS of every contact), the hub's STATUS packet (once a second: battery, charger, ports, Wi-Fi drops), its EVENTs (INTERLOCK, PORT_FAULT, BATTERY_LOW, CAM_STATE, CAM_SYNC_MISS) and LINKSTATS per port (protocol § host → hub control).
Contacts read badly
What it looks like: a contact or an area of the head map reads flat, saturated, or full of 50/60 Hz mains hum; the 125 Hz contact-quality tone is large on those contacts.
How to read it: the hub adds a small 125 Hz tone (3.3 mVpp) to the bias drive. Each contact's 125 Hz amplitude grows with the impedance difference between that contact and the reference, so a large tone means a poor contact (hub § part choices, REF and bias).
| cause | check | fix |
|---|---|---|
| the whole head reads badly | the REF and BIAS contacts are the two pins on the hub at the back of the head, above the inion | make sure the pod sits on the head and both pins touch skin; part the hair there. The hub also has a JST-SH connector for ear-clip or mastoid electrodes instead |
| thick or long hair under some tiles | is it one area (the crown, the back)? | lift the helmet slightly and let it settle again, so the pins work through the hair; wiggle gently. Very thick hair may not work with 2 mm of pin travel (unmeasured) |
| the shell sits too high or too low | every pin is designed to work between 6.2 and 7.7 mm from the scalp (boards § one pin); a head of a very different size or shape can move the shell out of that range | pull the beanie down so the cuff holds the hem under the rim. Head sizes outside the headform the shell was generated for are not covered yet |
| skin oil, products in the hair | is the tone high everywhere after a long session? | wash and dry hair before use; clean the pins (below) |
| a stuck or damaged pin | press the plunger with a fingertip: it should move about 2 mm and spring back | replace the tile from the spares; a stuck pin is a warranty item (warranty) |
| mains hum on everything | is a cable plugged in, or a mains device next to the head? | the helmet does not measure with USB plugged in at all (the interlock). Move away from mains equipment; hum is also a sign that REF or BIAS is not touching |
| motion | does it get worse when you move or talk? | sit still for recordings that matter; dry contacts are sensitive to movement (motion artefacts are unmeasured) |
Cleaning the pins (unverified): wipe the scalp face with a lint-free cloth and isopropyl alcohol, with the battery disconnected, and let it dry fully before use. Do not soak the helmet.
A chain does not enumerate
What it looks like: ENUMERATE reports a port with status RING_ERROR, TIMEOUT or FAULT, or with fewer
converters than its tiles have (each tile has two converters); the head map shows a whole patch of 3 to 5 tiles dark.
How enumeration works: the hub sends ENUM into a port's ring. Each converter in turn answers with its position and its 96-bit UID, and the ring comes back to the hub. Only the last converter in the chain should report SENSE high (nothing plugged into its OUT) (protocol § hub procedures).
| status or sign | likely cause | what to do |
|---|---|---|
FAULT, or EVENT PORT_FAULT |
the port's power switch latched off: a short on that chain. The hub retries once and then leaves the port off | most likely a cable of the wrong type. Every link must be a Type B jumper; a same-side cable maps pin 1 to pin 12 and puts the supply on ground. Check each cable on the chain against the photo in the ordering guide. Then look for a crushed cable or a screw touching a part |
TIMEOUT (no answer within 100 ms) |
the first tile has no power, no firmware, or the cable to the hub is not seated | reseat the hub-to-first-tile cable (open the flip lock, push the cable fully in, close it); check that the tile was flashed (builder guide § 3) |
| fewer converters than expected | the ring is broken after the last converter that answered | reseat the cable after that tile; check its OUT connector (J102) and the next tile's IN (J101) |
RING_ERROR: SENSE high in the middle of the chain |
a tile thinks it is last: its OUT cable is missing or not seated, so its mux closes the ring early | reseat that tile's OUT cable |
RING_ERROR: no tile reports SENSE high |
the last tile's SENSE line sees a cable that is not there, or a damaged connector | check the last tile's J102 is empty and undamaged |
| the port works but loses frames (LINKSTATS errors) | a marginal cable or connector at 3 Mbaud | reseat or replace the cable; report the LINKSTATS numbers in an issue (link errors at 3 Mbaud over 35 cm are a bench item) |
| the wrong patch of the head lights up | port n carries a different chain than protocol/map.json assumes |
connect each chain's head to the port the map gives (out/pcb/cap/boards.json → chains) |
Wi-Fi
The hub's ESP32-S3 joins your 2.4 GHz network as a station and serves one TCP client on port 7130. The app finds it by a broadcast on UDP port 7131. Each camera joins the network on its own and streams to your computer (protocol § transports, camera § how it streams).
| symptom | likely cause | what to do |
|---|---|---|
| the app cannot find the hub | your network blocks broadcasts between devices (guest networks, "client isolation", some mesh systems) | put the computer and the helmet on the same ordinary network, or enter the hub's IP address in the app's sensor settings |
| the hub does not join at all | wrong SSID or key, a 5 GHz-only network, or WPA3-only | give it the network again (HUB_WIFI) over USB; the ESP32-S3 uses 2.4 GHz only |
EEG gaps (seq gaps in the app; STATUS.wifi_dropped rising) |
the link cannot carry 12.8 Mb/s: the hub drops whole EEG packets, oldest first, when 64 KB are waiting | move closer to the access point; turn the cameras off or lower their rate (five cameras at the default SVGA 15 fps add about 18 Mb/s on the same channel); choose a less crowded 2.4 GHz channel |
| only some cameras stream | the cameras did not get the network (CAM_WIFI) or are not powered | check CAM_STATUS per camera; send CAM_WIFI again; check the camera's cable to the hub |
| it works on the desk and drops on the head | the head absorbs 2.4 GHz, and the transmit power is capped at 13 dBm on purpose | keep the access point in the room; on-head Wi-Fi throughput is a bench measurement still to be made |
Charging
The hub charges the battery from USB-C through a BQ25895 charger, at up to 1.5 A, in about 1.6 hours from empty (calculated, hub § power budget).
| symptom | likely cause | what to do |
|---|---|---|
| nothing measures while charging | by design: the interlock holds the contacts' supply off while USB power is present | unplug to wear and record |
| it does not charge | the battery has no thermistor and the TS pin has no 10 kΩ, so the charger sees a temperature fault | fit the 10 kΩ on TS, or use a battery with a 10 kΩ NTC lead (builder guide § 5) |
| it charges slowly | the charger sets its input limit from the USB-C cable's advertised current | use a USB-C charger and cable that offer 3 A at 5 V; the hub does not ask for higher voltages |
| it stops charging when warm | the charger follows the JEITA temperature limits | let it cool; charge at room temperature, off the head |
| it runs for half an hour | that is the design figure with all five cameras streaming (about 32 minutes); cameras off, about 1.7 hours | stream the cameras only when you need them |
| the battery swells, smells, or the pod gets hot | stop. Unplug it, take it off, put it on a non-flammable surface away from anything that burns, and email safety@ (support) |
Cameras
| symptom | likely cause | what to do |
|---|---|---|
| a camera does not power on | its port switch latched (FAULT# for that camera) or CAM_EN is low |
check CAM_STATUS; reseat its cable; a latch on every start can be inrush (a bench item) |
| the picture is curved | the 160° lens is a fisheye | undistort on the computer after calibrating each lens once with a checkerboard |
| the picture is black or upside down | the camera's tail is in J1 the wrong way, or folded wrong | refit it (builder guide § 4) |
| video and EEG do not line up | a camera missed SYNC pulses (CAM_SYNC_MISS) |
check the cable; report the event counts |