CircuitMedic

AI copilot for embedded debugging that detects firmware issues, retrieves traceable datasheet evidence, explains findings, recommends fixes, and validates corrected code.

Comment

Inspiration

CircuitMedic grew out of a real problem I encountered while building ARES, my autonomous rescue robot project.

While working with Arduino-based firmware and components such as the HC-SR04 ultrasonic sensor, I realized that embedded bugs can be very different from ordinary software bugs. Code may compile successfully and look perfectly reasonable while still violating a small hardware requirement — such as timing, timeout behavior, or sensor-specific constraints — and the resulting failure can be difficult to trace.

Debugging meant constantly moving between firmware, datasheets, hardware behavior, and different debugging resources. Even when an AI tool suggested a possible solution, I still wanted to answer four questions:

What exactly in my code is wrong? What does the hardware documentation actually require? What evidence supports the recommendation? And how do I know the fix really worked?

That experience led to CircuitMedic.

Presentation Deck

The complete 9-slide CircuitMedic presentation deck is available in the public GitHub repository and linked below.

Instead of building another chatbot that simply suggests code changes, I wanted to create a debugging workflow that connects firmware findings to traceable hardware evidence, explains the reasoning behind a recommendation, and allows the developer to validate the result by analyzing the corrected firmware again.

I started with Arduino Uno + HC-SR04, a combination directly connected to the embedded work that inspired the project.

The core workflow became:

Detect → Retrieve Evidence → Explain → Fix → Re-analyze

What it does

CircuitMedic is an AI-assisted debugging prototype for embedded hardware and firmware.

For its current Arduino Uno + HC-SR04 scope, CircuitMedic can:

  • analyze firmware using deterministic checks for supported failure patterns
  • identify suspicious code and report the corresponding finding
  • retrieve relevant passages from local datasheet documentation
  • pair findings with traceable source and page metadata
  • provide actionable recommended fixes
  • optionally generate an AI-assisted explanation grounded in the existing finding and retrieved evidence
  • expose uncertainty instead of presenting AI-generated reasoning as unquestionable fact
  • re-analyze corrected firmware to verify whether the implemented checks now pass

The demo intentionally begins with broken HC-SR04 firmware.

CircuitMedic initially reports 3 findings. After correcting the trigger timing according to the documented requirement, re-analysis reduces the result to 2 findings. After adding an explicit timeout and handling the no-echo case, the final analysis reaches 0 findings.

This creates a complete debugging loop rather than stopping at an AI-generated recommendation.

How we built it

CircuitMedic is built in Python around separate firmware analysis, document retrieval, diagnostic reporting, and optional AI explanation layers.

The firmware analyzer performs deterministic checks for the failure patterns currently supported by the prototype. I deliberately avoided asking an LLM to discover every bug from scratch because I wanted the base findings to remain predictable and inspectable.

For the evidence layer, CircuitMedic processes local hardware documentation and uses sentence embeddings to retrieve passages relevant to a detected issue. The diagnostic report then combines the code finding with retrieved evidence, source metadata, and a recommended correction.

The optional AI layer uses OpenAI to transform those existing findings and retrieved evidence into a clearer contextual explanation. AI therefore complements the underlying analysis rather than replacing it.

This separation is an important part of the architecture: if the AI service is unavailable, the deterministic findings, evidence, and base diagnostic report can still remain available.

The current prototype intentionally focuses on Arduino Uno and the HC-SR04 ultrasonic sensor. Rather than claiming broad C++ or physical hardware validation, I chose a focused scope where I could demonstrate an end-to-end, evidence-backed debugging workflow.

Challenges we ran into

One of the biggest challenges was preventing CircuitMedic from becoming a generic "send code to an LLM and display the response" application.

I wanted developers to be able to inspect why a finding exists. This led me to separate deterministic firmware detection, document retrieval, diagnostic reporting, and AI-assisted explanation into distinct parts of the system.

Another challenge was avoiding misleading detections as the analyzer became more robust. Firmware syntax can represent similar behavior in many different ways, and simple pattern matching can incorrectly interpret comments, strings, multiline calls, or guarded operations.

To strengthen the analyzer, I added regression cases covering:

  • multiline calls and same-line guards
  • conditional returns and later uses
  • millisecond and immutable delays
  • source-like strings and comments
  • other known failure cases discovered while refining the prototype

The current suite passes 43 automated tests: 15 existing tests and 28 new regression tests.

Retrieval introduced another challenge: a similarity score is useful for ranking passages, but it should not be presented as the probability that a diagnosis is correct. CircuitMedic therefore keeps retrieved evidence and AI-assisted reasoning distinguishable rather than turning retrieval similarity into a misleading confidence claim.

Accomplishments that we're proud of

I am especially proud that CircuitMedic demonstrates a complete debugging loop rather than ending with an AI-generated suggestion:

Firmware → Finding → Datasheet Evidence → Explanation → Recommended Fix → Re-analysis

The 3 → 2 → 0 findings sequence in the demo makes the effect of each correction directly observable.

I am also proud of the architectural separation between deterministic analysis and optional AI explanation. CircuitMedic can use AI where it adds value without making the entire diagnostic workflow dependent on an AI-generated answer.

Finally, expanding the test suite to 43 passing automated tests helped turn the project from a simple demonstration into a more disciplined prototype whose known failure cases can be checked repeatedly as the analyzer evolves.

What we learned

Building CircuitMedic changed how I think about using AI in engineering tools.

For technical debugging, the most useful role for AI is not necessarily to replace deterministic engineering logic. It can instead make inspectable information easier to understand and act on.

I also learned how important traceability, retrieval quality, source metadata, regression testing, and explicit uncertainty become when an AI prototype is expected to support a real technical workflow.

Most importantly, CircuitMedic connected my interests in embedded systems and AI in a practical way. A debugging difficulty I originally experienced while working on a robotics project became the starting point for building a tool intended to make that same workflow easier.

What's next for CircuitMedic

The next step is validation.

I want to test CircuitMedic against independent firmware examples and collect feedback from other students and embedded developers to understand which findings are genuinely useful, which explanations need improvement, and where the current checks fail.

The second step is to improve the analyzer using observed failures rather than simply adding more rules for the sake of feature count.

After validating the current approach, I plan to extend CircuitMedic to additional embedded components and debugging scenarios, gradually expanding its evidence-backed workflow beyond the HC-SR04 prototype.

The long-term goal is simple:

Make embedded firmware findings easier to inspect, understand, fix, and validate — while keeping the evidence visible.

Built With

Share this project:

Updates

Submission history