From 211e9795e05354b25455ab83e0b8be234ac3900c Mon Sep 17 00:00:00 2001 From: JF Date: Sun, 29 Mar 2020 15:19:39 +0200 Subject: Update Readme, add section about BLE connection troubleshooting --- README.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 2940dfd9..57b95aab 100644 --- a/README.md +++ b/README.md @@ -29,10 +29,12 @@ I've tested this project on the actual PineTime hardware. * SPI (DMA & IRQ based) LCD driver; * BLE advertising, connection and bonding; * BLE CTS client (retrieves the time from the connected device if it implements a CTS server); - * Push button to go to disable screen (and go to low power mode) / enable screen (and wake-up); + * Push button to go to disable screen (and go to low power mode) / enable screen (and wake-up) and UI navigation * Touch panel support; - * Basic user interface via display, touchpanel and push button. - * Digital watch face and 4 demo applications (spinning meter, analog gauche, push button and message box); + * 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). ## Stub using NRF52-DK ![Pinetime stub](./images/pinetimestub1.jpg "PinetimeStub") @@ -206,6 +208,7 @@ $ JLinkRTTClient At runtime, BLE advertising is started. You can then use a smartphone or computer to connect and bond to your Pinetime. As soon as a device is bonded, Pinetime will look for a **CTS** server (**C**urrent **T**ime **S**ervice) on the connected device. +### Using Android and NRFConnect Here is how to do it with an Android smartphone running NRFConnect: * Build and program the firmware on the Pinetime @@ -217,4 +220,33 @@ Here is how to do it with an Android smartphone running NRFConnect: * Go back to the main screen and scan for BLE devices. A device called "PineTime" should appear * Tap the button "Connect" next to the PineTime device. It should connect to the PineTime and switch to a new tab. * On this tab, on the top right, there is a 3 dots button. Tap on it and select Bond. The bonding process begins, and if it is sucessful, the PineTime should update its time and display it on the screen. - \ No newline at end of file + +### Using Linux and bluetoothctl +* Ensure that your bluetooth controller is enabled and working fine. I've tested this on a x86 Debian computer and on a RaspberryPi 3. +* Run bluetoothctl as root : `sudo bluetoothctl` +* Enter the following commands: + * `scan on` and wait for you Pinetime to be detected. Note the BLE MAC address + * `scan off' + * `trust ` + * `pair ` + * Wait for some time, and the connection should be established. + +**NOTE : ** The commands above establish a BLE connection between your PC, but the time synchronization and notifications won't work because there is not CTS or ANS server running. I'm currently working on an application that'll provide both of these servers. + +### Troubleshooting +If the connection cannot be established, or the time synchronization does not work, try the following steps. + +On Android: +* Disable and re-enable your bluetooth device +* In NRFConnect, in the device tab corresponding to your pinetime, tap on the menu on the top left of the screen and select "Delete bond information". +* Then re-try to bond/connect. + +On Linux: +* Reset the bluetooth device : `sudo hciconfig hci0 reset` +* Restart the Bluetooth service : `sudo systemctl restart bluetooth.service` +* In bluetootctl: + * `remove ` + * `trust ` + * `pair ` + +Note that the current firmware only advertise for the first 3 minutes. If you cannot connect after more than 3 minutes, try resetting the device (push the button and hold it for 7-10 seconds). \ No newline at end of file -- cgit v1.2.3-70-g09d2 From 932c0479ee7c501bc224435943c73a368001845e Mon Sep 17 00:00:00 2001 From: JF Date: Sun, 5 Apr 2020 17:03:06 +0200 Subject: Add documentation about BLE connection and services. --- README.md | 6 +++++- doc/ble.md | 27 +++++++++++++++++++++++++++ doc/ble/ans_sequence.png | Bin 0 -> 36606 bytes doc/ble/ans_sequence.puml | 29 +++++++++++++++++++++++++++++ doc/ble/connection_sequence.png | Bin 0 -> 17958 bytes doc/ble/connection_sequence.puml | 14 ++++++++++++++ 6 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 doc/ble.md create mode 100644 doc/ble/ans_sequence.png create mode 100644 doc/ble/ans_sequence.puml create mode 100644 doc/ble/connection_sequence.png create mode 100644 doc/ble/connection_sequence.puml (limited to 'README.md') diff --git a/README.md b/README.md index 57b95aab..790e3de1 100644 --- a/README.md +++ b/README.md @@ -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") diff --git a/doc/ble.md b/doc/ble.md new file mode 100644 index 00000000..0302b471 --- /dev/null +++ b/doc/ble.md @@ -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") \ No newline at end of file diff --git a/doc/ble/ans_sequence.png b/doc/ble/ans_sequence.png new file mode 100644 index 00000000..99cf8493 Binary files /dev/null and b/doc/ble/ans_sequence.png differ diff --git a/doc/ble/ans_sequence.puml b/doc/ble/ans_sequence.puml new file mode 100644 index 00000000..c3819059 --- /dev/null +++ b/doc/ble/ans_sequence.puml @@ -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 \ No newline at end of file diff --git a/doc/ble/connection_sequence.png b/doc/ble/connection_sequence.png new file mode 100644 index 00000000..7e8babcb Binary files /dev/null and b/doc/ble/connection_sequence.png differ diff --git a/doc/ble/connection_sequence.puml b/doc/ble/connection_sequence.puml new file mode 100644 index 00000000..55531829 --- /dev/null +++ b/doc/ble/connection_sequence.puml @@ -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 \ No newline at end of file -- cgit v1.2.3-70-g09d2