RIOT-OS
sys/stdio_nimble: add version note to README
Contribution description
In the latest release of ble-serial, a new command line option --write-with-response was added and the default value is False.
(See https://github.com/Jakeler/ble-serial/issues/109 and https://github.com/Jakeler/ble-serial/releases/tag/v3.0.0 ).
This will lead to the following error when trying to connect to the test/sys/shell_ble example or any application that uses the stdio_nimble module.
~/RIOTdev/RIOT/tests/sys/shell_ble$ ble-serial -d DA:ED:02:2A:35:CE -p /tmp/dev_riot_ble --write-uuid ccdd113f-40d5-4d68-86ac-a728dd82f4aa --read-uuid 35f28386-3070-4f3b-ba38-27507e991762
16:46:15.471 | INFO | linux_pty.py: Port endpoint created on /tmp/dev_riot_ble -> /dev/pts/1
16:46:15.471 | INFO | ble_client.py: Receiver set up
16:46:17.565 | INFO | ble_client.py: Trying to connect with DA:ED:02:2A:35:CE: tests/sys/shell/_ble
16:46:17.973 | WARNING | ble_client.py: Device DA:ED:02:2A:35:CE disconnected
16:46:17.974 | INFO | ble_client.py: Stopping Bluetooth event loop
16:46:19.446 | INFO | ble_client.py: Device DA:ED:02:2A:35:CE connected
16:46:19.446 | ERROR | main.py: No characteristic with ['write-without-response'] property found!
Traceback (most recent call last):
File "/usr/local/lib/python3.10/dist-packages/ble_serial/main.py", line 53, in _run
await self.bt.setup_chars(args.write_uuid, args.read_uuid, args.mode, args.write_with_response)
File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/ble_client.py", line 44, in setup_chars
self.write_char = self.find_char(write_uuid, write_cap)
File "/usr/local/lib/python3.10/dist-packages/ble_serial/bluetooth/ble_client.py", line 84, in find_char
assert len(results) > 0, \
AssertionError: No characteristic with ['write-without-response'] property found!
16:46:19.447 | WARNING | main.py: Shutdown initiated
16:46:19.447 | INFO | linux_pty.py: Serial reader and symlink removed
16:46:21.677 | WARNING | ble_client.py: Device DA:ED:02:2A:35:CE disconnected
16:46:21.677 | INFO | ble_client.py: Stopping Bluetooth event loop
16:46:21.678 | INFO | ble_client.py: Bluetooth disconnected
16:46:21.678 | INFO | main.py: Shutdown complete.
Using the new command line option makes the command work as expected:
~/RIOTdev/RIOT/tests/sys/shell_ble$ ble-serial -d DA:ED:02:2A:35:CE -p /tmp/dev_riot_ble --write-uuid ccdd113f-40d5-4d68-86ac-a728dd82f4aa --read-uuid 35f28386-3070-4f3b-ba38-27507e991762 --write-with-response
16:47:52.167 | INFO | linux_pty.py: Port endpoint created on /tmp/dev_riot_ble -> /dev/pts/1
16:47:52.167 | INFO | ble_client.py: Receiver set up
16:47:52.803 | INFO | ble_client.py: Trying to connect with DA:ED:02:2A:35:CE: tests/sys/shell/_ble
16:47:54.068 | INFO | ble_client.py: Device DA:ED:02:2A:35:CE connected
16:47:54.068 | INFO | ble_client.py: Found write characteristic ccdd113f-40d5-4d68-86ac-a728dd82f4aa (H. 14)
16:47:54.068 | INFO | ble_client.py: Found notify characteristic 35f28386-3070-4f3b-ba38-27507e991762 (H. 11)
16:47:54.409 | INFO | main.py: Running main loop!
Testing procedure
This is only a documentation change, but the test procedure would be as following:
Make sure you have the latest version of ble-serial installed. Otherwise you can upgrade it with pip install ble-serial --upgrade.
The latest version at the time of writing is 3.0.0.
$ pip show ble-serial
Name: ble-serial
Version: 3.0.0
Summary: Connects BLE adapters with virtual serial ports
Home-page:
Author:
Author-email: Jake <[email protected]>
License: MIT License
Location: /usr/local/lib/python3.10/dist-packages
Requires: bleak, coloredlogs
Required-by:
The test in tests/sys/shell_ble runs on all nRF52 devices (and probably others as well with NimBLE support). I used an nRF52840DK and our own hardware.
You can follow the procedure described in the text and should observe the aforementioned error when trying to connect to the device.
Maybe there's a better name for the PR/commit, but I couldn't think of anything better. I'm open to suggestions :D
huh didn't know this file exist - I think it's contents should be moved to stdio_nimble.h so it shows up in the documentation
huh didn't know this file exist - I think it's contents should be moved to
stdio_nimble.hso it shows up in the documentation
Just as it is, basically Copy & Paste (with some deduplication of what's already there)?
I don't like necessary line breaks in the code blocks, but otherwise the static tests will bonk me. I did not find a command how to add a line wrap to code blocks in Doxygen.
For example
Line 129-142:
...
* ```
* $ ble-serial -d 6BE8174C-A0F8-4479-AFA6-9828372CAFE9 -p /tmp/dev_riot_ble
* --write-uuid ccdd113f-40d5-4d68-86ac-a728dd82f4aa
* --read-uuid 35f28386-3070-4f3b-ba38-27507e991762 --write-with-response
*
* 17:44:18.765 | INFO | linux_pty.py: Slave created on /tmp/dev_riot_ble -> /dev/ttys006
* 17:44:18.766 | INFO | ble_interface.py: Receiver set up
* 17:44:18.766 | INFO | ble_interface.py: Trying to connect with 6BE8174C-A0F8-4479-AFA6-
* 9828372CAFE9
* 17:44:19.861 | INFO | ble_interface.py: Device 6BE8174C-A0F8-4479-AFA6-9828372CAFE9 connected
* 17:44:19.862 | INFO | ble_interface.py: Found write characteristic ccdd113f-40d5-4d68-86ac-
* a728dd82f4aa (H. 14)
* 17:44:19.862 | INFO | ble_interface.py: Found notify characteristic 35f28386-3070-4f3b-ba38-
* 27507e991762 (H. 11)
* 17:44:19.883 | INFO | main.py: Running main loop!
* ```
...
We have all this space in the resulting documentation and don't use it:
Murdock results
:heavy_check_mark: PASSED
9c44b7f8421d2f1fd708f897f31cc0d5ac279675 tests/sys/shell_ble: update reference to instructions
| Success | Failures | Total | Runtime |
|---|---|---|---|
| 1 | 0 | 1 | 01m:15s |
Artifacts
Is there something left to do for this to be merged? It looks like this PR will not have any collisions with #21108 either, so it should be all good.