Skip to content

Protocol Documentation

Table of Contents

Top

rpc/common.proto

HelloRequest

infos about the client connecting to the worker

Field Type Label Description
name string client name
version string client protocol version

HelloResponse

returns general info on the worker

Field Type Label Description
name string worker name
version string protocol version
uptime uint64 uptime of the worker
supported_modes WorkerMode repeated supported modes
worker_type WorkerType worker
operating_system string OS
operating_system_version string OS Version
ble_filters_required bool if BLE filters are required for scanning
bt_mac string bluetooth adapter mac address
net_mac string netwrok adapter mac address
uid string unique identifier for each worker

SetKeystoreRequest

request to set the keystore for the bluerpc server

Field Type Label Description
data bytes keystore content
overwrite bool overwrite if exists
apply bool if we should restart the worker to apply settings

StatusMessage

status message

Field Type Label Description
code ErrorCode error status
message string error description

Void

empty message

ErrorCode

possible error codes

Name Number Description
ERROR_CODE_UNK 0 not specified
ERROR_CODE_OK 1 OK
ERROR_CODE_ERROR 2 an unknown error occured
ERROR_CODE_UNAVAILABLE 3 device not available / cannot be found
ERROR_CODE_CONNECTION_FAILED 4 failed to connect to the device
ERROR_CODE_UNKNOWN_SERVICE 5 the specified sevice is unknown
ERROR_CODE_UNKNOWN_CHARACTERISTIC 6 the specified characteristic is unknown
ERROR_CODE_UNKNOWN_DESCRIPTOR 7 the specified descriptor is unknown
ERROR_CODE_UNSUPPORTED 8 the requested action is not supported
ERROR_CODE_INVALID_CONNECTION_SETTINGS 9 supplied connection settings are invalid
ERROR_CODE_ALREADY_CONNECTED 10 device is already connected
ERROR_CODE_DEVICE_BUSY 11 another app is already using this device
ERROR_CODE_CONNECTION_REQUIRED 12 connection is required (ex: for pairing)
ERROR_CODE_PAIRING_CODE_REQUIRED 13 pairing code is required
ERROR_CODE_SCAN_FILTERS_REQUIRED 14 if scan filters are mandatory (12.0 >= macOS < 12.3, android > 8)
ERROR_CODE_SCAN_ALREADY_RUNNING 15 scan already running
ERROR_CODE_SCAN_STOPPED 16 scan stopped
ERROR_CODE_KEYSTORE_ALREADY_EXISTS 17 keystore already exists

WorkerMode

possible worker modes

Name Number Description
WORKER_MODE_UNK 0 unknown worker mode
WORKER_MODE_GATT_PASSIVE 1 can receive gatt advertisement packets
WORKER_MODE_GATT_ACTIVE 2 can connect to a device

WorkerType

types of workers supported by bluerpc

Name Number Description
WORKER_TYPE_UNKNOWN 0 unknown worker type
WORKER_TYPE_PYTHON 1 python service worker
WORKER_TYPE_ANDROID 2 android worker

Top

rpc/services.proto

BlueRPC

main service

Method Name Request Type Response Type Description
Hello HelloRequest HelloResponse first request after connection, returns general infos about the worker
SetKeystore SetKeystoreRequest StatusMessage request to set the keystore of the woker (user will need to provide the password on the worker)
BLEScanStart BLEScanRequest StatusMessage start a scanner
BLEScanStop Void StatusMessage stop the scanner
BLEConnect BLEConnectRequest BLEConnectResponse connect
BLEDisconnect BLEDevice StatusMessage disconnect
BLEPair BLEPairingRequest StatusMessage pair
BLEPairCode BLEPairingCodeRequest StatusMessage pairing code (should be called after BLEPair when ERROR_CODE_PAIRING_CODE_REQUIRED is returned)
BLEUnpair BLEDevice StatusMessage unpair
BLEGetDevices Void BLEDevicesResponse get a list of connected and paired devices
BLEGetConnectionProperties BLEDevice BLEConnectionPropertiesResponse get connection properties
BLEListServices BLEDevice BLEListServicesResponse list services, characteristics and descriptors for a device
BLEReadCharacteristic BLEReadCharacteristicRequest BLEReadResponse read characteristic
BLEReadDescriptor BLEReadDescriptorRequest BLEReadResponse read descriptor
BLEWriteCharacteristic BLEWriteCharacteristicRequest StatusMessage write characteristic
BLEWriteDescriptor BLEWriteDescriptorRequest StatusMessage write descriptor
BLENotification BLENotificationRequest StatusMessage subscribe or unsubscribe to a characteristic notification
BLEReceiveNotifications Void BLENotificationResponse stream global method to receive all the subscribed notifications
BLEReceiveDisconnect Void BLEDevice stream global method to receive disconnect notifications
BLEReceiveScan Void BLEScanResponse stream global method to receive scan results

Top

rpc/gatt.proto

BLEAdvertisementData

simple key/value message for storing advertisement data

