Clasificador De Frutas
Clasificador de frutas (naranjas y manzanas) con ayuda de LMStudio y FastMCP
Ask AI about Clasificador De Frutas
Powered by Claude · Grounded in docs
I know everything about Clasificador De Frutas. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Clasificador Automático de Frutas con IA
Sistema de clasificación fÃsica en tiempo real que combina Visión Artificial local con Arduino
Descripción del Proyecto
Este proyecto es un sistema de clasificación de frutas completamente automatizado que utiliza Inteligencia Artificial local y hardware de código abierto para identificar y separar fÃsicamente manzanas y naranjas.
El sistema funciona de la siguiente manera: una fruta se coloca en una rampa; un sensor ultrasónico detecta su presencia, una webcam captura la imagen y un modelo de visión artificial (Qwen3-VL ejecutado localmente en LMStudio) identifica de qué fruta se trata. Finalmente, servomotores controlados por Arduino desvÃan la fruta hacia el contenedor correcto.
Todo el proceso es orquestado por un servidor MCP (Model Context Protocol) escrito en Python con FastMCP. El usuario interactúa con el sistema a través del chat de LMStudio: simplemente escribe "Iniciar" y el modelo Qwen3-VL llama automáticamente las herramientas MCP para operar todo el pipeline.
CaracterÃsticas Principales
- Completamente Automático — Operación continua en bucle infinito sin intervención manual una vez iniciado.
- Inferencia 100% Local — Sin dependencias de la nube. El modelo de IA corre localmente con LMStudio.
- Hardware Accesible — Componentes económicos y fáciles de conseguir.
- Protocolo MCP — Controlable mediante lenguaje natural desde el chat de LMStudio a través de FastMCP.
- Validación Multi-foto — Sistema de votación con múltiples capturas para reducir errores de clasificación.
Hardware
Componentes utilizados
| Componente | Modelo | Función |
|---|---|---|
| Microcontrolador | Arduino UNO R3 | Controla los servos y lee el sensor ultrasónico |
| Cámara | Webcam USB | Captura imágenes de las frutas para la clasificación por IA |
| Sensor de distancia | HC-SR04 | Detecta la presencia de una fruta en la posición de escaneo |
| Servomotores (x2) | MG995 | Accionan las compuertas para desviar las frutas al contenedor correcto |
| Estructura | Maqueta fÃsica | Rampa con dos compuertas laterales y contenedores de destino |
Diagrama del Circuito
Conexiones de pines
| Pin Arduino | Componente | Función |
|---|---|---|
6 | HC-SR04 → Trig | Disparo del pulso ultrasónico |
7 | HC-SR04 → Echo | Recepción del eco |
9 | Servo MG995 #1 | Compuerta de manzanas |
10 | Servo MG995 #2 | Compuerta de naranjas |
5V | HC-SR04 VCC / Servos VCC | Alimentación |
GND | HC-SR04 GND / Servos GND | Tierra común |
Maqueta FÃsica
Arquitectura del Sistema
LMStudio cumple un doble rol en este sistema: es la interfaz donde el usuario interactúa con el modelo (chat + MCP tools) y también sirve como servidor de visión artificial (API en puerto 1235) para clasificar las imágenes.
graph LR
A["LMStudio<br/>Chat + MCP Client<br/>(Qwen3-VL 4B)"]
B["server.py<br/>FastMCP Server"]
C["LMStudio<br/>Vision API<br/>(localhost:1235)"]
D["Arduino UNO R3<br/>Sensor + Servos"]
A <-->|"lenguaje natural · streamable-http"| B
B -->|"HTTP API · /v1/chat/completions"| C
B -->|"Serial · 115200 baud"| D
Flujo de un ciclo completo
flowchart TD
A["Inicio del ciclo"] --> B["Enviar WAIT_FRUIT"]
B --> C{"¿Detectada?"}
C -- "TIMEOUT" --> B
C -- "DETECTED" --> D["Esperar estabilización"]
D --> E["Capturar foto"]
E --> F["Clasificar con Qwen3-VL"]
F --> G{"¿Confirmada?"}
G -- "unknown" --> H["Descartar y reiniciar"]
H --> B
G -- "apple/orange" --> I["Enviar comando"]
I --> J["Accionar servo"]
J --> K["Ciclo completado"]
K --> B
Comunicación entre componentes
1. server.py ↔ Arduino (Serial, 115200 baud)
El servidor Python envÃa comandos de texto por el puerto serial y espera una respuesta:
| Comando enviado | Respuesta esperada | Acción |
|---|---|---|
PING\n | PONG | Verifica que el Arduino está conectado |
WAIT_FRUIT\n | DETECTED o TIMEOUT | Espera hasta que el sensor detecte un objeto a < 15 cm |
APPLE\n | OK | Abre la compuerta de manzanas (servo a 135°) + empuje del servo opuesto |
ORANGE\n | OK | Abre la compuerta de naranjas (servo a 45°) + empuje del servo opuesto |
2. server.py ↔ LMStudio (HTTP API, localhost:1235)
El servidor captura un frame de la webcam con OpenCV, lo codifica a JPEG en base64 y lo envÃa como imagen al endpoint /v1/chat/completions de LMStudio. El modelo Qwen3-VL analiza la imagen y devuelve la clasificación.
Software — Partes Esenciales del Código
Prompt de Clasificación de la IA
Este es el prompt exacto que se envÃa al modelo de visión para clasificar cada fruta. Está diseñado para ser extremadamente restrictivo: el modelo solo puede responder con una de tres palabras, evitando respuestas ambiguas o fuera de rango:
"You are a fruit classification system for a sorting machine. "
"Look at this image carefully and identify the fruit.\n\n"
"Rules:\n"
"- If you see an apple (any color: red, green, yellow), respond: apple\n"
"- If you see an orange (round citrus fruit), respond: orange\n"
"- If you see no fruit, or the image is unclear, respond: unknown\n\n"
"Reply with ONLY one word: apple, orange, or unknown.\n"
"No punctuation, no explanation, no extra text."
¿Por qué funciona?
temperature: 0— Elimina la aleatoriedad. El modelo siempre da la respuesta más probable.max_tokens: 10— Limita la respuesta a pocas palabras, evitando que el modelo "hable de más".- Parseo con fallback — Aunque el modelo agregue texto extra, el código extrae la keyword (
apple,orange) si aparece en la respuesta.
Tools MCP (Herramientas del servidor)
El servidor expone 7 herramientas via MCP que el modelo en LMStudio puede invocar:
| Tool | Descripción |
|---|---|
take_photo() | Captura una foto de la webcam y devuelve la imagen en base64 |
wait_for_fruit() | Bloquea hasta que el sensor ultrasónico detecte una fruta |
classify_fruit() | Captura una foto y la envÃa al modelo de IA para clasificarla |
sort_fruit(fruit) | EnvÃa comando al Arduino para accionar el servo correspondiente |
start_sorting_loop() | Inicia el bucle automático de clasificación en segundo plano |
stop_sorting_loop() | Detiene el bucle automático |
get_loop_status() | Devuelve los eventos nuevos del bucle (para que el modelo los narre) |
Cómo se comunican las Tools entre sÃ
El sistema tiene dos modos de operación:
Modo Manual — El modelo invoca las tools una por una:
flowchart LR
A[wait_for_fruit] --> B[classify_fruit] --> C["sort_fruit('apple')"]
Modo Automático — El flujo completo corre en un thread en segundo plano:
sequenceDiagram
participant M as Modelo (LMStudio)
participant T as Thread en segundo plano
M->>T: start_sorting_loop()
loop cada ciclo
T->>T: wait_for_fruit
T->>T: classify_with_retries
T->>T: sort_fruit
end
loop cada ~5 segundos
M->>T: get_loop_status()
T-->>M: eventos nuevos
note over M: Narra los eventos<br/>al usuario en español
end
M->>T: stop_sorting_loop()
El campo instructions del servidor MCP instruye al modelo Qwen3-VL (en LMStudio) a:
- Llamar
start_sorting_loop()cuando el usuario diga "iniciar" - Llamar
get_loop_status()automáticamente cada 3-5 segundos - Traducir los eventos a lenguaje natural en español
- Nunca preguntar si desea continuar
Protocolo Serial del Arduino
El Arduino implementa un protocolo serial simple basado en texto. Cada comando termina en \n y cada respuesta termina en \n:
sequenceDiagram
participant S as server.py
participant A as Arduino
S->>A: WAIT_FRUIT
A-->>S: DETECTED (sensor < 15 cm)
S->>A: APPLE
note over A: Servo manzana → 135°<br/>Servo naranja empuja (105°)<br/>Ambos vuelven a 90°
A-->>S: OK
El mecanismo de empuje es clave: cuando se clasifica una manzana, el servo de la manzana abre la compuerta (135°) y el servo de la naranja hace un pequeño empuje (de 90° a 105°) para ayudar a la fruta a rodar hacia el contenedor. Lo mismo ocurre a la inversa.
Demo
Configuración Rápida
1. LMStudio
- Descarga e instala LMStudio.
- Carga el modelo
qwen/qwen3-vl-4b(o cualquier modelo de visión compatible con herramientas). - Inicia el servidor de visión en el puerto
1235:lms server start --port 1235
2. Arduino
- Abre
fruit_sorter.inoen el IDE de Arduino. - Conecta los componentes según el diagrama del circuito.
- Carga el sketch en tu Arduino UNO.
3. Python
# Instalar dependencias
pip install fastmcp opencv-python pyserial requests
# Configurar el puerto serial en server.py (ej. COM5 en Windows, /dev/ttyACM0 en Linux)
# Ejecutar el servidor MCP
fastmcp run server.py:app --transport=http
4. Usar el sistema
- En LMStudio, abre un chat con el modelo
qwen3-vl-4b. - Las herramientas MCP del servidor aparecerán automáticamente.
- Escribe "Iniciar" en el chat y el modelo activará el sistema automático de clasificación.
Estructura del Repositorio
fruit_sorter/
├── server.py # Servidor FastMCP — orquesta IA, cámara y Arduino
├── fruit_sorter.ino # Sketch de Arduino — control de servos y sensor
├── assets/
│ ├── circuit_diagram.png # Diagrama del circuito (Tinkercad)
│ ├── demo.gif # GIF con demostración del funcionamiento
│ └── maqueta.jpeg # FotografÃa de la maqueta fÃsica
└── README.md # Este archivo
