SwiftでBluetoothサーマルプリンターをコントロール！CoreBluetooth実践ガイド🖨️

はじめに (対象読者・この記事でわかること)

この記事は、iOSアプリ開発に携わる方、Swiftを使ってBluetoothデバイス連携を実装したいと考えている方、特にBluetooth接続のサーマルプリンターを自作アプリからコントロールしたい開発者の方を対象としています。プログラミング初学者の方でも、CoreBluetoothの基本的な概念から段階的に理解できるよう構成しています。

この記事を読むことで、SwiftのCoreBluetoothフレームワークを使ったBluetooth Low Energy (BLE) デバイスの基本的な接続・通信方法がわかります。さらに、サーマルプリンターに特化したESC/POSコマンドの生成と送信方法を学び、最終的にはiOSアプリから実際にテキストを印刷できるようになることを目指します。外部ハードウェアと連携するアプリ開発の第一歩として、ぜひこの記事を活用してください。

前提知識

この記事を読み進める上で、以下の知識があるとスムーズです。 - Swiftの基本的な文法（変数、定数、関数、クラス、プロトコルなど） - iOSアプリ開発の基本的な知識（Xcodeの操作、UIKitまたはSwiftUIでのUI構築） - Bluetooth Low Energy (BLE) の基本的な概念（Central、Peripheral、Service、Characteristic）

SwiftでBluetoothプリンターを制御する魅力と課題

近年、モバイル決済システムやPOS (Point of Sale) アプリケーションの普及に伴い、スマートフォンやタブレットから直接レシートや伝票を印刷するニーズが高まっています。SwiftとCoreBluetoothフレームワークを活用することで、iOSデバイスから手軽にBluetooth接続のサーマルプリンターを制御し、このようなアプリケーションを実現することが可能になります。

サーマルプリンターは、手軽に入手でき、バッテリー駆動可能な小型モデルも多いため、移動販売やイベントなど、様々なシーンでの活用が期待されます。しかし、プリンターとの通信には、Bluetooth LEの基本的な知識に加え、プリンター固有の制御コマンドである「ESC/POSコマンド」を理解し、適切にデータをエンコードして送信する必要があります。CoreBluetoothは非同期処理が多く、状態管理も複雑になりがちなので、一つずつ順を追って実装していくことが重要です。この記事では、これらの複雑な要素を体系的に解説し、具体的なコード例を通じて実践的なスキルを習得していただくことを目指します。

CoreBluetoothを用いたサーマルプリンター制御の実装ステップ

ここでは、SwiftのCoreBluetoothフレームワークを使ってBluetoothサーマルプリンターを制御する具体的な手順を解説します。CoreBluetoothは非同期処理が中心となるため、デリゲートメソッドを適切に実装し、Bluetoothデバイスの状態変化に応じて処理を進めていくことが重要です。

ステップ1: Central Managerの準備とデバイススキャン

まず、Bluetooth通信を制御する中心となるCBCentralManagerのインスタンスを生成し、BLEデバイスのスキャンを開始します。

Swift

import CoreBluetooth
import UIKit

class BluetoothPrinterManager: NSObject, CBCentralManagerDelegate, CBPeripheralDelegate {

    var centralManager: CBCentralManager!
    var discoveredPeripherals: [CBPeripheral] = []
    var connectedPeripheral: CBPeripheral?
    var printableCharacteristic: CBCharacteristic?

    override init() {
        super.init()
        centralManager = CBCentralManager(delegate: self, queue: nil)
    }

    // MARK: - CBCentralManagerDelegate

    // CentralManagerの状態が更新されたときに呼ばれる
    func centralManagerDidUpdateState(_ central: CBCentralManager) {
        switch central.state {
        case .poweredOn:
            print("Bluetooth is powered on. Starting scan...")
            // プリンターのサービスUUIDが分かっている場合は指定することで、
            // 該当するデバイスのみをスキャン対象にできます。
            // ここでは特定のUUIDを指定せず、全てのスキャン対象を表示します。
            // 実際のプリンターでは、マニュアル等でサービスUUIDを確認してください。
            centralManager.scanForPeripherals(withServices: nil, options: nil)
        case .poweredOff:
            print("Bluetooth is powered off.")
        case .unsupported:
            print("Bluetooth is not supported on this device.")
        case .unauthorized:
            print("Bluetooth is unauthorized. Check Privacy Settings.")
        case .resetting:
            print("Bluetooth is resetting.")
        case .unknown:
            print("Bluetooth state is unknown.")
        @unknown default:
            print("Unknown Bluetooth state.")
        }
    }