Field Type Label Description
uuid string key (usually service uuid for BLE)
value bytes optional associated value

BLECharacteristic

BLE Characteristic representation

Field Type Label Description
uuid string characteristic UUID
properties BLEChrProperty repeated characteristic properties
descriptors BLEDescriptor repeated descriptors associated with this characteristic

BLEConnectRequest

connect request

Field Type Label Description
device BLEDevice device

BLEConnectResponse

connect response

Field Type Label Description
status StatusMessage status
mtu uint32 mtu

BLEConnectionPropertiesResponse

connection properties

Field Type Label Description
status StatusMessage status
rssi float rssi

BLEDescriptor

BLE Descriptor representation

Field Type Label Description
uuid string descriptor UUID

BLEDevice

represents the data needed to identify a bluetooth device

Field Type Label Description
mac string using the mac address
uuid string or using a UUID (macOS)

BLEDevicesResponse

message representing the state of the worker connections

Field Type Label Description
status StatusMessage status
max_connections uint32 maximum number of simultaneous connections allowed (0 if undefined)
connected_devices BLEDevice repeated list of currently connected devices
reliable_paired_list bool if the paired devices list is reliable (=query to the bluetooth system, != stored list of previous pairings)
paired_devices BLEDevice repeated list of paired devices

BLEListServicesResponse

list of Services/Characteristics/Descriptors for a specific device

Field Type Label Description
status StatusMessage status
device BLEDevice device
services BLEService repeated services

BLENotificationRequest

subscribe/unsubscribe to a characteristic notification

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
uuid string characteristic uuid
subscribe bool subscribe

BLENotificationResponse

characteristic notification data

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
uuid string characteristic uuid
data bytes data

BLEPairingCodeRequest

request for pairing with code

Field Type Label Description
device BLEDevice device
code string code

BLEPairingRequest

pairing request

Field Type Label Description
device BLEDevice device

BLEReadCharacteristicRequest

read characteristic

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
uuid string characteristic uuid

BLEReadDescriptorRequest

read descriptor

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
characteristic_uuid string characteristic uuild
uuid string descriptor uuid

BLEReadResponse

generic message for returning data

Field Type Label Description
status StatusMessage status
data bytes data

BLEScanFilter

device scan filter

Field Type Label Description
type BLEScanFilterType type of filter
value string filtering data

BLEScanRequest

device scan configuration

Field Type Label Description
interval uint64 scanning interval in miliseconds
active bool Passive or Active scanning
filters BLEScanFilter repeated scanning filters (a device must match at least one of these filters, all devices are returned if no filters are specified)
merge_filters bool if existing filters shoud be kept or overriden

BLEScanResponse

message representing a scan result for a device or more

Field Type Label Description
status StatusMessage status
data BLEScanResponseData repeated data

BLEScanResponseData

message representing a scan result for a device

Field Type Label Description
device BLEDevice device information
rssi float RSSI
txpwr float TX Power
service_uuids string repeated discovered services
service_data BLEAdvertisementData repeated advertisement data
manufacturer_data BLEAdvertisementData repeated advertisement data
time uint64 timestamp of the discovery
name string name of the device

BLEService

BLE Service representation

Field Type Label Description
uuid string service UUID
characteristics BLECharacteristic repeated characteristics associated with this service

BLEWriteCharacteristicRequest

write characteristic

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
uuid string characteristic uuid
data bytes data
mode BLEWriteMode mode

BLEWriteDescriptorRequest

read descriptor

Field Type Label Description
device BLEDevice device
service_uuid string service uuid
characteristic_uuid string characteristic uuild
uuid string descriptor uuid
data bytes data

BLEChrProperty

BLE characteristics properties

Name Number Description
BLE_CHR_PROPERTY_UNK 0 unknown characteristic
BLE_CHR_PROPERTY_READ 1 read property
BLE_CHR_PROPERTY_WRITE 2 write property
BLE_CHR_PROPERTY_NOTIFY 3 notify property
BLE_CHR_PROPERTY_BROADCAST 4 broadcast property
BLE_CHR_PROPERTY_EXTENDED_PROPS 5 extended properties
BLE_CHR_PROPERTY_INDICATE 6 indicate property
BLE_CHR_PROPERTY_SIGNED_WRITE 7 signed write property
BLE_CHR_PROPERTY_WRITE_NO_RESPONSE 8 write without response property

BLEScanFilterType

scan filter types

Name Number Description
BLE_SCAN_FILTER_TYPE_UNKNOWN 0 unknown
BLE_SCAN_FILTER_TYPE_MAC 1 filter by mac address
BLE_SCAN_FILTER_TYPE_NAME 2 filter by device name
BLE_SCAN_FILTER_TYPE_UUID 3 filter by service UUID (only from the advertisement data)

BLEWriteMode

BLE writing mode

Name Number Description
BLE_WRITE_MODE_UNK 0 default write mode
BLE_WRITE_MODE_NO_RESPONSE 1 write with no response
BLE_WRITE_MODE_SIGNED 2 signed write

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)