מדריך שילוב מדפסת בלוטות' לאפליקציות מובייל

מדריך חיבור מדפסת בלוטות': אינטגרציה לאפליקציות מובייל

פיתחנו מעל 20 פרויקטים של הדפסת בלוטות' לאנדרואיד ו-iOS. ואנחנו יודעים: בפועל, הסריקה נכשלת במציאת המדפסת כי היא כבר מזווגת לטלפון אחר; החיבור נופל באמצע ההדפסה ללא התראה; באנדרואיד 12+, הרשאות הבלוטות' השתנו וקוד ישן לא יעבור קומפילציה. בפרויקט אחד לרשת קמעונאית, מעל 30% מהקבלות לא הודפסו עקב נפילות חיבור — ההפסדים הגיעו ל-$500 ליום. לאחר יישום חיבור מחדש אוטומטי ותור משימות עם WorkManager, התקלות ירדו ל-2%, וקריאות התמיכה פחתו ב-60%. מאמר זה מסביר כיצד להגדיר כראוי חיבורים למדפסות תרמיות (Zebra, Bixolon, Star) ולהימנע ממלכודות נפוצות.

למה הגישה הסטנדרטית לא עובדת

הדפסת בלוטות' נראית פשוטה: מצא את המכשיר, התחבר, שלח בתים. אבל המציאות מורכבת יותר. בואו נבחן את שתי הפלטפורמות.

הגדרת חיבור בלוטות' למדפסת באנדרואיד

מדפסות תרמיות משתמשות ב-Bluetooth Classic (SPP — Serial Port Profile), לא ב-BLE. זה חשוב כי ה-APIs שונים.