    // デバイスが発見されたときに呼ばれる
    func centralManager(_ central: CBCentralManager, didDiscover peripheral: CBPeripheral, advertisementData: [String : Any], rssi RSSI: NSNumber) {
        if !discoveredPeripherals.contains(where: { $0.identifier == peripheral.identifier }) {
            discoveredPeripherals.append(peripheral)
            print("Discovered peripheral: \(peripheral.name ?? "Unknown") (\(peripheral.identifier))")
            // ここで目的のプリンターを特定し、接続を試みる
            // 例: 名前が特定の文字列を含むプリンターに接続
            if let name = peripheral.name, name.lowercased().contains("printer") { // プリンター名に合わせて変更
                print("Found target printer: \(name). Connecting...")
                centralManager.stopScan()
                connectedPeripheral = peripheral
                connectedPeripheral?.delegate = self
                centralManager.connect(peripheral, options: nil)
            }
        }
    }
}

CBCentralManagerを初期化する際にdelegateを設定し、centralManagerDidUpdateStateメソッドでBluetoothの状態が.poweredOnになったらスキャンを開始します。centralManager(_:didDiscover:advertisementData:rssi:)メソッドで発見されたデバイスをリストアップし、目的のプリンターが見つかったらスキャンを停止して接続を試みます。

ステップ2: プリンターへの接続とサービス・キャラクタリスティックの発見

デバイスへの接続が成功したら、次にそのデバイスが提供するサービスとキャラクタリスティックを発見します。印刷可能なキャラクタリスティックを見つけることが目標です。

Swift

extension BluetoothPrinterManager {
    // デバイスへの接続が成功したときに呼ばれる
    func centralManager(_ central: CBCentralManager, didConnect peripheral: CBPeripheral) {
        print("Connected to \(peripheral.name ?? "Unknown peripheral")")
        // サービスを発見
        // 多くのサーマルプリンターは、"FFE0"または"18F0"のようなカスタムサービスUUIDを使用します。
        // マニュアルで確認できない場合、nilで全てのサービスをスキャンすることもできます。
        peripheral.discoverServices(nil)
    }

    // デバイスへの接続が失敗したときに呼ばれる
    func centralManager(_ central: CBCentralManager, didFailToConnect peripheral: CBPeripheral, error: Error?) {
        print("Failed to connect to \(peripheral.name ?? "Unknown peripheral"): \(error?.localizedDescription ?? "Unknown error")")
    }

    // サービスが発見されたときに呼ばれる
    func peripheral(_ peripheral: CBPeripheral, didDiscoverServices error: Error?) {
        guard error == nil else {
            print("Error discovering services: \(error!.localizedDescription)")
            return
        }

        for service in peripheral.services ?? [] {
            print("Discovered service: \(service.uuid)")
            // 印刷に使うキャラクタリスティックを含むサービスを特定し、キャラクタリスティックを発見
            // 例: サービスUUIDが"FFE0"の場合
            if service.uuid == CBUUID(string: "FFE0") { // 多くのサーマルプリンターが使用するサービスUUID
                peripheral.discoverCharacteristics(nil, for: service)
            }
        }
    }

    // キャラクタリスティックが発見されたときに呼ばれる
    func peripheral(_ peripheral: CBPeripheral, didDiscoverCharacteristicsFor service: CBService, error: Error?) {
        guard error == nil else {
            print("Error discovering characteristics: \(error!.localizedDescription)")
            return
        }

        for characteristic in service.characteristics ?? [] {
            print("Discovered characteristic: \(characteristic.uuid) (Properties: \(characteristic.properties))")
            // 印刷に使うキャラクタリスティックを特定
            // 多くのサーマルプリンターは、Writeプロパティを持つ"FFE1"のようなキャラクタリスティックを使用します。
            if characteristic.uuid == CBUUID(string: "FFE1") && characteristic.properties.contains(.write) { // 印刷コマンドを書き込むキャラクタリスティック
                printableCharacteristic = characteristic
                print("Found printable characteristic: \(characteristic.uuid)")
                // データの通知が必要な場合は、ここでsetNotifyValue(true, for:)を呼び出します
                // peripheral.setNotifyValue(true, for: characteristic)
            }
        }

        if printableCharacteristic == nil {
            print("Warning: No printable characteristic found for service \(service.uuid)")
        }
    }
}

centralManager(_:didConnect:)が呼ばれたら、discoverServices(nil)で全てのサービスを発見します。その後、peripheral(_:didDiscoverServices:)で目的のサービス（例: UUID "FFE0"）を見つけ、そのサービスに含まれるキャラクタリスティックをdiscoverCharacteristics(nil, for: service)で発見します。最終的に、peripheral(_:didDiscoverCharacteristicsFor:error:)で書き込み可能なキャラクタリスティック（例: UUID "FFE1"）をprintableCharacteristicに保持します。

