Juqiao Glove-Software: Treiber, Python-API, ROS2

Schritt 1 – Installation

Installieren Sie das juqiao-glove-Paket

Der Handschuh kommuniziert über USB CDC seriell – keine Kernel-Module, keine benutzerdefinierten Treiber. Das Python-Paket wird umschlossen pyserial und verwaltet das Binärrahmenprotokoll.

Jedes Betriebssystem wird unterstützt Der Handschuh erscheint als standardmäßiges serielles CDC-ACM-Gerät. Windows, macOS und Linux zählen es alle automatisch mit Posteingangstreibern auf. Kein Treiberinstallationsprogramm des Anbieters erforderlich.

# Python 3.10+ recommended
pip install juqiao-handschuh

# 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]“

Überprüfen Sie die Installation:

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

Schritt 2 – Porterkennung

Erkennen des USB-Ports

Schließen Sie den Handschuh über das 1,5 m lange USB-C-Kabel an. Das Gerät wird als serieller CDC-ACM-Port aufgeführt.

OS	Typischer Portname	Notizen
Linux	/dev/ttyACM0	Benutzer hinzufügen zu Auswählen Gruppe, wenn die Erlaubnis verweigert wird
macOS	/dev/tty.usbmodem*	Verwenden ls /dev/tty.usb* um den genauen Namen zu finden
Windows	COM3 (variiert)	Überprüfen Sie den Geräte-Manager → Ports (COM & LPT)

Den Handschuh automatisch von Python aus erkennen:

aus juqiao_glove JuqiaoGlove importieren

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

Oder geben Sie den Port explizit an:

Handschuh = JuqiaoGlove(port="/dev/ttyACM0", Baudrate=3000000)

Linux-Berechtigungsfehler? Laufen sudo usermod -aG dialout $USER Melden Sie sich dann ab und wieder an. Alternativ können Sie auch verwenden sudo chmod 666 /dev/ttyACM0 für eine Problemumgehung in einer Sitzung.

Schritt 3 – Streaming-API

Python-Streaming-API

Der Handschuh streamt mit 200 Hz. Jeder Frame enthält ein Druckarray mit 64 Elementen (16-Bit-ADC, normalisiert 0,0–1,0) sowie einen Zeitstempel.

aus juqiao_glove JuqiaoGlove importieren Importzeit Handschuh = JuqiaoGlove.find() handschuh.connect()

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

# Continuous callback stream
def on_frame(frame): max_node = Frame.Pressures.argmax() print(f"t={frame.timestamp:.4f} Peak_node={max_node} val={Frame.Pressures[max_node]:.3f}") handschuh.stream(callback=on_frame, duration=5.0)  # stream for 5 seconds

# Or use as an iterator
mit Glove.stream() als Frames: für Rahmen in Rahmen: Prozess(Rahmen) falls erledigt: Pause handschuh.disconnect()

Frame-Objektreferenz

Attribut	Typ	Beschreibung
Frame.Zeitstempel	schweben	Hostseitige Empfangszeit (Sekunden, Unix-Epoche)
Rahmendrücke	np.ndarray (64,)	Normalisierter Druck pro Knoten, 0,0 (kein) bis 1,0 (maximal)
Frame.Pressures_raw	np.ndarray (64,)	Rohe 16-Bit-ADC-Zählungen (0–65535)
frame.contact_mask	np.ndarray (64,) bool	True, wenn der Druck den Schwellenwert überschreitet (Standard 0,05)
frame.contact_nodes	Liste[int]	Indizes der Knoten, die derzeit in Kontakt sind
frame.grasp_region	str oder None	Heuristischer Bereich: „Palme“, "Daumen", "Index", "Nicht", "Ring", „kleiner Finger“, Keiner
Frame.Sequenz	int	Bildzähler (umbricht bei 65535); Verwenden Sie diese Option, um ausgelassene Frames zu erkennen

Referenz – Sensoranordnung

64-Knoten-Sensorlayout

