Реализация разблокировки электросамоката по 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 месяцев. Стоимость рассчитывается индивидуально.