תוכנת Juqiao Glove: מנהל התקן, Python API, ROS2

שלב 1 - התקנה

התקן את חבילת juqiao-glove

הכפפה מתקשרת באמצעות USB CDC טורית - ללא מודולי ליבה, ללא מנהלי התקנים מותאמים אישית. חבילת Python עוטפת פיסיריאל ומטפל בפרוטוקול המסגרת הבינארית.

כל מערכת הפעלה נתמכת הכפפה מופיעה כהתקן סדרתי CDC-ACM סטנדרטי. Windows, macOS ו-Linux כולם מונים את זה באופן אוטומטי עם מנהלי התקנים של תיבת הדואר הנכנס. אין צורך בהתקנה של מנהלי התקנים של ספקים.

# Python 3.10+ recommended
pip להתקין juqiao-glove

# Or with optional visualization extras (matplotlib, numpy)
התקנת pip "juqiao-glove[ כלומר]"

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

אמת את ההתקנה:

python -c "ייבוא ​​juqiao_glove; print(juqiao_glove.__version__)"
# Expected: 0.4.x or later

שלב 2 - זיהוי יציאות

זיהוי יציאת ה-USB

חבר את הכפפה באמצעות כבל USB-C באורך 1.5 מ'. ההתקן מונה כיציאה טורית CDC-ACM.

OS	שם יציאה טיפוסי	הערות
לינוקס	/dev/ttyACM0	הוסף משתמש ל חיוג קבוצה אם הרשות נדחתה
macOS	/dev/tty.usbmodem*	לְהִשְׁתַמֵשׁ ls /dev/tty.usb* כדי למצוא שם מדויק
חלונות	COM3 (משתנה)	בדוק את מנהל ההתקנים ← יציאות (COM ו-LPT)

זיהוי אוטומטי של הכפפה מ-Python:

מ-juqiao_glove ייבוא ​​JuqiaoGlove

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

או ציין את היציאה במפורש:

glove = JuqiaoGlove(port="/dev/ttyACM0", baudrate=3000000)

שגיאת הרשאת לינוקס? לָרוּץ sudo usermod -aG חיוג $USER לאחר מכן התנתק והיכנס חזרה. לחלופין, השתמש sudo chmod 666 /dev/ttyACM0 לפתרון עוקף של מפגש אחד.

שלב 3 - סטרימינג API

Python Streaming API

הכפפה זורמת ב-200 הרץ. כל מסגרת מכילה מערך לחץ של 64 אלמנטים (16 סיביות ADC, מנורמל 0.0-1.0) בתוספת חותמת זמן.

מ-juqiao_glove ייבוא JuqiaoGlove זמן ייבוא glove = JuqiaoGlove.find() glove.connect()

# Single-frame read
frame = glove.read_frame() print(frame.timestamp)          # float, seconds since epoch
print(frame.pressures)          # np.ndarray shape (64,), float32, range 0.0-1.0
print(frame.pressures.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}") glove.stream(callback=on_frame, duration=5  # stream for 5 seconds

# Or use as an iterator
עם glove.stream() כמסגרות: עבור מסגרת במסגרות: תהליך (מסגרת) אם נעשה: לשבור glove.disconnect()

הפניה לאובייקט מסגרת

תְכוּנָה	סוּג	תֵאוּר
frame.timestamp	לָצוּף	זמן קליטה בצד המארח (שניות, עידן יוניקס)
מסגרת.לחצים	np.ndarray (64,)	לחץ מנורמל לצומת, 0.0 (ללא) עד 1.0 (מקסימום)
frame.pressures_raw	np.ndarray (64,)	ספירת ADC גולמית של 16 סיביות (0–65535)
frame.contact_mask	np.ndarray (64,) bool	נכון כאשר הלחץ עולה על הסף (ברירת מחדל 0.05)
frame.contact_nodes	רשימה[int]	מדדים של צמתים שנמצאים כעת בקשר
frame.grasp_region	str או None	אזור היוריסטי: "כַּף הַיָד", "אֲגוּדָל", "מַדָד", "אֶמצַע", "טַבַּעַת", "זרת", אַף לֹא אֶחָד
frame.sequence	int	מונה מסגרת (עוטף ב-65535); השתמש כדי לזהות פריימים שנשרו

