30 breaking releases
0.37.0 | Mar 3, 2023 |
---|---|
0.35.0 | Feb 10, 2023 |
0.31.0 | Sep 21, 2022 |
0.22.0 | Jul 18, 2022 |
0.5.0 | Mar 28, 2022 |
#71 in Cryptography
199 downloads per month
475KB
10K
SLoC
ockam_transport_ble
Run:
cargo build --example 04-routing-over-ble-transport-initiator
cargo run --example 04-routing-over-ble-transport-initiator
cargo run --example 05-secure-channel-over-ble-transport-initiator
Transport Model
All Bluetooth Low Energy (BLE) devices use the Generic Attribute Profile (GATT).
BLE transports will typically be based around GATT concepts and feature the following terminology:
Client
The device initiating GATT commands and requests. For example, a computer or other device managing and collecting data from many embedded BLE devices.
Server
The device which receives GATT commands and requests. For example, a small micro-controller collecting sensor data for transmission to a Client device.
This can be confusing as we are used to the Client being the small device and the Server being the big one!
Characteristic
A data value transferred between client and server, for example, an Ockam packet containing a sensor reading.
Service
A collection of related characteristics, which operate together to perform a particular function. For instance, the Ockam UART (Universal Asynchronous Receiver/Transmitter) service contains the characteristics required to implement the receive and transmit channels.
Descriptor
A descriptor provides additional information about a characteristic. Descriptors are optional and each characteristic can have any number of descriptors.
Identifiers
Services, characteristics, and descriptors are collectively referred to as attributes and are identified by UUIDs.
Any implementer may pick a random or pseudorandom UUID for proprietary uses, but the Bluetooth SIG have reserved a range of UUIDs (xxxxxxxx-0000-1000-8000-00805F9B34FB) for standard attributes.
InteroperaBLE identifier structure
xxxxxxxx-xxxx-Mxxx-9xxx-xxxxxxxxxxxx
^ ^-------------------- Upper bits must be 10_b to represent GUID Variant 1 (i.e. 8, 9, a or b)
|------------------------- Must be 4 to represent Version 4 - rest are random
Ockam Identifiers
Ockam Identifiers are in the range:
xxxxxxxx-b19e-11e2-9e96-0800200c9a66
https://stackoverflow.com/questions/10867405/generating-v5-uuid-what-is-name-and-namespace https://www.uuidtools.com/generate/v5 https://www.uuidtools.com/decode
Assigned Identifiers
UART Service Identifier
d973f2e0-b19e-11e2-9e96-0800200c9a66
UART Transmit Characteristic Identifier
d973f2e1-b19e-11e2-9e96-0800200c9a66
NOTIFY
UART Receive Characteristic Identifier
d973f2e2-b19e-11e2-9e96-0800200c9a66
WRITE_WITHOUT_RESPONSE | WRITE
Mandatory identifier
TODO
- https://reelyactive.github.io/ble-identifier-reference.html
- https://reelyactive.github.io/diy/best-practices-ble-identifiers/
ockam -> 0ca?
Setup notes
Linux
Dependencies
apt-get install libdbus-1-dev libssl-dev
dbus permissions
Edit /etc/dbus-1/system.d/bluetooth.conf
:
<policy user="antoine">
<allow send_destination="org.bluez"/>
<allow send_interface="org.bluez.Agent1"/>
<allow send_interface="org.bluez.GattCharacteristic1"/>
<allow send_interface="org.bluez.GattDescriptor1"/>
<allow send_interface="org.freedesktop.DBus.ObjectManager"/>
<allow send_interface="org.freedesktop.DBus.Properties"/>
</policy>
Mac
To use Bluetooth on macOS Big Sur (11) or later, you need to either package your binary into an application bundle with an Info.plist
including NSBluetoothAlwaysUsageDescription
, or (for a command-line application such as the examples included with btleplug
) enable the Bluetooth permission for your terminal.
You can do the latter by going to:
System Preferences → Security & Privacy → Privacy → Bluetooth
... clicking the '+' button, and selecting 'Terminal' (or iTerm or whichever terminal application you use).
Update: There is currently a bug in macOS Monterey that prevents Bluetooth Discovery for unsigned apps (even if you have given permissions to them)
To fix:
Keychain Access => System Menu => Certificate Assistant => Create a Certificate...
Name: Self Signed Root
Identity Type: Self Signed Root
Certificate Type: Code Signing
codesign -f -o runtime --timestamp -s "Self Signed Root" target/debug/examples/04-routing-over-ble-transport-initiator
codesign --entitlements Entitlements.plist -f -o runtime --timestamp -s "Self Signed Root" 04-routing-over-ble-transport-initiator
codesign --entitlements Entitlements.plist -f -o runtime --timestamp -s "Apple Development: Antoine van Gelder (R972JJ8RXX)" 04-routing-over-ble-transport-initiator
codesign -f -o runtime --timestamp -s "Developer ID Application: Antoine van Gelder (HLUFY5JD2L)" 04-routing-over-ble-transport-initiator
codesign --entitlements Entitlements.plist -f -s "Apple Distribution" 04-routing-over-ble-transport-initiator
Dependencies
~3–70MB
~1.5M SLoC