Die 64 Taxel sind als gewebte Fasermatrix angeordnet, die die Handfläche und alle fünf Fingersegmente bedeckt. Knotenindizes folgen einer konsistenten Reihen-Hauptreihenfolge in der Rückenansicht.

0–12

Handfläche (zentrales Polster)

13–23

Daumen (3 Segmente)

24–34

Zeigefinger

35–45

Mittelfinger

46–54

Ringfinger

55–63

Kleiner Finger

# Access region slices by name
aus juqiao_glove.layout REGION_SLICES importieren palm_nodes = frame.pressions[REGION_SLICES["palm"]] thumb_nodes = frame.pressions[REGION_SLICES["thumb"]] index_nodes = Frame.Pressures[REGION_SLICES["Index"]]

# Reshape to 8×8 spatial grid (dorsal view, row-major)
Grid = Frame.Pressures.reshape(8, 8)

Optional – Visualisierung

Druck-Heatmap-Visualisierung

Der [nämlich] Extra installiert einen Live-Matplotlib-Heatmap-Renderer, der für die Kalibrierung und das Debuggen nützlich ist.

# Requires: pip install "juqiao-glove[viz]"
aus juqiao_glove JuqiaoGlove importieren Importieren Sie PressureHeatmap aus juqiao_glove.viz Handschuh = JuqiaoGlove.find() handschuh.connect() viz = PressureHeatmap(title="Juqiao Glove — Live Pressure") nämlichshow(Handschuh)  # Opens a matplotlib window; press Q to quit

Speichern Sie Frames für Headless-Umgebungen oder zur Datenüberprüfung als Video:

aus juqiao_glove.viz record_heatmap_video importieren record_heatmap_video( input_npy="session_pressions.npy",  # shape (N, 64) saved during recording
    Output_mp4="heatmap.mp4", fps=30, colormap="inferno", )

Optional – ROS2

ROS2-Schnittstelle

Der juqiao_glove_ros2 Paket veröffentlicht eine benutzerdefinierte TaktileArray Nachricht mit 200 Hz. Kompatibel mit ROS2 Humble und 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 Git-Klon https://github.com/roboticscenter/juqiao_glove_ros2 cd ~/ros2_ws && colcon build --packages-select juqiao_glove_ros2

Starten Sie den Treiberknoten:

Quelle /opt/ros/humble/setup.bash Quelle ~/ros2_ws/install/setup.bash

# Auto-detect port
ros2 startet juqiao_glove_ros2 handschuh.launch.py

# Specify port explicitly
ros2 startet juqiao_glove_ros2 handschuh.launch.py ​​port:=/dev/ttyACM0

Veröffentlichte Themen:

Thema	Nachrichtentyp	Rate	Beschreibung
/juqiao_glove/tactile_array	juqiao_glove_ros2/TactileArray	200 Hz	Vollständiges Druckarray mit 64 Knoten
/juqiao_glove/contact_mask	std_msgs/UInt8MultiArray	200 Hz	Binärkontakt pro Knoten (0 oder 1)
/juqiao_glove/grasp_region	std_msgs/String	200 Hz	Heuristik des aktiven Bereichs oder leere Zeichenfolge
/juqiao_glove/status	Diagnostic_msgs/DiagnosticStatus	1 Hz	Firmware-Version, Frame-Drop-Rate

Kombinierter Orca-Hand- und Handschuhstart

Bei Verwendung des Handschuhs zusammen mit der Orca-Hand für synchronisierte Aufnahmen:

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

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

# Verify synchronized topics
ros2-Themenliste | grep -E "orca|juqiao" ros2 Thema hz /juqiao_glove/tactile_array ros2 Thema hz /orca_hand/joint_states

Schritt 4 – Kalibrierung

Basiskalibrierung

Der Handschuh wird mit Werkskalibrierung geliefert. Führen Sie eine Neukalibrierung durch, wenn Sie eine Abweichung der Basislinie bemerken (Knoten zeigen im Ruhezustand einen Wert ungleich Null an) oder nach längerer Lagerung.