ステップ3: 印刷データの送信（ESC/POSコマンド）

サーマルプリンターの制御には、一般的にESC/POSコマンドが使用されます。これは、プリンターに特定の動作（テキスト印刷、改行、文字サイズ変更、画像印刷など）を指示するためのバイトシーケンスです。

Swift

extension BluetoothPrinterManager {
    // 印刷データを送信するメソッド
    func printText(_ text: String) {
        guard let peripheral = connectedPeripheral,
              let characteristic = printableCharacteristic else {
            print("Not connected to printer or printable characteristic not found.")
            return
        }

        // ESC/POSコマンドの生成例
        var printData = Data()

        // 初期化コマンド (ESC @)
        printData.append(Data([0x1B, 0x40]))

        // 中央揃え (ESC a 1)
        printData.append(Data([0x1B, 0x61, 0x01]))

        // テキストをUTF-8でエンコードして追加
        // プリンターによってはShift-JISなど、異なるエンコーディングが必要な場合があります
        if let textData = text.data(using: .utf8) { // 必要に応じて .shiftJIS に変更
            printData.append(textData)
        } else {
            print("Failed to encode text to data.")
            return
        }

        // 改行コード (LF) を追加
        printData.append(Data([0x0A]))

        // カットコマンド (GS V 0) またはフィード＆カット (GS V 1)
        // printData.append(Data([0x1D, 0x56, 0x00])) // フルカット
        printData.append(Data([0x1D, 0x56, 0x01])) // フィード後にフルカット

        // データをプリンターに書き込む
        // .withoutResponse: 書き込みが成功したかどうかの応答を待たない（高速だが信頼性は低い）
        // .withResponse: 書き込みが成功したかどうかの応答を待つ（低速だが信頼性が高い）
        // 多くのプリンターでは .withoutResponse で十分です。
        peripheral.writeValue(printData, for: characteristic, type: .withoutResponse)
        print("Sent print data to printer.")
    }

    // 書き込み完了時に呼ばれる (type: .withResponse の場合)
    func peripheral(_ peripheral: CBPeripheral, didWriteValueFor characteristic: CBCharacteristic, error: Error?) {
        if let error = error {
            print("Error writing value: \(error.localizedDescription)")
        } else {
            print("Successfully wrote value to characteristic \(characteristic.uuid)")
        }
    }

    // アプリケーションが終了する前に接続を切断
    func disconnect() {
        if let peripheral = connectedPeripheral {
            centralManager.cancelPeripheralConnection(peripheral)
            print("Disconnected from peripheral.")
        }
    }

    // 切断されたときに呼ばれる
    func centralManager(_ central: CBCentralManager, didDisconnectPeripheral peripheral: CBPeripheral, error: Error?) {
        print("Disconnected from \(peripheral.name ?? "Unknown")")
        // 必要に応じて再接続処理など
        connectedPeripheral = nil
        printableCharacteristic = nil
        // centralManager.scanForPeripherals(withServices: nil, options: nil) // 再スキャン
    }
}

printTextメソッドでは、まずDataオブジェクトを初期化し、ESC/POSコマンドをバイト配列として追加していきます。テキストは指定されたエンコーディング（多くの場合はUTF-8ですが、プリンターによってはShift-JISが必要な場合もあります）でDataに変換します。最後に、peripheral.writeValue(_:for:type:)メソッドを使って、準備したデータをprintableCharacteristicに書き込みます。typeパラメータは、プリンターからの応答を待つかどうかを制御します。通常は.withoutResponseで十分です。

ハマった点やエラー解決

Bluetooth LEデバイス連携では、予期せぬ問題に遭遇することがよくあります。以下によくあるハマりどころとその解決策をまとめました。

1. CBCentralManager の状態が .poweredOn にならない:

   • 問題: アプリ実行時にBluetoothが利用できない、または権限がない。
   • 解決策: iOSの設定アプリでBluetoothがオンになっていることを確認します。また、Info.plistにPrivacy - Bluetooth Peripheral Usage Description (キー: NSBluetoothPeripheralUsageDescription) を追加し、Bluetoothを使用する理由をユーザーに伝える記述を入れます。この記述がないと、iOS 13以降でアプリがクラッシュする可能性があります。

2. 目的のプリンターがスキャンされない:

   • 問題: centralManager(_:didDiscover:...)が呼ばれない、または目的のプリンターが表示されない。
   • 解決策:
     • プリンターがペアリングモードまたはアドバタイズモードになっているか確認します。
     • スキャン時にwithServices: nilではなく、プリンターのマニュアルに記載されている正確なサービスUUIDを指定すると、見つけやすくなることがあります。
     • 他のデバイスと接続されていないか確認し、一度切断します。

