Troubleshooting: the bug the code could not show

Chapter two of the gateway build. The firmware from chapter one was finished, it compiled clean, and it did not work.

​

The symptom

Bluetooth tags five centimetres from the antenna. Powered. Advertising. Whitelisted in the gateway’s configuration. The gateway received nothing, and there were no errors anywhere. Every line of the code was plausible, the build was clean, and nothing in the source said otherwise.

​

Giving the agent the hardware context

The session started by telling it what it was working on: which chips are on the board, how they are connected right now, and which debug layers are available. Not the code, which it already had, but the physical arrangement in front of us. That framing is what makes the rest possible. An agent that knows a debug probe is attached and a dongle is spare can reach for them.

​

Layer one: the application log

Over RTT, the nRF52840 side reported exactly what you would hope for:

• the scanner starts
• Bluetooth initialises
• scanning is running

And then not one advertisement received. Not a corrupted one, not a filtered one. None. The firmware believed it was working, and on its own terms it was. A log can only tell you what the code thinks happened. It cannot tell you whether the antenna is connected.

​

Layer two: the air

At this point the agent asked for an over-the-air capture. That was its decision, not a prompt. The application log had told it everything an application log can tell you, and the next answer was not in the code. The dongle went into DFU mode, and the agent configured and flashed the nRF Sniffer for Bluetooth LE firmware onto it itself. The tedious part, handled without instruction. What the air showed: Strong signal, right next to the gateway. The tags were transmitting. Our receiver was deaf.

​

The cause

This board has an RF front end between the antenna and the radio, and it was never switched on. That is worse than it sounds. With the front end off, the antenna is not weakened; it is effectively disconnected. The radio has to enable it in hardware, with precise timing, and that configuration was missing from the build. The chip was listening to an antenna that was not there. This is where an experienced engineer would have looked after a few hours with a spectrum analyser. Seeing the log and the air side by side turned it into a configuration fix.

​

After the fix

The agent rebuilt and flashed. Same board, same tags, same position. The advertisements arrived. The dashboard showed device MAC addresses and signal strength, live. The logs showed JSON being published, and the data landed on the MQTT client.

​

If your board does this

A clean build, a clean log and nothing received narrows quickly once the air is in the picture:

• Tell the agent what is physically on the bench: the board, the probe, and any spare dongle. That is what lets it reach for a capture instead of re-reading the source.
• Ask for the air before the code. Advertisements on the air and none in the log is a receiver problem, not a parser problem, and no amount of reading the parser will find it.
• On any board with a front-end module, check that its control pins are driven. On the BWG840X they are P0.17, P0.19, P0.06 and P0.08 for the SKY66112, and the curated board knowledge carries them so the agent does not have to be told.

​

What this generalises to

Application logs and over-the-air capture, correlated on real hardware, is how embedded engineers debug. The agent does it at machine speed, and the same three layers (app log, HCI bus, and the air) are a standing capability rather than a one-off.

​

Verified with