Set and get the time on various Bluetooth Low Energy clocks
This project offers a way to easily recognize Bluetooth Low Energy (BLE) clocks from their advertisements and has a device-independent API to set and get the time on them.
Bluetooth Clocks supports the following devices:
| Device | Set time | Set 12/24h format | Read time |
|---|---|---|---|
| Current Time Service (e.g. PineTime with InfiniTime firmware) | Yes | No | Yes |
| PVVX firmware (LYWSD03MMC, MHO-C401, CGG1, CGDK2, MJWSD05MMC, MHO-C122) | Yes | No | Yes |
| Qingping BT Clock Lite | Yes | No | No |
| ThermoPro TP358/TP393 | Yes | Yes | No |
| Xiaomi LYWSD02 | Yes | No | Yes |
You can install bluetooth-clocks as a package from PyPI with pip:
pip install bluetooth-clocks
If you have installed the package with pip, you can run the program as bluetooth-clocks:
$ bluetooth-clocks -h
usage: bluetooth-clocks [-h] [--version] [-v] [-vv] {discover,get,set} ...
Bluetooth Clocks
options:
-h, --help show this help message and exit
--version show program's version number and exit
-v, --verbose set loglevel to INFO
-vv, --very-verbose set loglevel to DEBUG
Subcommands:
{discover,get,set}
discover discover supported Bluetooth clocks
get get the time from a Bluetooth clock
set set the time of a Bluetooth clock
You can discover supported Bluetooth clocks with bluetooth-clocks discover:
$ bluetooth-clocks discover Scanning for supported clocks... Found a ThermoPro TP358: address BC:C7:DA:6A:52:C6, name TP358 (52C6) Found a Xiaomi LYWSD02: address E7:2E:00:B1:38:96, name LYWSD02 Found a ThermoPro TP393: address 10:76:36:14:2A:3D, name TP393 (2A3D) Found a Qingping BT Clock Lite: address 58:2D:34:54:2D:2C, name Qingping BT Clock Lite Found a Current Time Service: address EB:76:55:B9:56:18, name F15
These are the options that the discover subcommand recognizes:
$ bluetooth-clocks discover -h
usage: bluetooth-clocks discover [-h] [-s SCAN_DURATION]
options:
-h, --help show this help message and exit
-s SCAN_DURATION, --scan-duration SCAN_DURATION
scan duration (default: 5 seconds)
Set the time of a clock with a given Bluetooth address:
$ bluetooth-clocks set -a E7:2E:00:B1:38:96 Scanning for device E7:2E:00:B1:38:96... Writing time to device... Synchronized time
If you want to regularly synchronize the time on the device, you can run this command as a service, e.g. with a systemd service or in a cron job in Linux.
These are the options that the set subcommand recognizes:
$ bluetooth-clocks set -h
usage: bluetooth-clocks set [-h] -a ADDRESS [-s SCAN_DURATION] [-t TIME] [-p]
options:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
Bluetooth address (e.g. 12:34:56:78:9A:BC)
-s SCAN_DURATION, --scan-duration SCAN_DURATION
scan duration (default: 5 seconds)
-t TIME, --time TIME the time to set, in ISO 8601 format (e.g. 2023-01-10T16:20,
default: current time)
-p, --am-pm use AM/PM format (default: 24-hour format)
Warning
Don't be a jerk by changing the time of other people's clocks. Use this tool responsibly.
Get the time from a clock with a given Bluetooth address:
$ bluetooth-clocks get -a E7:2E:00:B1:38:96 Scanning for device E7:2E:00:B1:38:96... Reading time from device... 2023-01-14T17:54:17
These are the options that the get subcommand recognizes:
$ bluetooth-clocks get -h
usage: bluetooth-clocks get [-h] -a ADDRESS [-s SCAN_DURATION]
options:
-h, --help show this help message and exit
-a ADDRESS, --address ADDRESS
Bluetooth address (e.g. 12:34:56:78:9A:BC)
-s SCAN_DURATION, --scan-duration SCAN_DURATION
scan duration (default: 5 seconds)
The functionality of the command-line program can also be used in your own Python programs by using this project as a library.
See the module reference for complete API documentation.
Read the online documentation of Bluetooth Clocks.
If you want to learn more about Bluetooth Low Energy development, read the book Develop your own Bluetooth Low Energy Applications for Raspberry Pi, ESP32 and nRF52 with Python, Arduino and Zephyr and the accompanying GitHub repository koenvervloesem/bluetooth-low-energy-applications.
This project is provided by Koen Vervloesem as open source software with the MIT license. See the LICENSE file for more information.