Bluetooth Classic באנדרואיד משתמש ב-BluetoothAdapter, BluetoothDevice, BluetoothSocket. עם אנדרואיד 12 (targetSdk 31+), נדרשות הרשאות חדשות (ראה תיעוד הרשאות הבלוטות' של אנדרואיד):

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

ללא targetSdk 31+ עם הדגל <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> , Google Play דורש הצדקה לשימוש בסריקת בלוטות' למיקום. הדגל מציין במפורש שזה לא למטרה זו.

חיבור דרך SPP Bluetooth UUID (הפרופיל הסטנדרטי מתואר ב-מפרט SPP של בלוטות' בוויקיפדיה):

val device: BluetoothDevice = bluetoothAdapter.bondedDevices
    .firstOrNull { it.name.contains("Zebra") }
    ?: return

val socket = device.createRfcommSocketToServiceRecord(
    UUID.fromString("00001101-0000-1000-8000-00805F9B34FB") // SPP UUID
)

withContext(Dispatchers.IO) {
    socket.connect()
    val outputStream = socket.outputStream
    outputStream.write(zplData)
    outputStream.flush()
}

BLUETOOTH_SCAN עלול לזרוק neverForLocation אם המכשיר עסוק בחיבור אחר. מדפסות Zebra תומכות רק בחיבור פעיל אחד — אם המדפסת כבר מחוברת לטלפון אחר, החיבור ייכשל עם שגיאה. כדאי להציג הודעה ברורה למשתמש במקום קריסה כללית.

גילוי מכשירים. val device: BluetoothDevice = bluetoothAdapter.bondedDevices .firstOrNull { it.name.contains("Zebra") } ?: return val socket = device.createRfcommSocketToServiceRecord( UUID.fromString("00001101-0000-1000-8000-00805F9B34FB") // SPP UUID ) withContext(Dispatchers.IO) { socket.connect() val outputStream = socket.outputStream outputStream.write(zplData) outputStream.flush() } הוא אסינכרוני, לוקח עד 12 שניות, ומרוקן את הסוללה. עדיף להציג רשימה של מכשירים שכבר מזווגים (createRfcommSocketToServiceRecord) — המשתמש מזווג את המדפסת פעם אחת בהגדרות הטלפון. סרוק אחר מכשירים חדשים רק לפי בקשה מפורשת.

למה iOS דורשת הסמכת MFi

ב-iOS, מדפסות תרמיות עם Bluetooth Classic עובדות דרך מסגרת IOException — פרוטוקול MFi (Made for iPhone). המדפסת חייבת להיות בעלת הסמכת MFi. Zebra, Star Micronics ו-Bixolon מוסמכות.

import ExternalAccessory
let session = EASession(accessory: accessory, forProtocol: "com.zebra.rawport")
session?.outputStream?.schedule(in: .main, forMode: .default)
session?.outputStream?.open()
let data = zplString.data(using: .utf8)!
data.withUnsafeBytes { session?.outputStream?.write($0, maxLength: data.count) }

מחרוזת הפרוטוקול (BluetoothAdapter.startDiscovery()) היא ספציפית לספק וחייבת להיות רשומה ב-bondedDevices תחת ExternalAccessory. ללא זה, iOS לא תאפשר לפתוח את הסשן.

מדפסות BLE ב-iOS פטורות מהגבלות MFi ומשתמשות ב-import ExternalAccessory let session = EASession(accessory: accessory, forProtocol: "com.zebra.rawport") session?.outputStream?.schedule(in: .main, forMode: .default) session?.outputStream?.open() let data = zplString.data(using: .utf8)! data.withUnsafeBytes { session?.outputStream?.write($0, maxLength: data.count) } הסטנדרטי. Star Micronics mPOP וכמה דגמי Bixolon תומכים ב-BLE.

SDKs של ספקים: Zebra Link-OS (אנדרואיד/iOS) מספק סטטוס מדפסת, כיול ותמיכה ב-ZPL. Bixolon SDK (אנדרואיד) מציע פענוח סטטוס ותמיכה ב-CPCL/ESC/POS. Star SDK (אנדרואיד/iOS) תומך ב-BLE, MFi, טבלאות וגרפיקה. בחירת ה-SDK הנכון יכולה להפחית את זמן הפיתוח ב-40% ולשפר את אמינות ההדפסה.

פתרון בעיות הדפסת בלוטות'

שימוש ב-Zebra Link-OS SDK

למדפסות Zebra, ה-SDK הרשמי (com.zebra.rawport) מפשט את שכבת התעבורה (בלוטות'/TCP) ומוסיף תכונות שימושיות:

• בדיקת סטטוס המדפסת לפני ההדפסה (Info.plist)
• קבלת הגדרות (UISupportedExternalAccessoryProtocols)
• כיול מדיה
• רשימת גופנים ופורמטים במדפסת

val connection = BluetoothConnection(macAddress)
connection.open()
val printer = ZebraPrinterFactory.getInstance(connection)
val status = printer.currentStatus
if (status.isReadyToPrint) {
    printer.sendCommand(zplTemplate)
} else {
    // status.isPaused, status.isHeadOpen, status.isPaperOut — конкретная причина
    showError(getPrinterStatusMessage(status))
}
connection.close()

ללא ה-SDK, אין דרך לדעת שהמדפסת נגמרה בנייר עד שמנסים להדפיס. עם ה-SDK, CoreBluetooth נותן את הסיבה המדויקת לכשל.

חיבור מחדש אוטומטי וטיפול בשגיאות

חיבורי בלוטות' נופלים. המדפסת נכבית ונדלקת. הטלפון יוצא מטווח. יישום ללא חיבור מחדש אוטומטי הוא מקור לתלונות תמיכה.

דפוס: ב-ZSDK_ANDROID_API_x.x.aar במהלך PrinterStatus — סגור את הסוקט, המתן 1–2 שניות, ונסה להתחבר מחדש (עד 3 ניסיונות). אם לא הצלחת, שמור את המשימה לתור מקומי והודע למשתמש. SettingsGenerator.getConfigLabel() עם val connection = BluetoothConnection(macAddress) connection.open() val printer = ZebraPrinterFactory.getInstance(connection) val status = printer.currentStatus if (status.isReadyToPrint) { printer.sendCommand(zplTemplate) } else { // status.isPaused, status.isHeadOpen, status.isPaperOut — конкретная причина showError(getPrinterStatusMessage(status)) } connection.close() לניסיונות חוזרים כשהחיבור זמין שוב.

יישום חיבור מחדש אוטומטי ב-iOS

ל-iOS אין מנגנון תור מובנה, אז אנחנו משתמשים בטיימרים וניסיונות חוזרים:

1. בהפסקת זרם, אנחנו מקבלים status.isPaperOut.
2. סגור את הסשן ואחרי 2 שניות נסה לפתוח מחדש IOException.
3. אם זה נכשל, שמור את הנתונים ב-outputStream.write() והצג התראה מקומית.
4. כשהמדפסת חוזרת לטווח, המערכת מפעילה אוטומטית WorkManager, ואנחנו ממשיכים בהדפסה.

גישה זו הוכחה על 20+ פרויקטים.

מה כלול בעבודת אינטגרציית הדפסת הבלוטות' שלנו

• ניתוח דרישות ובחירת פרוטוקול (SPP, BLE, ExternalAccessory)
• הגדרת הרשאות ותצורת פרויקט
• יישום גילוי מכשירים וזיווג
• אינטגרציית SDK של ספק (Zebra, Star, Bixolon)
• לוגיקת שליחת נתונים (ZPL, CPCL, ESC/POS)
• יישום חיבור מחדש אוטומטי ותור משימות
• בדיקות על 5+ דגמי מכשירים אמיתיים
• תיעוד אינטגרציה ותמיכה במהלך ההשקה

במרכז לוגיסטי גדול, שילבנו הדפסת תוויות על 200 מדפסות Zebra ZQ520. באמצעות Zebra SDK, הגדרנו את המדפסות בתצורה המונית ויישמנו חיבור מחדש אוטומטי עם תור Redis. זמן ההדפסה לתווית ירד מ-8 ל-2 שניות (הפחתה של 75%), כלומר התהליך המאופטם מהיר פי 4 מבעבר. תדירות נפילות החיבור ירדה מ-15% ל-1.5% (שיפור פי 10), מה שהופך את המערכת לאמינה פי 10. זה הביא לחיסכון שנתי של $120,000 עקב הפחתת זמני השבתה והדפסות חוזרות.

לוחות זמנים ועלות

לוחות הזמנים ליישום אינטגרציית הדפסת בלוטות' נעים בין שבוע ל-3 שבועות, תלוי במורכבות (מספר דגמי מדפסות, דרישות SDK, סוג נתוני ההדפסה). העלות מחושבת באופן אישי לאחר ניתוח הפרויקט שלך. פרויקטים טיפוסיים מתחילים ב-$5,000.

אם אתה רוצה ליישם הדפסת בלוטות', צור קשר כדי להעריך את הפרויקט שלך. בקש ייעוץ — נעזור לך לבחור את הפרוטוקול וה-SDK הנכונים.