Реалізація розблокування електросамоката по BLE/QR через мобільний додаток

Реалізація розблокування електросамоката по BLE/QR через мобільний додаток

Розблокування самоката в шерингу — це кілька секунд користувацького шляху, які або працюють непомітно, або ламають опит повністю. Користувач відсканував QR, додаток повинен: верифікувати токен на сервері, отримати команду розблокування, доставити її на контролер самоката по BLE — та все це за 1-2 секунди. Будь-яка затримка сприймається як баг.

QR-код: від сканування до BLE-команди

QR на самокаті кодує ідентифікатор пристрою: рядок вида https://ride.example.com/unlock?id=SC-00234 або просто SC-00234. Скануємо через ML Kit Barcode Scanning (Android/iOS) або AVFoundation AVCaptureMetadataOutput. ML Kit переважніше — працює без сітки, швидше в умовах поганого освітлення.

Після отримання ID — запрос на сервер: POST /api/v1/unlock з {scooterId, userId, sessionToken}. Сервер перевіряє баланс/підписку, резервує самокат, повертає {bleUnlockToken, bleDeviceAddress, lockServiceUUID, lockCharacteristicUUID, expiresAt}. Токен одноразовий, живе 30-60 секунд — якщо BLE-підключення не встиг, користувач отримує ошибку та ініціює новий запрос.

// iOS: сканування QR через AVFoundation
class QRScannerViewController: UIViewController, AVCaptureMetadataOutputObjectsDelegate {
    func metadataOutput(_ output: AVCaptureMetadataOutput,
                        didOutput metadataObjects: [AVMetadataObject],
                        from connection: AVCaptureConnection) {
        guard let readableObject = metadataObjects.first as? AVMetadataMachineReadableCodeObject,
              let stringValue = readableObject.stringValue,
              let scooterId = parseScooterId(from: stringValue) else { return }

        captureSession.stopRunning()
        Task { await viewModel.initiateUnlock(scooterId: scooterId) }
    }
}

BLE-розблокування: деталі реалізації

Самокати в шерингу використовують BLE-модулі на Nordic nRF52 або ESP32 з кастомним GATT-профілем. Схема проста: пишемо токен в WriteCharacteristic, контролер перевіряє HMAC-підпис токена (спільний секрет зашитий в прошивку), при совпаденні — знімає електромагнітний замок та дозволяє мотор.

// Android: запис unlock-токена в BLE characteristic
class ScooterUnlockManager(private val context: Context) {
    private var gatt: BluetoothGatt? = null

    suspend fun unlock(address: String, token: UnlockToken): UnlockResult {
        return suspendCancellableCoroutine { cont ->
            val device = bluetoothAdapter.getRemoteDevice(address)
            gatt = device.connectGatt(context, false, object : BluetoothGattCallback() {
                override fun onConnectionStateChange(g: BluetoothGatt, status: Int, state: Int) {
                    if (state == BluetoothProfile.STATE_CONNECTED) g.discoverServices()
                    else if (status != BluetoothGatt.GATT_SUCCESS) {
                        cont.resume(UnlockResult.BleConnectionFailed(status))
                    }
                }

                override fun onServicesDiscovered(g: BluetoothGatt, status: Int) {
                    val characteristic = g
                        .getService(token.serviceUUID)
                        ?.getCharacteristic(token.characteristicUUID)
                        ?: run { cont.resume(UnlockResult.ServiceNotFound); return }

                    characteristic.value = token.payload.toByteArray()
                    characteristic.writeType = BluetoothGattCharacteristic.WRITE_TYPE_DEFAULT
                    g.writeCharacteristic(characteristic)
                }

                override fun onCharacteristicWrite(g: BluetoothGatt,
                    characteristic: BluetoothGattCharacteristic, status: Int) {
                    val result = if (status == BluetoothGatt.GATT_SUCCESS)
                        UnlockResult.Success else UnlockResult.WriteFailed(status)
                    cont.resume(result)
                    g.disconnect()
                }
            }, BluetoothDevice.TRANSPORT_LE)

            cont.invokeOnCancellation { gatt?.disconnect() }
        }
    }
}

Критична деталь: TRANSPORT_LE в connectGatt — без цього флага Android може спробувати підключитися через Classic Bluetooth, що дає status=133 на пристроях BLE-only.

Проблеми в реальних умовах

Поганий BLE-сигнал. Самокат стоїть у підземному паркінгу, вокруг 20 інших самокатів з тими ж GATT-сервісами. Скануємо не все пристрої підряд, а адресно: bluetoothAdapter.getRemoteDevice(address) по MAC з серверной ответа. Це швидше, ніж сканувати окіл.

Істекший токен. Користувач відсканував QR, потім відвлекся на 2 хвилини. Токен істек. При отриманні GATT_SUCCESS на запис, але самокат не розблокувався — потрібен Notify Characteristic для ответу від контролера. Контролер пише в ответный characteristic: 0x01 (OK), 0x02 (token expired), 0x03 (already locked by another session).

Android 12+ Bluetooth permissions. BLUETOOTH_SCAN та BLUETOOTH_CONNECT — тепер runtime permissions. Якщо користувач відклав та вибрав «Не питати більше», shouldShowRequestPermissionRationale повертає false — ведемо його в Settings через Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS).

UX-деталі, які роблять різницю

Паралельний запуск сервера та BLE: як тільки отримано ответ сервера з адресою пристрою, починаємо BLE-підключення не дочекавшись фінальної анімації UI. Користувач бачит спиннер, а BLE-handshake вже йде. Економить ~300-500 мс.

Розробка модуля QR-сканування + BLE-розблокування для шеринговой платформи (iOS + Android): 3-5 тижнів. З повним флотовым бекендом (резервування, біллінг, геофенсинг): 3-5 місяців. Вартість розраховується індивідуально.