Ziehen Sie vor der Kalibrierung den Handschuh aus Die Kalibrierung erfasst die Nulldruck-Basislinie. Tragen oder berühren Sie den Handschuh während der Kalibrierungssequenz nicht – legen Sie ihn flach auf eine Oberfläche.

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

# Or from Python
aus juqiao_glove JuqiaoGlove importieren Handschuh = JuqiaoGlove.find() handschuh.connect() handschuh.kalibrieren_baseline(duration=3.0)   # averages 3 seconds of idle frames
Handschuh.save_Kalibrierung("~/.juqiao_glove_cal.json") handschuh.disconnect()

Kalibrierung zur Laufzeit laden:

Handschuh = JuqiaoGlove.find() handschuh.connect() handschuh.load_kalibrierung("~/.juqiao_glove_cal.json")

# Now frame.pressures reflects calibrated values
Frame = Handschuh.read_frame() print(frame.pressions.max())  # Should be ~0.0 at rest

Schwellenwertoptimierung

Der standardmäßige Kontaktschwellenwert beträgt 0,05 (5 % des Skalenendwerts). Pro Aufgabe anpassen:

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

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

# Per-region thresholds
handschuh.set_contact_threshold({"palm": 0.08, "thumb": 0.03, "index": 0.03})

Fehlerbehebung

Häufige Probleme

SerialException: [Errno 13] Berechtigung verweigert: „/dev/ttyACM0“

Laufen sudo usermod -aG dialout $USER Melden Sie sich dann ab und wieder an. Alternativ: sudo chmod 666 /dev/ttyACM0 (wird beim Herausziehen des Netzsteckers zurückgesetzt).

JuqiaoGlove.find() hat None zurückgegeben – kein Gerät gefunden

Überprüfen Sie die USB-Verbindung. Laufen dmesg | tail -20 (Linux) bzw ls /dev/tty.usb* (macOS), um zu überprüfen, ob das Betriebssystem das Gerät aufgelistet hat. Versuchen Sie es mit einem anderen USB-Anschluss oder -Kabel (der Anschluss ist USB-C, muss aber ein Datenkabel sein, kein reines Ladekabel).

Alle 64 Knoten zeigen 0,0 an – keine Druckdaten

Anruf glove.info() um zu bestätigen, dass die Firmware antwortet. Wenn dies der Fall ist, überprüfen Sie, ob die Kalibrierungsdatei nicht zu stark subtrahiert. Löschen ~/.juqiao_glove_cal.json und neu kalibrieren, während der Handschuh flach liegt.

Basisliniendrift – Knoten zeigen im Ruhezustand 0,1–0,2 an

Neu kalibrieren: Handschuh ohne Druck flach hinlegen und laufen lassen glove.calibrate_baseline(). Kann nach Temperaturänderungen oder längerer Lagerung auftreten. Wenn die Drift bei flachem Handschuh > 0,4 ist, muss das Sensorgewebe möglicherweise ausgetauscht werden (wenden Sie sich an den Juqiao-Support).

Frame-Drops – Sequenznummern werden übersprungen

Überprüfen Sie die Qualität und den Anschluss des USB-Kabels. Verwenden Sie einen USB 3.0-Anschluss. Vermeiden Sie unter Linux USB-Hubs mit anderen Geräten mit hoher Bandbreite. Stellen Sie sicher, dass Ihre on_frame Rückruf kehrt schnell zurück – umfangreiche Verarbeitung in einem separaten Thread durchführen.

ROS2-Knoten startet, aber keine Nachrichten auf /juqiao_glove/tactile_array

Überprüfen Sie das Port-Argument: ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0. Überprüfen Sie die Knotenprotokolle: ros2 node info /juqiao_glove_driver. Stellen Sie sicher, dass dialout Der Gruppenfix wurde auf den Benutzer angewendet, der den ROS2-Knoten ausführt.

Software- und Treiber-Setup