3. プリンターへの接続が失敗する、またはすぐに切断される:

   • 問題: centralManager(_:didFailToConnect:...)が呼ばれる、またはcentralManager(_:didDisconnectPeripheral:...)が予期せず呼ばれる。
   • 解決策:
     • 接続を試みるCBPeripheralインスタンスを、クラスのプロパティとして保持し続ける必要があります。ローカル変数として宣言すると、参照が失われ、ガベージコレクションによって切断されてしまうことがあります。
     • プリンターのバッテリー残量が十分か確認します。
     • CoreBluetoothのデリゲートメソッド内で過度な処理を行っていないか確認します。

4. サービスやキャラクタリスティックが発見できない:

   • 問題: peripheral(_:didDiscoverServices:...) や peripheral(_:didDiscoverCharacteristicsFor:...) で期待するUUIDが見つからない。
   • 解決策:
     • プリンターのマニュアルで、使用するサービスUUIDとキャラクタリスティックUUIDを正確に確認します。多くのサーマルプリンターは標準的なUUIDとは異なるカスタムUUIDを使用します。
     • discoverServices(nil) と discoverCharacteristics(nil, for: service) で、まずは全てのサービスとキャラクタリスティックをスキャンし、ログに出力して正しいUUIDを特定します。

5. 印刷が正しく行われない（文字化け、一部しか印刷されないなど）:

   • 問題: writeValue でデータを送信しても、期待通りの印刷結果が得られない。
   • 解決策:
     • エンコーディング: テキストデータをDataに変換する際のエンコーディング（例: .utf8, .shiftJIS）がプリンターの対応するものと一致しているか確認します。特に日本語を扱う場合は重要です。
     • ESC/POSコマンド: 送信するESC/POSコマンドがプリンターの仕様に合致しているか再確認します。コマンドのバイト列が正確であるか、不足がないかなどを確認します。
     • データ分割: 一度に送信できるデータのサイズには制限がある場合があります（MTU: Maximum Transmission Unit）。非常に長いテキストや画像を印刷する場合、データをチャンクに分割して送信する必要があります。通常、20バイト程度が安全な上限とされますが、peripheral.maximumWriteValueLength(for: .withoutResponse)で確認できます。

解決策

上記の問題に対する解決策は、CoreBluetoothのライフサイクル管理とプリンター固有の仕様理解に集約されます。

• ライフサイクル管理の徹底: CBCentralManager と CBPeripheral のインスタンスを適切に保持し、デリゲートメソッドを網羅的に実装して、Bluetoothの状態変化を正確に追跡することが重要です。
• UUIDの特定: プリンターのマニュアルや既存のサンプルコードを参考に、正確なサービスUUIDとキャラクタリスティックUUIDを特定します。不明な場合は、nilを指定して全スキャンを行い、ログから推測することも可能です。
• エンコーディングとコマンド: プリンターの仕様書を参照し、適切なテキストエンコーディングとESC/POSコマンドを使用します。特に、改行コードや文字コードの指定は、正常な印刷のために不可欠です。
• エラーハンドリング: centralManager(_:didFailToConnect:...)やperipheral(_:didWriteValueFor:error:)などのエラーデリゲートを実装し、発生したエラーを適切にログ出力してデバッグの手がかりとします。

これらの点を意識して実装を進めることで、Bluetoothサーマルプリンターの制御をより確実に実現できるでしょう。

まとめ

本記事では、SwiftのCoreBluetoothフレームワークを活用してBluetooth接続のサーマルプリンターをコントロールする方法を解説しました。

• CoreBluetoothの基本: CBCentralManagerによるデバイススキャン、CBPeripheralによる接続、サービス・キャラクタリスティックの発見という一連の流れを学びました。
• ESC/POSコマンド: プリンター固有の制御コマンドであるESC/POSコマンドの生成と、バイトデータへの変換、そしてwriteValueメソッドでの送信方法を理解しました。
• 実践的な課題解決: 実装時に遭遇しがちな「ハマった点」とその「解決策」を具体的に提示し、より堅牢な実装のためのヒントを提供しました。

この記事を通して、Swiftでの外部ハードウェア連携、特にBluetooth LEデバイスとの通信の基礎を習得し、POSシステムやモバイル決済、チケット発行など、様々なアプリケーションへの応用が可能になったことでしょう。

今後は、画像データの印刷、プリンターのステータス取得、より複雑なレイアウト制御、あるいはエラーハンドリングの強化といった発展的な内容についても探求していくと、さらに高度なプリンター連携を実現できます。

参考資料

• Apple Developer Documentation - Core Bluetooth
• ESC/POS Command Reference (EPSON)
• SwiftとCoreBluetoothでBLEデバイスと通信する基礎