Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koenvervloesem/bluetooth-clocks
Set and get the time on various Bluetooth Low Energy clocks
https://github.com/koenvervloesem/bluetooth-clocks
ble bluetooth bluetooth-low-energy clocks current-time-service infinitime pinetime pvvx-firmware python python3 qingping thermopro time-sync time-synchronization xiaomi
Last synced: 4 days ago
JSON representation
Set and get the time on various Bluetooth Low Energy clocks
- Host: GitHub
- URL: https://github.com/koenvervloesem/bluetooth-clocks
- Owner: koenvervloesem
- License: mit
- Created: 2023-01-20T17:52:36.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-10-28T16:03:51.000Z (about 1 year ago)
- Last Synced: 2024-10-07T23:24:47.878Z (about 1 month ago)
- Topics: ble, bluetooth, bluetooth-low-energy, clocks, current-time-service, infinitime, pinetime, pvvx-firmware, python, python3, qingping, thermopro, time-sync, time-synchronization, xiaomi
- Language: Python
- Homepage: https://bluetooth-clocks.readthedocs.io
- Size: 554 KB
- Stars: 19
- Watchers: 6
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGELOG.rst
- Contributing: CONTRIBUTING.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
.. image:: https://github.com/koenvervloesem/bluetooth-clocks/workflows/tests/badge.svg
:alt: Continuous Integration
:target: https://github.com/koenvervloesem/bluetooth-clocks/actions
.. image:: https://img.shields.io/pypi/v/bluetooth-clocks.svg
:alt: Python package version
:target: https://pypi.org/project/bluetooth-clocks/
.. image:: https://img.shields.io/pypi/pyversions/bluetooth-clocks.svg
:alt: Supported Python versions
:target: https://python.org/
.. image:: https://readthedocs.org/projects/bluetooth-clocks/badge/?version=latest
:target: https://bluetooth-clocks.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://codecov.io/gh/koenvervloesem/bluetooth-clocks/branch/main/graph/badge.svg?token=RQNLC3OTFN
:alt: Codecov coverage
:target: https://codecov.io/gh/koenvervloesem/bluetooth-clocks
.. image:: https://img.shields.io/github/license/koenvervloesem/bluetooth-clocks.svg
:alt: License
:target: https://github.com/koenvervloesem/bluetooth-clocks/blob/main/LICENSE.txt
|
================
Bluetooth Clocks
================
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.
.. image:: https://github.com/koenvervloesem/bluetooth-clocks/raw/main/docs/_static/synchronized-clocks.jpg
:alt: Synchronize all your Bluetooth Low Energy clocks
.. inclusion-marker-after-intro
Supported devices
=================
Bluetooth Clocks supports the following devices:
+--------------------------+------------+-------------------+-----------+
| Device | Set time | Set 12/24h format | Read time |
+==========================+============+===================+===========+
| `Current Time Service`_ | Yes | No | Yes |
| (e.g. PineTime with | | | |
| InfiniTime firmware) | | | |
+--------------------------+------------+-------------------+-----------+
| `PVVX firmware`_ | Yes | No | Yes |
| (LYWSD03MMC, MHO-C401, | | | |
| CGG1, CGDK2, MJWSD05MMC, | | | |
| MHO-C122) | | | |
+--------------------------+------------+-------------------+-----------+
| Qingping BT Clock Lite | Yes | No | No |
+--------------------------+------------+-------------------+-----------+
| ThermoPro TP358/TP393 | Yes | Yes | No |
+--------------------------+------------+-------------------+-----------+
| Xiaomi LYWSD02 | Yes | No | Yes |
+--------------------------+------------+-------------------+-----------+
.. _Current Time Service: https://www.bluetooth.com/specifications/specs/current-time-service-1-1/
.. _PVVX firmware: https://github.com/pvvx/ATC_MiThermometer
.. inclusion-marker-before-installation
Installation
============
You can install bluetooth-clocks as a package from PyPI with pip::
pip install bluetooth-clocks
Usage of the command-line program
=================================
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
Discovering Bluetooth clocks
----------------------------
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)
Setting the time
----------------
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.
Getting the time
----------------
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)
Usage of the library
====================
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.
.. inclusion-marker-before-license
Documentation
=============
Read the `online documentation `_ of Bluetooth Clocks.
Learn more about Bluetooth Low Energy development
=================================================
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 `_.
License
=======
This project is provided by Koen Vervloesem as open source software with the MIT license. See the `LICENSE `_ file for more information.