Guante Táctil Juqiao

Configuración de Software y Controlador

Instalar el controlador USB CDC, transmitir datos de presión de 64 nodos en Python, visualizar mapas de calor de contacto e integrar con los pipelines de grabación de Orca Hand.

Resumen Inicio Rápido Configuración Software Especificaciones Recolección de Datos

📦 Instalación 🔌 Detección de Puertos 📊 API de Transmisión 🤚 Diseño de Sensores 🎨 Visualización 🤖 Interfaz ROS2 ⚙️ Calibración 🔧 Solución de Problemas

Paso 1 — Instalación

Instalar el paquete juqiao-glove

El guante se comunica a través de USB CDC serial — sin módulos del kernel, sin controladores personalizados. El paquete de Python envuelve pyserial y maneja el protocolo de marco binario.

Cualquier sistema operativo soportado El guante aparece como un dispositivo serial estándar CDC-ACM. Windows, macOS y Linux lo enumeran automáticamente con controladores inbox. No se requiere instalador de controlador del proveedor.

# Python 3.10+ recommended
pip install juqiao-glove

# Or with optional visualization extras (matplotlib, numpy)
pip install "juqiao-glove[viz]"

# Or with ROS2 bridge extras (requires ROS2 Humble or later)
pip install "juqiao-glove[ros2]"

Verifica la instalación:

python -c "import juqiao_glove; print(juqiao_glove.__version__)"
# Expected: 0.4.x or later

Paso 2 — Detección de puerto

Detectando el puerto USB

Conecta el guante a través del cable USB-C de 1.5 m. El dispositivo se enumera como un puerto serie CDC-ACM.

OS	Nombre de puerto típico	Notas
Linux	/dev/ttyACM0	Agregar usuario a dialout grupo si se deniega el permiso
macOS	/dev/tty.usbmodem*	para usar ls /dev/tty.usb* para encontrar el nombre exacto
Windows	COM3 (varía)	Verifica el Administrador de dispositivos → Puertos (COM y LPT)

Detección automática del guante desde Python:

from juqiao_glove import JuqiaoGlove

# Auto-scan all serial ports and return the first Juqiao device found
guante = JuqiaoGlove.find()   # → '/dev/ttyACM0' or 'COM3' etc.
print(guante.info()) # → firmware version, node count, sample rate

O especifica el puerto explícitamente:

guante = JuqiaoGlove(puerto="/dev/ttyACM0", baudrate=3000000)

¿Error de permisos en Linux? Ejecutar sudo usermod -aG dialout $USER luego cierra sesión y vuelve a iniciar sesión. Alternativamente, usa sudo chmod 666 /dev/ttyACM0 para una solución temporal de una sesión.

Paso 3 — API de Streaming

API de transmisión de Python

El guante transmite a 200 Hz. Cada cuadro contiene un arreglo de presión de 64 elementos (ADC de 16 bits, normalizado de 0.0 a 1.0) más una marca de tiempo.

from juqiao_glove import JuqiaoGlove

# Single-frame read
cuadro = guante.read_frame()          # float, seconds since epoch
print(cuadro.presiones)          # np.ndarray shape (64,), float32, range 0.0-1.0
print(cuadro.presiones.reshape(8, 8)) # 8×8 spatial grid

# Continuous callback stream
def on_frame(cuadro):  # stream for 5 seconds

# Or use as an iterator
con guante.stream() como cuadros:

Referencia del Objeto Cuadro

Atributo	Tipo	Descripción
marco.marca de tiempo	flotante	Tiempo de recepción del lado del host (segundos, época Unix)
marco.presiones	np.ndarray (64,)	Presión normalizada por nodo, 0.0 (ninguna) a 1.0 (máx)
marco.presiones_raw	np.ndarray (64,)	Cuentas ADC crudas de 16 bits (0–65535)
marco.contact_mask	np.ndarray (64,) bool	Verdadero donde la presión excede el umbral (por defecto 0.05)
marco.contact_nodes	Lista [usted]	Índices de nodos actualmente en contacto
marco.grasp_region	str o Ninguno	Región heurística: "palma", "pulgar", "índice", "medio", "Cancelar", "meñique", Ninguno
marco.secuencia	int	Contador de marcos (se reinicia en 65535); usar para detectar marcos perdidos

Referencia — Diseño del sensor

Diseño del sensor de 64 nodos

Los 64 taxeles están dispuestos como una matriz de fibra tejida que cubre la palma y los cinco segmentos de los dedos. Los índices de los nodos siguen un orden consistente de fila mayor en vista dorsal.

0–12

Palma (almohadilla central)

13–23

Pulgar (3 segmentos)

24–34

Dedo índice

35–45

Dedo medio

46–54

Dedo anular

55–63

Dedo meñique

# Access region slices by name
desde juqiao_glove.layout importar REGION_SLICES

# Reshape to 8×8 spatial grid (dorsal view, row-major)
grid = frame.pressures.reshape(8, 8)

Opcional — Visualización

Visualización del mapa de calor de presión

La [viz] extra instala un renderizador de mapa de calor en vivo de matplotlib útil para calibración y depuración.

# Requires: pip install "juqiao-glove[viz]"
from juqiao_glove import JuqiaoGlove  # Opens a matplotlib window; press Q to quit