הפניה - פריסת חיישן

פריסת חיישן 64 צמתים

64 הטקסלים מסודרים כמטריצת סיבים ארוגים המכסה את כף היד ואת כל חמשת מקטעי האצבעות. מדדי הצומת עוקבים אחר סדר עיקרי של השורה בנוף הגבי.

0–12

דקל (כרד מרכזי)

13–23

אגודל (3 קטעים)

24–34

אצבע מורה

35–45

אצבע אמצעית

46–54

קְמִיצָה

55–63

אצבע זרת

# Access region slices by name
m-juqiao_glove.layout ייבוא ​​REGION_SLICES palm_nodes = frame.pressures[REGION_SLICES["palm"]] thumb_nodes = frame.pressures[REGION_SLICES["thumb"]] index_nodes = frame.pressures[REGION_"SL

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

אופציונלי - הדמיה

הדמיית מפת חום בלחץ

ה [דְהַינוּ] extra מתקין מעבד מפות חום חי matplotlib שימושי לכיול וניפוי באגים.

# Requires: pip install "juqiao-glove[viz]"
מ-juqiao_glove ייבוא JuqiaoGlove מאת juqiao_glove.viz ייבוא PressureHeatmap glove = JuqiaoGlove.find() glove.connect() כלומר = PressureHeatmap(title="Juqiao Glove — לחץ חי") viz.show(glove)  # Opens a matplotlib window; press Q to quit

עבור סביבות חסרות ראש או סקירת נתונים, שמור פריימים כסרטון:

מאת juqiao_glove.viz ייבוא ​​record_heatmap_video record_heatmap_video( input_npy="session_pressures.npy",  # shape (N, 64) saved during recording
    output_mp4="heatmap.mp4", fps=30, colormap="תופת", )

אופציונלי - ROS2

ממשק ROS2

ה juqiao_glove_ros2 החבילה מפרסמת מותאם אישית מערך מישוש הודעה בתדר 200 הרץ. תואם עם ROS2 Humble ו-Iron.

# Install the package (requires ROS2 to be sourced)
התקנת pip "juqiao-glove[ros2]"

# Or build from source in your workspace
cd ~/ros2_ws/src שיבוט git https://github.com/roboticscenter/juqiao_glove_ros2 cd ~/ros2_ws && colcon build --packages-select juqiao_glove_ros2

הפעל את צומת מנהל ההתקן:

מקור /opt/ros/humble/setup.bash מקור ~/ros2_ws/install/setup.bash

# Auto-detect port
השקת ros2 juqiao_glove_ros2 glove.launch.py

# Specify port explicitly
השקת ros2 juqiao_glove_ros2 glove.launch.py ​​port:=/dev/ttyACM0

נושאים שפורסמו:

נוֹשֵׂא	סוג הודעה	קֶצֶב	תֵאוּר
/juqiao_glove/tactile_array	juqiao_glove_ros2/TactileArray	200 הרץ	מערך לחץ מלא של 64 צמתים
/juqiao_glove/contact_mask	std_msgs/UInt8MultiArray	200 הרץ	איש קשר בינארי לכל צומת (0 או 1)
/juqiao_glove/grasp_region	std_msgs/String	200 הרץ	היוריסטית אזור פעיל או מחרוזת ריקה
/juqiao_glove/status	diagnostic_msgs/DiagnosticStatus	1 הרץ	גרסת קושחה, קצב ירידת פריים

משולבת Orca Hand + Glove Launch

בעת שימוש בכפפה לצד Orca Hand להקלטה מסונכרנת:

# Launch Orca Hand driver
ros2 הפעל orca_ros2 orca_hand.launch.py ​​port:=/dev/ttyUSB0

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

# Verify synchronized topics
רשימת נושאים ros2 | grep -E "orca|juqiao" ros2 נושא hz /juqiao_glove/tactile_array ros2 נושא hz /orca_hand/joint_states

שלב 4 - כיול

כיול קו בסיס

הכפפה נשלחת עם כיול מפעל. כיול מחדש אם אתה מבחין בסחיפה של קו הבסיס (צמתים קוראים ללא אפס בזמן מנוחה) או לאחר אחסון ממושך.

הסר את הכפפה לפני הכיול כיול לוכד את קו הבסיס של אפס לחץ. אין ללבוש או לגעת בכפפה במהלך רצף הכיול - הנח אותה שטוחה על משטח.

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

# Or from Python
m-juqiao_glove ייבוא ​​JuqiaoGlove glove = JuqiaoGlove.find() glove.connect() glove.calibrate_baseline(duration=3.0)   # averages 3 seconds of idle frames
glove.save_calibration("~/.juqiao_glove_cal.json") glove.disconnect()

טען כיול בזמן ריצה:

glove = JuqiaoGlove.find() glove.connect() glove.load_calibration("~/.juqiao_glove_cal.json")

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

כוונון סף

סף ברירת המחדל למגע הוא 0.05 (5% מקנה המידה המלא). התאם לכל משימה:

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

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

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

פתרון בעיות

בעיות נפוצות

SerialException: [שגיאה 13] הרשאה נדחתה: '/dev/ttyACM0'

לָרוּץ sudo usermod -aG dialout $USER לאחר מכן צא והיכנס חזרה. לחלופין: sudo chmod 666 /dev/ttyACM0 (מתאפס בניתוק).

JuqiaoGlove.find() החזיר ללא - לא נמצא התקן

בדוק חיבור USB. לָרוּץ dmesg | tail -20 (לינוקס) או ls /dev/tty.usb* (macOS) כדי לוודא שמערכת ההפעלה מונה את המכשיר. נסה יציאת USB או כבל אחר (המחבר הוא USB-C אך חייב להיות כבל נתונים, לא לטעינה בלבד).

כל 64 הצמתים קוראים 0.0 - ללא נתוני לחץ

שִׂיחָה glove.info() כדי לאשר שהקושחה מגיבה. אם כן, בדוק שקובץ הכיול אינו מופחת יתר על המידה. לִמְחוֹק ~/.juqiao_glove_cal.json ולכייל מחדש כשהכפפה שוכבת שטוחה.

סחיפה של קו הבסיס - צמתים קוראים 0.1-0.2 במנוחה

כיול מחדש: להניח את הכפפה שטוחה ללא לחץ ולרוץ glove.calibrate_baseline(). יכול להתרחש לאחר שינויי טמפרטורה או אחסון ממושך. אם נסחף מעל 0.4 עם כפפה שטוחה, ייתכן שיהיה צורך בהחלפה של בד החישה (צור קשר עם תמיכת Juqiao).

נפילות מסגרת - דילוג על מספרי רצף

בדוק את איכות ויציאת כבל ה-USB. השתמש ביציאת USB 3.0. ב-Linux, הימנע מרכזות USB עם התקנים אחרים בעלי רוחב פס גבוה. ודא שלך on_frame התקשרות חוזרת חוזרת במהירות - בצע עיבוד כבד בשרשור נפרד.

צומת ROS2 מתחיל אך אין הודעות ב-/juqiao_glove/tactile_array

אמת את ארגומנט היציאה: ros2 launch juqiao_glove_ros2 glove.launch.py port:=/dev/ttyACM0. בדוק את יומני הצומת: ros2 node info /juqiao_glove_driver. להבטיח את dialout תיקון הקבוצה הוחל על המשתמש המריץ את הצומת ROS2.

הגדרת תוכנה ומנהלי התקנים