Add documentation about BLE connection and services.

This commit is contained in:
JF 2020-04-05 17:03:06 +02:00
parent 26fb9ed1cd
commit 932c0479ee
6 changed files with 75 additions and 1 deletions

View file

@ -34,7 +34,11 @@ I've tested this project on the actual PineTime hardware.
* Rich user interface (using [LittleVGL](https://littlevgl.com/)) via display, touchpanel and push button.
* Digital watch face and 4 demo applications (spinning meter, analog gauche, push button and message box);
* Watchdog (automatic reset in case of firmware crash) and reset support (push and hold the button for 7 - 10s);
* BLE Notification support (still Work-In-Progress, companion app needed).
* BLE Notification support (still Work-In-Progress, [companion app](https://github.com/JF002/gobbledegook) needed).
## Documentation
* [BLE implementation and API](./doc/ble.md)
## Stub using NRF52-DK
![Pinetime stub](./images/pinetimestub1.jpg "PinetimeStub")

27
doc/ble.md Normal file
View file

@ -0,0 +1,27 @@
# Bluetooth Low-Energy :
## Introduction
This page describes the BLE implementation and API built in this firmware.
**Note** : I'm a beginner in BLE related technologies and the information of this document reflect my current knowledge and understanding of the BLE stack. These informations might be erroneous or incomplete. Feel free to submit a PR if you think you can improve these.
## BLE Connection
When starting the firmware start a BLE advertising : it send small messages that can be received by any *central* device in range. This allows the device to announce its presence to other devices.
A companion application (running on a PC, RasberryPi, smartphone) which received this avertising packet can request a connection to the device. This connection procedure allows the 2 devices to negociate communication parameters, security keys,...
When the connection is established, the pinetime will try to discover services running on the companion application. For now **CTS** (**C**urrent **T**ime **S**ervice) and **ANS** (**A**lert **N**otification **S**ervice) are supported.
If **CTS** is detected, it'll request the current time to the companion application. If **ANS** is detected, it will listen to new notifications coming from the companion application.
![BLE connection sequence diagram](ble/connection_sequence.png "BLE connection sequence diagram")
## BLE services
[List of standard BLE services](https://www.bluetooth.com/specifications/gatt/services/)
### CTS
[Current Time Service](https://www.bluetooth.com/wp-content/uploads/Sitecore-Media-Library/Gatt/Xml/Services/org.bluetooth.service.alert_notification.xml)
### ANS
[Alert Notification Service](https://www.bluetooth.com/wp-content/uploads/Sitecore-Media-Library/Gatt/Xml/Services/org.bluetooth.service.current_time.xml)
![ANS sequence diagram](./ble/ans_sequence.png "ANS sequence diagram")

BIN
doc/ble/ans_sequence.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 36 KiB

29
doc/ble/ans_sequence.puml Normal file
View file

@ -0,0 +1,29 @@
@startuml
group Get configuration from server
Pinetime -> CompanionApp : Read request (Supported 'new' notification categories - 0x2A47)
CompanionApp --> Pinetime: Response (0xff = all categories)
Pinetime -> CompanionApp : Read request (Supported 'unread' notification categories - 0x2A48)
CompanionApp --> Pinetime: Response (0xff = all categories)
end
group Configure the server
Pinetime -> CompanionApp : Configure 'new' notifications categories : Accept all (Write [0, 0xFF] to Control Point - 0x2A44)
activate CompanionApp
deactivate CompanionApp
Pinetime -> CompanionApp : Configure 'unread' notifications categories : Accept all (Write [1, 0xFF] to Control Point - 0x2A44)
activate CompanionApp
deactivate CompanionApp
end
group Server sends a notification
CompanionApp -> Pinetime : Notify new_alert (0x2A46)
activate Pinetime
note over Pinetime
Pinetime FW handles the
notification (display on UI)
end note
deactivate Pinetime
end
@enduml

Binary file not shown.

After

Width:  |  Height:  |  Size: 18 KiB

View file

@ -0,0 +1,14 @@
@startuml
Pinetime --> CompanionApp: Start advertising
group BLE Connection
CompanionApp -> Pinetime: Connection request
CompanionApp <-> Pinetime: Connection parameters negociation, security procedure,...
end
group Service Discovery
CompanionApp <-> Pinetime: Discover service 0x1805 (CTS)
CompanionApp <-> Pinetime: Discover service 0x1811 (ANS)
end
@enduml