🔍 CircuitLens
Local Cactus Hybrid VLM
CircuitLens can use Cactus as a local-first VLM and fall back to Gemini. Cactus exposes an OpenAI-compatible server, so install it and start a vision-capable model in a separate terminal:
brew install cactus-compute/cactus/cactus
cactus serve Cactus-Compute/gemma-4-e2b-it-hybrid --port 8080
Copy .env.example to .env, set CACTUS_ENABLED=true, and keep AI_PROVIDER=hybrid. The app will call Cactus at http://127.0.0.1:8080/v1 first, then use Gemini if Cactus is unavailable. To require Cactus only, set AI_PROVIDER=cactus.
Recommended VLM choices:
Cactus-Compute/gemma-4-e2b-it-hybrid: best fit for Cactus Hybrid because it includes confidence-based cloud handoff and vision support.LiquidAI/LFM2-VL-450M: smaller local VLM for lower memory use, without the same Cactus Hybrid handoff behavior.gemini-3.1-pro-preview: strongest cloud option already integrated in CircuitLens for detailed board analysis.
The existing cactus run command is interactive CLI usage. For CircuitLens integration, use cactus serve, which provides the HTTP endpoint consumed by the Vite server.
Raspberry Pi Deployment
The Pi does not need Node.js or npm. Build the frontend on the development machine, then copy the generated dist/ directory, server.py, and .env to the Pi. The Python runtime serves the UI and handles the Gemini/Cactus API routes:
# On the development machine
npm run build
scp -r dist server.py .env pi@<pi-ip>:/home/pi/circuitlens/
# On Raspberry Pi OS
cd ~/circuitlens
python3 server.py
Open http://<pi-ip>:5173 from a browser on the Pi or another device on the same network. A USB or CSI camera and microphone can be used by the browser through the existing image and voice controls. For the Pi to use a local VLM, point CACTUS_BASE_URL at a Cactus server that supports the Pi architecture; otherwise set AI_PROVIDER=gemini or keep AI_PROVIDER=hybrid for cloud fallback.
Single-device Pi 5 install
Copy the deployment files to the Pi once. After that, the Pi runs the complete device and starts the services on boot:
mkdir -p ~/circuitlens
# Copy dist/, server.py, .env, and rpi/ into ~/circuitlens first.
cd ~/circuitlens
sudo bash rpi/install.sh
sudo bash rpi/setup-cactus.sh
Use AI_PROVIDER=hybrid and CACTUS_ENABLED=true in /opt/circuitlens/.env for local Cactus first with Gemini fallback. For fully offline operation, use AI_PROVIDER=cactus, CACTUS_ENABLED=true, and --no-cloud-handoff is already enabled by the Cactus service. Check the device with:
systemctl status circuitlens cactus
curl http://127.0.0.1:5173/health
The Pi 5 is ARM64, which is the architecture expected by Cactus's native NEON runtime. The earlier Cactus failure happened only in x86-64 Kali WSL, not on the target Pi architecture.
Python Package
The production frontend is bundled into a Python wheel. The wheel contains the Python runtime and built HTML/CSS/JavaScript files; it does not contain node_modules and does not require Node.js at runtime.
Install From TestPyPI
Use this while testing the package before publishing it to the public PyPI index:
python -m pip install --index-url https://test.pypi.org/simple/ circuitlens
circuitlens
If dependency resolution needs packages from normal PyPI as well, use:
python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ circuitlens
Install From PyPI
After the package is published to the real PyPI index:
python -m pip install circuitlens
circuitlens
The command starts the local server at http://0.0.0.0:5173. Set CIRCUITLENS_HOST or CIRCUITLENS_PORT to change the bind address or port.
Create a .env file in the directory where you run circuitlens when using Gemini or Cactus:
AI_PROVIDER=hybrid
CACTUS_ENABLED=true
CACTUS_BASE_URL=http://127.0.0.1:8080/v1
CACTUS_MODEL=Cactus-Compute/gemma-4-e2b-it-hybrid
GEMINI_API_KEY=replace_with_your_gemini_api_key
GEMINI_MODEL=gemini-3.1-pro-preview
For fully offline operation, use AI_PROVIDER=cactus and run a compatible local Cactus VLM. For Gemini-only operation, use AI_PROVIDER=gemini. The wheel does not include Cactus model weights.
Build The Wheel
For maintainers, build it after building the frontend:
npm run build
python -m build --wheel --no-isolation --outdir wheelhouse
python -m venv package-test
package-test/bin/pip install wheelhouse/circuitlens-*.whl
package-test/bin/circuitlens
On Windows, use package-test\\Scripts\\pip.exe and package-test\\Scripts\\circuitlens.exe. The package name is circuitlens.
AI Visual Electronics Troubleshooter
CircuitLens is a phone-first AI electronics troubleshooting assistant that combines camera context, voice/text symptoms, multimodal AI and structured diagnostic reasoning to help engineers determine what to test next.
CircuitLens is designed to bridge the gap between seeing a physical hardware problem and knowing what to test next.
The core workflow is:
OBSERVE → HYPOTHESIZE → TEST → UPDATE → NEXT TEST
📱 UI Preview
The following image represents the proposed CircuitLens user interface and product direction.
Concept UI — MVP in development
Proposed CircuitLens mobile-first interface
🎯 The Problem
Debugging electronics is still heavily dependent on engineering experience.
When a sensor, peripheral or embedded system fails, engineers commonly move between:
- Physical hardware
- Wiring
- Datasheets
- Firmware
- Serial logs
- Documentation
- Search engines
- Debugging tools
A typical troubleshooting workflow becomes:
SYMPTOM
↓
INSPECT HARDWARE
↓
SEARCH DOCUMENTATION
↓
CHECK CODE
↓
GUESS POSSIBLE CAUSE
↓
RUN A TEST
↓
REPEAT
The physical hardware contains important information, but most existing troubleshooting workflows begin with text, logs or code.
The result
- Physical context is easily lost.
- Engineers repeatedly switch between hardware and software.
- Beginners struggle to determine what to test first.
- Experienced engineers spend time diagnosing repetitive problems.
- Generic AI assistants often return long lists of possible causes instead of determining the most useful next action.
💡 Our Solution
CircuitLens
CircuitLens turns an Android smartphone into a visual engineering troubleshooting assistant.
The user points the phone camera at an electronic setup and describes the problem through voice or text.
CircuitLens combines:
CAMERA CONTEXT
+
USER SYMPTOM
+
HARDWARE CONTEXT
+
TECHNICAL KNOWLEDGE
+
PREVIOUS TEST RESULTS
to construct a structured diagnostic path.
The user experience
- Inspect the physical hardware using the phone camera.
- Describe the problem using voice or text.
- Understand the visible hardware and relevant context.
- Generate competing fault hypotheses.
- Select the Next Best Test.
- Perform the test.
- Feed the result back into the diagnostic engine.
- Update the diagnosis and determine the next test.
🧠 Core Innovation
From AI Answers → AI Investigation
A conventional AI assistant might respond:
"Check your wiring, power supply, I²C address and sensor configuration."
CircuitLens is designed to go further.
Instead of asking:
"What could be wrong?"
CircuitLens asks:
"Which test should I perform next to reduce uncertainty?"
The diagnostic loop is:
OBSERVE
↓
HYPOTHESIZE
↓
SELECT NEXT BEST TEST
↓
PERFORM TEST
↓
CAPTURE RESULT
↓
UPDATE HYPOTHESES
↓
SELECT NEXT TEST
This makes CircuitLens an iterative diagnostic system, rather than a one-shot chatbot.
🔧 Initial MVP Scenario
The initial MVP focuses on a real embedded-system setup:
STM32F407G-DISC1
connected to:
ADXL345 Accelerometer
using:
I²C
Example problem:
"My ADXL345 is not giving the correct acceleration values."
The system can consider possible causes such as:
| Priority | Hypothesis |
|---|---|
| High | I²C communication issue |
| High | Incorrect I²C address |
| Medium | Power / GND issue |
| Medium | Sensor configuration issue |
🔬 Example Diagnostic Workflow
1. Hardware Inspection
The phone camera observes the setup.
STM32F407G-DISC1
+
ADXL345
+
I²C
The vision pipeline can identify relevant hardware and visible context.
2. Symptom Capture
The user says:
"My ADXL345 is not giving the correct acceleration values."
The voice input is converted into structured symptom information.
3. Hypothesis Generation
CircuitLens generates candidate causes:
01 I²C communication
02 Incorrect address
03 Power / GND
04 Sensor configuration
4. Next Best Test
Instead of presenting every possible fix, CircuitLens selects a diagnostic action.
┌────────────────────────────────┐
│ NEXT BEST TEST │
│ │
│ Read ADXL345 DEVID register │
│ │
│ Expected result: 0xE5 │
└────────────────────────────────┘
The test is useful because its result can provide evidence about communication and addressing.
5. Result
Example:
TEST RESULT
DEVID = 0x00
CircuitLens updates the diagnostic state.
I²C COMMUNICATION HIGH
I²C ADDRESS HIGH
POWER / GND MEDIUM
CONFIGURATION LOWER
The system can then recommend:
NEXT TEST
Verify SDA / SCL continuity
and confirm the I²C address.
The investigation continues until sufficient evidence is available.
📱 Phone-First Product Experience
The smartphone is not simply a display for a desktop application.
It acts as the primary sensing, interaction and guidance device.
CAMERA
↓
PHYSICAL HARDWARE CONTEXT
↓
VOICE / TEXT SYMPTOM
↓
MULTIMODAL REASONING
↓
FAULT HYPOTHESES
↓
NEXT BEST TEST
↓
TEST RESULT
↓
UPDATED DIAGNOSIS
🏗️ System Architecture
CircuitLens is designed around a mobile-first architecture.
ANDROID PHONE
│
┌─────────────┴─────────────┐
│ │
CAMERA VOICE
│ │
CameraX Audio Input
│ │
└─────────────┬─────────────┘
↓
IMAGE PREPROCESSING
│
┌──────────┴──────────┐
│ │
OCR LIGHTWEIGHT CV
│ │
└──────────┬──────────┘
↓
HARDWARE CONTEXT
│
↓
LOCAL MULTIMODAL AI
Gemma 3n
│
↓
STRUCTURED JSON
│
↓
DIAGNOSTIC ENGINE
│
┌──────────┴──────────┐
│ │
HYPOTHESES TEST SELECTION
│ │
└──────────┬──────────┘
↓
NEXT BEST TEST
│
↓
USER RESULT
│
└────────→ UPDATE
📲 Proposed Android Technology Stack
Application
- Kotlin
- Jetpack Compose
- Android CameraX
- Android audio / voice input
Computer Vision
- Image preprocessing
- Lightweight component detection
- OCR
- OpenCV where appropriate
AI
- Gemma 3n — proposed local/open multimodal model
- Structured model output
- Evidence-aware reasoning
Mobile Inference
Potential inference technologies include:
- LiteRT
- MediaPipe
- ONNX Runtime Mobile
Optimization
- Model quantization
- Frame sampling
- Region-of-interest processing
- Tiered inference
- Asynchronous inference
- GPU/NPU acceleration where supported
- Memory-aware model loading
- Thermal and battery awareness
Actual performance metrics will be benchmarked during implementation rather than assumed.
⚙️ Mobile AI Strategy
Running multimodal AI locally on a smartphone requires careful resource management.
Model Quantization
Reduce model size and computational requirements where appropriate.
Frame Sampling
Avoid running expensive inference on every camera frame.
CAMERA STREAM
↓
LIGHTWEIGHT PROCESSING
↓
RELEVANT FRAME
↓
AI REASONING
Region of Interest
Focus computation on relevant hardware regions rather than the entire image.
Tiered Inference
Use lightweight perception frequently and invoke heavier multimodal reasoning only when necessary.
Asynchronous Inference
Keep the Android interface responsive while inference is running.
Hardware Acceleration
Use available GPU/NPU acceleration where supported by the device and inference framework.
Thermal and Memory Management
Perform expensive inference only when required and manage model resources according to device constraints.
🧩 Structured AI Output
The AI reasoning layer is designed to return structured information rather than directly controlling the application interface.
Example:
{
"hardware": [
"STM32F407G-DISC1",
"ADXL345"
],
"interface": "I2C",
"symptom": "Incorrect acceleration values",
"hypotheses": [
{
"name": "I2C communication issue",
"priority": "high"
},
{
"name": "Incorrect address",
"priority": "high"
}
],
"next_test": {
"name": "Read ADXL345 DEVID",
"expected": "0xE5"
}
}
The Android application can interpret this structured output and render a predictable diagnostic interface.
🧠 Diagnostic Engine
The AI model is responsible for understanding the available information and generating candidate hypotheses.
The diagnostic engine is responsible for:
- Maintaining diagnostic state
- Tracking evidence
- Ranking hypotheses
- Selecting diagnostic tests
- Processing test results
- Updating the investigation
This separation is intended to make the system more controllable and explainable than a pure conversational AI architecture.
📷 Why the Phone Is Essential
CircuitLens is designed around the capabilities of a modern smartphone.
| Phone Capability | CircuitLens Usage |
|---|---|
| Camera | Physical hardware inspection |
| Microphone | Voice-based symptom input |
| Processing | Mobile AI/CV workloads |
| Display | Guided diagnostic procedures |
| On-device AI | Local/private reasoning path |
| Connectivity | Optional engineering workflows |
The goal is:
Make the phone an engineering diagnostic instrument.
💻 Office Kit Workflow
CircuitLens can bridge phone-based physical inspection with laptop-based engineering workflows.
Potential engineering artifacts include:
- Hardware images
- Diagnostic results
- Voice notes
- Test history
- Firmware
- Serial logs
- Datasheets
- Source code
- Diagnostic reports
Conceptual workflow:
PHONE
│
┌────────────┴────────────┐
│ │
CAMERA DIAGNOSIS
│ │
└────────────┬────────────┘
↓
OFFICE KIT
↓
LAPTOP
│
┌────────────┼────────────┐
↓ ↓ ↓
Firmware Logs Datasheets
🎯 Target Users
Embedded Engineers
Investigate board and peripheral problems faster.
Students & Makers
Learn structured electronics troubleshooting.
Robotics Engineers
Investigate sensors, controllers and communication interfaces.
Laboratory Engineers
Diagnose recurring equipment problems.
Field Technicians
Use a phone as a portable troubleshooting assistant.
🚀 MVP Scope
The initial implementation is deliberately constrained.
Initial Hardware Focus
STM32
+
Common Sensors
+
I²C
+
Defined Diagnostic Procedures
The goal is not to claim that CircuitLens can diagnose every circuit.
The MVP will first validate the workflow against known embedded-system scenarios.
Future Expansion
EMBEDDED SYSTEMS
↓
IoT
↓
ROBOTICS
↓
LAB EQUIPMENT
↓
INDUSTRIAL FIELD SERVICE
🛠️ Development Roadmap
Phase 1 — Mobile Interface
Camera, symptom input and diagnostic UI.
Phase 2 — Hardware Context
Component recognition, OCR and image processing.
Phase 3 — Multimodal AI
Integrate a mobile-capable local/open multimodal model.
Phase 4 — Diagnostic Engine
Implement hypothesis generation, ranking and test selection.
Phase 5 — Closed-Loop Diagnosis
Feed test results back into the diagnostic state.
Phase 6 — Phone/Laptop Workflow
Integrate Office Kit and engineering artifacts.
Phase 7 — Real Hardware Validation
Validate against real STM32 + sensor failure scenarios.
⚠️ Engineering Challenges
| Challenge | Approach |
|---|---|
| Local model compute requirements | Quantization + tiered inference |
| Ambiguous wiring | Begin with constrained hardware setups |
| Vision uncertainty | Combine visual context with user input |
| AI hallucination | Structured outputs + diagnostic constraints |
| Incorrect diagnosis | Closed-loop testing |
| Thermal limitations | Asynchronous / demand-based inference |
| Limited MVP development time | Focus on STM32 + ADXL345 first |
📊 Current Development Status
CircuitLens is currently being developed as a hackathon MVP.
Concept & Planning
- Product concept
- Diagnostic workflow
- Next Best Test concept
- Initial hardware scenario
- Android architecture
- Initial UI direction
Prototype
- Interactive camera inspection
- Hardware-context pipeline
- Diagnostic reasoning engine
- Next Best Test engine
- Closed-loop test updates
- Voice interaction
Production Path
- Local multimodal model integration
- Android implementation
- Mobile inference optimization
- Real hardware validation
- Office Kit workflow
🧪 Prototype Strategy
The first prototype focuses on proving the core diagnostic interaction rather than attempting universal electronics diagnosis.
The intended workflow is:
LAUNCH CIRCUITLENS
↓
INSPECT HARDWARE
↓
IDENTIFY CONTEXT
↓
ENTER / SPEAK SYMPTOM
↓
GENERATE HYPOTHESES
↓
SELECT NEXT BEST TEST
↓
ENTER TEST RESULT
↓
UPDATE DIAGNOSIS
↓
SELECT NEXT TEST
Where deterministic prototype logic is used during development, it will be clearly distinguished from real AI inference.
🔮 Future Vision
CircuitLens starts with embedded-system troubleshooting.
The long-term vision is to help engineers understand physical systems using multimodal AI.
Potential applications include:
- Embedded systems
- IoT devices
- Robotics
- Industrial automation
- Laboratory equipment
- Electronics repair
- Field maintenance
Long-term Vision
Bridge the gap between seeing an engineering problem and knowing what to test next.
🏆 Hackathon
Built for:
iQOO Hackathon — Open Innovation Track
CircuitLens focuses on:
- Physical-world AI
- Multimodal interaction
- Mobile/on-device AI
- Android
- Computer vision
- Embedded systems
- AI-assisted diagnostics
- Phone-first engineering workflows
👨💻 Developer
Samarth Ratnaparkhi
Solo developer with hands-on engineering experience across:
- Embedded systems
- STM32
- Sensors
- I²C
- Computer vision
- AI/ML
- Robotics
- Industrial camera systems
- Hardware/software integration
CircuitLens builds on this engineering experience to explore a phone-first AI diagnostic workflow for physical electronics.
📦 Getting Started
Prerequisites
Make sure the following are installed:
- Node.js 18+
- npm
- Git
Check your installations:
node --version
npm --version
git --version
Clone the Repository
git clone https://github.com/Samarth-07-14/CircuitLens.git
Enter the project directory:
cd CircuitLens
Install Dependencies
npm install
Start the Development Server
npm run dev
Vite will start the development server.
Open the URL shown in the terminal, typically:
http://localhost:5173
Build for Production
npm run build
Preview the Production Build
npm run preview
🔄 Development Workflow
Clone the project:
git clone https://github.com/Samarth-07-14/CircuitLens.git
cd CircuitLens
Install dependencies:
npm install
Start development:
npm run dev
After making changes:
git status
git add .
git commit -m "Update CircuitLens prototype"
git push
📁 Project Structure
CircuitLens/
│
├── public/
│
├── assets/
│ └── circuitlens-ui.png
│
├── src/
│ ├── components/
│ ├── pages/
│ ├── data/
│ ├── logic/
│ └── ...
│
├── index.html
├── package.json
├── package-lock.json
├── vite.config.ts
├── tsconfig.json
├── tsconfig.app.json
├── tsconfig.node.json
├── tailwind.config.ts
├── postcss.config.js
├── eslint.config.js
└── README.md
🤝 Development Priorities
The project is being developed with the following priorities:
- Working diagnostic workflow
- High-quality mobile UI
- Real camera interaction
- Reliable diagnostic state management
- Multimodal AI integration
- Local/on-device inference
- Real hardware validation
📜 License
This project is licensed under the MIT License.
Third-party libraries, frameworks, models and open-source components retain their respective licenses.
🔍 CIRCUITLENS
See the hardware. Understand the problem. Test what matters.
Point. Ask. Test.
1 maintainer
Metadata
1 maintainer
Release files for circuitlens 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| circuitlens-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Release files / circuitlens-0.1.1-py3-none-any.whl
| Download URL | circuitlens-0.1.1-py3-none-any.whl |
|---|---|
| Size | 84.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
13992fb510e240d53849e43e6df5f15f5836085451f2e1789098d8e49194d8df
|
|
BLAKE2b-256 checksum How to use checksums |
7e3dc7c79c8f679ade878abef17ff35da7928cb57359b752f6cb00996ab426bc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.4
|