Para entornos sin cabeza o revisión de datos, guarda los fotogramas como un video:

desde juqiao_glove.viz importar record_heatmap_video  # shape (N, 64) saved during recording
    salida_mp4="mapa de calor.mp4",

Opcional: ROS2

Interfaz ROS2

La juqiao_glove_ros2 el paquete publica un TactileArray mensaje a 200 Hz. Compatible con ROS2 Humble e Iron.

# Install the package (requires ROS2 to be sourced)
pip install "juqiao-glove[ros2]"

# Or build from source in your workspace
CD ~/ros2_ws/src

Inicie el nodo del controlador:

fuente /opt/ros/humble/setup.bash

# Auto-detect port
ros2 launch juqiao_glove_ros2 glove.launch.py

# Specify port explicitly
ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0

Temas publicados:

Él	Tipo de mensaje	Frecuencia	Descripción
/juqiao_glove/tactile_array	juqiao_glove_ros2/TactileArray	200 Hz	Matriz de presión completa de 64 nodos
/juqiao_glove/contact_mask	std_msgs/UInt8MultiArray	200 Hz	Contacto binario por nodo (0 o 1)
/juqiao_glove/grasp_region	std_msgs/String	200 Hz	Heurística de región activa o cadena vacía
/juqiao_glove/status	diagnostic_msgs/DiagnosticStatus	1 Hz	Versión del firmware, tasa de caída de fotogramas

Lanzamiento combinado de la mano Orca + guante

Al usar el guante junto con la mano Orca para grabación sincronizada:

# Launch Orca Hand driver
ros2 launch orca_ros2 orca_hand.launch.py port:=/dev/ttyUSB0

# In a second terminal, launch Juqiao Glove driver
ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0

# Verify synchronized topics
lista de temas de ros2 | grep -E "orca|juqiao"

Paso 4 — Calibración

Calibración de referencia

El guante se envía con calibración de fábrica. Recalibre si nota deriva de referencia (nodos leyendo valores no cero en reposo) o después de un almacenamiento prolongado.

Retire el guante antes de calibrar La calibración captura la línea base de presión cero. No use ni toque el guante durante la secuencia de calibración; colóquelo plano sobre una superficie.

# CLI calibration — lay glove flat, do not touch
python -m juqiao_glove.calibrate --port /dev/ttyACM0

# Or from Python
from juqiao_glove import JuqiaoGlove   # averages 3 seconds of idle frames
guante.save_calibration("~/.juqiao_glove_cal.json")

Cargar calibración en tiempo de ejecución:

guante = JuqiaoGlove.find()

# Now frame.pressures reflects calibrated values
marco = guante.read_frame()  # Should be ~0.0 at rest

Ajuste de umbral

El umbral de contacto predeterminado es 0.05 (5% de la escala completa). Ajuste según la tarea:

# For delicate objects (lower threshold detects light touch)
guante.set_contact_threshold(0.02)

# For heavy manipulation tasks (reduce false positives)
guante.set_contact_threshold(0.10)

# Per-region thresholds
glove.set_contact_threshold({"palma": 0.08, "pulgar": 0.03, "índice": 0.03})

Solución de problemas

Problemas Comunes

SerialException: [Errno 13] Permiso denegado: '/dev/ttyACM0'

Ejecutar sudo usermod -aG dialout $USER luego cierra sesión y vuelve a iniciar. Alternativamente: sudo chmod 666 /dev/ttyACM0 (se reinicia al desconectar).

JuqiaoGlove.find() devolvió None — no se encontró ningún dispositivo

Verifica la conexión USB. Ejecuta dmesg | tail -20 (Linux) o ls /dev/tty.usb* (macOS) para verificar que el sistema operativo enumeró el dispositivo. Prueba un puerto USB o cable diferente (el conector es USB-C pero debe ser un cable de datos, no solo de carga).

Todos los 64 nodos leen 0.0 — sin datos de presión

Llamar glove.info() para confirmar que el firmware responde. Si lo hace, verifica que el archivo de calibración no esté restando en exceso. Elimina ~/.juqiao_glove_cal.json y recalibra con el guante plano.

Deriva de línea base — los nodos leen 0.1–0.2 en reposo

Recalibrar: coloca el guante plano sin presión y ejecuta glove.calibrate_baseline(). Puede ocurrir después de cambios de temperatura o almacenamiento prolongado. Si la deriva > 0.4 con el guante plano, el tejido sensorial puede necesitar reemplazo (contacta al soporte de Juqiao).

Caídas de fotogramas — los números de secuencia se saltan

Verifica la calidad del cable USB y el puerto. Usa un puerto USB 3.0. En Linux, evita los hubs USB con otros dispositivos de alto ancho de banda. Asegúrate de que tu on_frame callback regrese rápidamente — realiza el procesamiento pesado en un hilo separado.

El nodo ROS2 se inicia pero no hay mensajes en /juqiao_glove/tactile_array

Verifica el argumento del puerto: ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0. Verificar los registros del nodo: ros2 node info /juqiao_glove_driver. Asegurarse de que dialout se aplicó la corrección del grupo al usuario que ejecuta el nodo ROS2.

Anterior ← Configuración

Siguiente Recolección de Datos →