uPyble
Command line tool for Bluetooth Low Energy devices
uPyble is intended to be a command line tool upydev-like to make easier the development, prototyping and testing process of devices based on boards running *MicroPython with Bluetooth Low Energy capabilities.
*( Any other BLE device should work as well)
⚠️ Keep in mind that this project is in ALPHA state, sometimes, some commands may not work/return anything ⚠️
Features:
- Command line wireless communication/control of MicroPython/other devices.
- Custom commands to automate communication/control
- Command line autocompletion
- Terminal BLE SHELL-REPL 🔸🔺
🔸 (REPL works, but some SHELL commands are still under development)
🔺 There is a limit in the amount of output it can produce, so long lists or cat
a big file will freeze the BLE SHELL-REPL and possibly the device, which makes a reset almost inevitable.
Getting Started
For Terminal BLE SHELL-REPL :
First be sure that the BLE REPL daemon is enabled and running:
-
- Put
ble_advertising.py
,ble_uart_peripheral.py
and ble_uart_repl.py
in the device
-
-
Add these lines to main.py
:
import ble_uart_repl
ble_uart_repl.start()
These scripts are in upybleutils directory. (Originals from MicroPython repo bluetooth examples)
Installing :
$ pip install upyble
or $ pip install --upgrade upyble
to update to the last version available
Finding BLE devices:
Use $ upyble scan
or $ upyble tscan
for table output format.
$ upyble tscan
Scanning...
Scanning...
BLE device/s found: 1
==============================================================================
NAME | UUID | RSSI (dBm) |
esp32-30aea4233564 | 9998175F-9A91-4CA2-B5EA-482AFC3453B9 | -68.0 |
Create a configuration file:
*upyble will use local working directory configuration unless it does not find any or manually indicated with -g
option.
-
To save configuration globally use -g flag: $ upyble config -t [UPYDEVICE UUID] -g
e.g.
$ upyble config -t 9998175F-9A91-4CA2-B5EA-482AFC3453B9 -g
* Be aware that some devices may generate random UUID every a couple of minutes, so this won't be useful in those cases.
uPyble Usage:
Usage:
$ upyble [Mode] [options]
This means that if the first argument is not a Mode keyword it assumes it is a 'raw' upy command to send to the upy device
Help: $ upyble -h
uPyble Mode/Tools:
upyble check
: to check local machine Bluetooth characteriscticsupyble config
: save upy device settings (see -t
, -g
), so the target uuid argument wont be required any moreupyble scan
: to scan for BLE devices (see -n
for max number of scans)upyble tscan
: to scan for BLE devices, results with table formatupyble sconf
: to scan and configure a device that matches a name -d [NAME]
upyble get_services
: to get services of a device, use -r
to read them and -mdata
to see available metadataupyble get_stag
: to get service tag from a service code, use -scode
to indicate the codeupyble get_scode
: to get service code from a service tag, use -stag
to indicate the tagupyble get_ctag
: to get characteristic tag from characteristic code, use -ccode
to indicate the codeupyble get_ccode
: to get characteristic code from a characteristic tag, use -ctag
to indicate the tagupyble get_aptag
: to get appearance tag from an appearance code, use -apcode
to indicate the codeupyble get_apcode
: to get appearance code from an appearance tag, use -aptag
to indicate the tagupyble get_mtag
: to get manufacturer tag from manufacturer code, use -mcode
to indicate the codeupyble get_mcode
: to get manufacturer code from a manufacturer tag, use -mtag
to indicate the tagupyble cmdata
: to get characteristic metadata (name, type, uuid, unit, format, notes...). (Not all characteristics are available yet), Use -c
option to indicate characteristic or -c all
to see all that are available. Use -xml
to see the xml file instead.upyble cmdata_t
: get_cmdata in table format.upyble dmdata
: to get descriptor metadata (Name, uuid, format...). Use -desc
option to indicate a descriptor or -desc all
to see all that are available.upyble follow
: to read from a service (see -s
, -c
, -tm
) , e.g : upyble follow -s "Battery Service"
, will read all readable characteristics, or use -c
to indicate a specific one/group. e.g: upyble follow -s "Battery Service" -c "Battery Level"
. This mode autodetects format and unit from characteristic metadataupyble rfollow
: to read from a service (see -s
, -c
, -tm
, -u
, fmt
and -x
) , e.g : upyble follow -s "Battery Service"
, will read all readable characteristics, or use -c
to indicate a specific one/group. e.g: upyble follow -s "Battery Service" -c "Battery Level"
upyble see
: to get specific info about a devices group use -G
option as see -G [GROUP NAME]
upyble brepl
: to enter the BLE SHELL-REPLupyble ble@[DEVICE]
: to access brepl in a 'ssh' style command if a device is stored in a global group called UPYBLE_G
(this needs to be created first doing e.g. $ upyble make_group -g -f UPYBLE_G -devs foo_device UUID
) The device can be accessed as $ upyble ble@foo_device
or redirect any command as e.g. $ upyble get_services -@foo_device
.
Examples:
Follow the Battery Level and Temperature (cpu) of an Esp32.
This needs ble_batt_temp.py
in the device. (See upybleutils)
In the device REPL do:
>>> import ble_batt_temp
>>> ble_batt_temp.ble_batt.start_batt_bg()
Now in local Shell/Terminal:
-
Scan and configure device:
$ upyble scan
Scanning...
Scanning...
BLE device/s found: 1
NAME: esp32-batt-temp, UUID: 9998175F-9A91-4CA2-B5EA-482AFC3453B9, RSSI: -59.0 dBm, Services: Environmental Sensing
$ upyble config -t 9998175F-9A91-4CA2-B5EA-482AFC3453B9 -g
upyble device settings saved globally!
-
Follow services
$ upyble follow -s all
Following service: all
[Service] 180A: Device Information
[Characteristic] 2A01: (read) | Name: Appearance
[Characteristic] 2A29: (read) | Name: Manufacturer Name String
[Service] 180F: Battery Service
[Characteristic] 2A19: (read,notify) | Name: Battery Level
[Descriptor] 2902: (Handle: 19)
[Service] 181A: Environmental Sensing
[Characteristic] 2A6E: (read,notify) | Name: Temperature
[Descriptor] 2902: (Handle: 23)
15:35:28,813 [upyble@esp32-batt-temp] Battery Service [Battery Level] : 77.0 %
15:35:28,843 [upyble@esp32-batt-temp] Environmental Sensing [Temperature] : 56.67 °C
15:35:33,883 [upyble@esp32-batt-temp] Battery Service [Battery Level] : 76.0 %
15:35:33,913 [upyble@esp32-batt-temp] Environmental Sensing [Temperature] : 56.67 °C
15:35:38,954 [upyble@esp32-batt-temp] Battery Service [Battery Level] : 76.0 %
15:35:38,983 [upyble@esp32-batt-temp] Environmental Sensing [Temperature] : 56.67 °C
15:35:44,024 [upyble@esp32-batt-temp] Battery Service [Battery Level] : 71.0 %
15:35:44,053 [upyble@esp32-batt-temp] Environmental Sensing [Temperature] : 56.67 °C
^CDisconnected successfully
See more usage examples at EXAMPLES doc.
ABOUT
To see more information about upyble dependencies, requirements, tested devices, etc see ABOUT doc.