.. 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 <https://bluetooth-clocks.readthedocs.io/en/latest/api/modules.html>`_ for complete API documentation.
.. inclusion-marker-before-license
Documentation
=============
Read the `online documentation <https://bluetooth-clocks.readthedocs.io>`_ 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 <https://koen.vervloesem.eu/books/develop-your-own-bluetooth-low-energy-applications/>`_ and the accompanying GitHub repository `koenvervloesem/bluetooth-low-energy-applications <https://github.com/koenvervloesem/bluetooth-low-energy-applications>`_.
License
=======
This project is provided by Koen Vervloesem as open source software with the MIT license. See the `LICENSE <https://github.com/koenvervloesem/bluetooth-clocks/blob/main/LICENSE.txt>`_ file for more information.
Raw data
{
"_id": null,
"home_page": "https://github.com/koenvervloesem/bluetooth-clocks",
"name": "bluetooth-clocks",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "bluetooth,ble,bluetooth-low-energy,clocks,time,time-synchronization,get-time,set-time,current-time-service",
"author": "Koen Vervloesem",
"author_email": "koen@vervloesem.eu",
"download_url": "https://files.pythonhosted.org/packages/77/cf/6d677e33e696173a88263b234043b7ae057f7107ff82f8eeb8015d53a82a/bluetooth-clocks-0.2.0.tar.gz",
"platform": "any",
"description": ".. image:: https://github.com/koenvervloesem/bluetooth-clocks/workflows/tests/badge.svg\n :alt: Continuous Integration\n :target: https://github.com/koenvervloesem/bluetooth-clocks/actions\n.. image:: https://img.shields.io/pypi/v/bluetooth-clocks.svg\n :alt: Python package version\n :target: https://pypi.org/project/bluetooth-clocks/\n.. image:: https://img.shields.io/pypi/pyversions/bluetooth-clocks.svg\n :alt: Supported Python versions\n :target: https://python.org/\n.. image:: https://readthedocs.org/projects/bluetooth-clocks/badge/?version=latest\n :target: https://bluetooth-clocks.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n.. image:: https://codecov.io/gh/koenvervloesem/bluetooth-clocks/branch/main/graph/badge.svg?token=RQNLC3OTFN\n :alt: Codecov coverage\n :target: https://codecov.io/gh/koenvervloesem/bluetooth-clocks\n.. image:: https://img.shields.io/github/license/koenvervloesem/bluetooth-clocks.svg\n :alt: License\n :target: https://github.com/koenvervloesem/bluetooth-clocks/blob/main/LICENSE.txt\n\n|\n\n================\nBluetooth Clocks\n================\n\n\n Set and get the time on various Bluetooth Low Energy clocks\n\n\nThis project offers a way to easily recognize Bluetooth Low Energy (BLE) clocks from\ntheir advertisements and has a device-independent API to set and get the time on them.\n\n.. image:: https://github.com/koenvervloesem/bluetooth-clocks/raw/main/docs/_static/synchronized-clocks.jpg\n :alt: Synchronize all your Bluetooth Low Energy clocks\n\n.. inclusion-marker-after-intro\n\nSupported devices\n=================\n\nBluetooth Clocks supports the following devices:\n\n+--------------------------+------------+-------------------+-----------+\n| Device | Set time | Set 12/24h format | Read time |\n+==========================+============+===================+===========+\n| `Current Time Service`_ | Yes | No | Yes |\n| (e.g. PineTime with | | | |\n| InfiniTime firmware) | | | |\n+--------------------------+------------+-------------------+-----------+\n| `PVVX firmware`_ | Yes | No | Yes |\n| (LYWSD03MMC, MHO-C401, | | | |\n| CGG1, CGDK2, MJWSD05MMC, | | | |\n| MHO-C122) | | | |\n+--------------------------+------------+-------------------+-----------+\n| Qingping BT Clock Lite | Yes | No | No |\n+--------------------------+------------+-------------------+-----------+\n| ThermoPro TP358/TP393 | Yes | Yes | No |\n+--------------------------+------------+-------------------+-----------+\n| Xiaomi LYWSD02 | Yes | No | Yes |\n+--------------------------+------------+-------------------+-----------+\n\n.. _Current Time Service: https://www.bluetooth.com/specifications/specs/current-time-service-1-1/\n.. _PVVX firmware: https://github.com/pvvx/ATC_MiThermometer\n\n.. inclusion-marker-before-installation\n\nInstallation\n============\n\nYou can install bluetooth-clocks as a package from PyPI with pip::\n\n pip install bluetooth-clocks\n\nUsage of the command-line program\n=================================\n\nIf you have installed the package with ``pip``, you can run the program as ``bluetooth-clocks``::\n\n $ bluetooth-clocks -h\n usage: bluetooth-clocks [-h] [--version] [-v] [-vv] {discover,get,set} ...\n\n Bluetooth Clocks\n\n options:\n -h, --help show this help message and exit\n --version show program's version number and exit\n -v, --verbose set loglevel to INFO\n -vv, --very-verbose set loglevel to DEBUG\n\n Subcommands:\n {discover,get,set}\n discover discover supported Bluetooth clocks\n get get the time from a Bluetooth clock\n set set the time of a Bluetooth clock\n\nDiscovering Bluetooth clocks\n----------------------------\n\nYou can discover supported Bluetooth clocks with ``bluetooth-clocks discover``::\n\n $ bluetooth-clocks discover\n Scanning for supported clocks...\n Found a ThermoPro TP358: address BC:C7:DA:6A:52:C6, name TP358 (52C6)\n Found a Xiaomi LYWSD02: address E7:2E:00:B1:38:96, name LYWSD02\n Found a ThermoPro TP393: address 10:76:36:14:2A:3D, name TP393 (2A3D)\n Found a Qingping BT Clock Lite: address 58:2D:34:54:2D:2C, name Qingping BT Clock Lite\n Found a Current Time Service: address EB:76:55:B9:56:18, name F15\n\nThese are the options that the ``discover`` subcommand recognizes::\n\n $ bluetooth-clocks discover -h\n usage: bluetooth-clocks discover [-h] [-s SCAN_DURATION]\n\n options:\n -h, --help show this help message and exit\n -s SCAN_DURATION, --scan-duration SCAN_DURATION\n scan duration (default: 5 seconds)\n\nSetting the time\n----------------\n\nSet the time of a clock with a given Bluetooth address::\n\n $ bluetooth-clocks set -a E7:2E:00:B1:38:96\n Scanning for device E7:2E:00:B1:38:96...\n Writing time to device...\n Synchronized time\n\nIf 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.\n\nThese are the options that the ``set`` subcommand recognizes::\n\n $ bluetooth-clocks set -h\n usage: bluetooth-clocks set [-h] -a ADDRESS [-s SCAN_DURATION] [-t TIME] [-p]\n\n options:\n -h, --help show this help message and exit\n -a ADDRESS, --address ADDRESS\n Bluetooth address (e.g. 12:34:56:78:9A:BC)\n -s SCAN_DURATION, --scan-duration SCAN_DURATION\n scan duration (default: 5 seconds)\n -t TIME, --time TIME the time to set, in ISO 8601 format (e.g. 2023-01-10T16:20,\n default: current time)\n -p, --am-pm use AM/PM format (default: 24-hour format)\n\n.. warning::\n\n Don't be a jerk by changing the time of other people's clocks. Use this tool responsibly.\n\nGetting the time\n----------------\n\nGet the time from a clock with a given Bluetooth address::\n\n $ bluetooth-clocks get -a E7:2E:00:B1:38:96\n Scanning for device E7:2E:00:B1:38:96...\n Reading time from device...\n 2023-01-14T17:54:17\n\nThese are the options that the ``get`` subcommand recognizes::\n\n $ bluetooth-clocks get -h\n usage: bluetooth-clocks get [-h] -a ADDRESS [-s SCAN_DURATION]\n\n options:\n -h, --help show this help message and exit\n -a ADDRESS, --address ADDRESS\n Bluetooth address (e.g. 12:34:56:78:9A:BC)\n -s SCAN_DURATION, --scan-duration SCAN_DURATION\n scan duration (default: 5 seconds)\n\nUsage of the library\n====================\n\nThe functionality of the command-line program can also be used in your own Python programs by using this project as a library.\n\nSee the `module reference <https://bluetooth-clocks.readthedocs.io/en/latest/api/modules.html>`_ for complete API documentation.\n\n.. inclusion-marker-before-license\n\nDocumentation\n=============\n\nRead the `online documentation <https://bluetooth-clocks.readthedocs.io>`_ of Bluetooth Clocks.\n\nLearn more about Bluetooth Low Energy development\n=================================================\n\nIf 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 <https://koen.vervloesem.eu/books/develop-your-own-bluetooth-low-energy-applications/>`_ and the accompanying GitHub repository `koenvervloesem/bluetooth-low-energy-applications <https://github.com/koenvervloesem/bluetooth-low-energy-applications>`_.\n\nLicense\n=======\n\nThis project is provided by Koen Vervloesem as open source software with the MIT license. See the `LICENSE <https://github.com/koenvervloesem/bluetooth-clocks/blob/main/LICENSE.txt>`_ file for more information.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Set and get the time on various Bluetooth Low Energy clocks",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/koenvervloesem/bluetooth-clocks/blob/main/CHANGELOG.rst",
"Documentation": "https://bluetooth-clocks.readthedocs.io/",
"Download": "https://pypi.org/project/bluetooth-clocks/#files",
"Homepage": "https://github.com/koenvervloesem/bluetooth-clocks",
"Source": "https://github.com/koenvervloesem/bluetooth-clocks",
"Tracker": "https://github.com/koenvervloesem/bluetooth-clocks/issues"
},
"split_keywords": [
"bluetooth",
"ble",
"bluetooth-low-energy",
"clocks",
"time",
"time-synchronization",
"get-time",
"set-time",
"current-time-service"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6d99088d67c58c0158a15bbb5502f88e4de538efa1de96653d12bef43f175e0",
"md5": "f56b278a500ec886ba9f85d0871655a6",
"sha256": "099c7cd989323fbefce3ed998859e7a52c432c8fd9f26d75de29939d1e04fef3"
},
"downloads": -1,
"filename": "bluetooth_clocks-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f56b278a500ec886ba9f85d0871655a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20462,
"upload_time": "2023-07-04T13:35:36",
"upload_time_iso_8601": "2023-07-04T13:35:36.274512Z",
"url": "https://files.pythonhosted.org/packages/b6/d9/9088d67c58c0158a15bbb5502f88e4de538efa1de96653d12bef43f175e0/bluetooth_clocks-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "77cf6d677e33e696173a88263b234043b7ae057f7107ff82f8eeb8015d53a82a",
"md5": "79faa05070962e161ba6caf4e60fff28",
"sha256": "42bf2cec2cdafa0d435050c12f0cc192a42d59148badf96b18bfce7dcc06abbe"
},
"downloads": -1,
"filename": "bluetooth-clocks-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "79faa05070962e161ba6caf4e60fff28",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 532660,
"upload_time": "2023-07-04T13:35:38",
"upload_time_iso_8601": "2023-07-04T13:35:38.324688Z",
"url": "https://files.pythonhosted.org/packages/77/cf/6d677e33e696173a88263b234043b7ae057f7107ff82f8eeb8015d53a82a/bluetooth-clocks-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-04 13:35:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "koenvervloesem",
"github_project": "bluetooth-clocks",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "bluetooth-clocks"
}
JSON
