rcvd-py/README

RCVD.py: sync BLE-enabled Casio watches from Python 3
-----------------------------------------------------
The RCVD project is now fully ported to Python 3. This is an application that
allows you to synchronize time and date on your Bluetooth LE enabled Casio
wristwatches (see supported models in the FAQ section). The original concept
was created for KaiOS 2.5.x and Web Bluetooth API enabled browsers in 2022.
This version is a standalone CLI application but optionally can be used as
a library.

== Dependencies ==

RCVD.py has been tested on Python 3.10 and depends on these libraries:
bleak (0.21.1+), asyncio (3.4.3+) and ntplib (0.4.0+). Just install all of
them by running pip install -r requirements.txt from the project directory.

Of course, you need to run RCVD on a PC with a Bluetooth 4.0+ adapter or on
another Bluetooth-enabled device that supports Bluetooth LE.

== Usage ==

RCVD can be run like this:

python rcvd.py [-h] [-t timeout] [-d delta] [-s ntp_server] [-n ntp_version]

All parameters are optional here:

* -h: display help screen
* -t: BLE scanning timeout in seconds (default 4)
* -d: manual delta correction in milliseconds (default 500, see below)
* -s: specify NTP server to fetch time from (if no server is specified, then
      local system time is used)
* -n: specify NTP protocol version to use, default is 4, good for most cases

After running the command, you must press the corresponding time sync button
on your watch (usually the lower right) to put it into the BLE sync mode. If
possible, press this button at the same time as running the command, but a
short delay (within the timeout specified with -t parameter) is allowed. Once
the watch is connected and the handshake is performed, RCVD will fetch the
current time from the specified source (local system time by default, or the
NTP server of your choice) and set it on the watch. Look for the OK indicator
on the watch itself to confirm that the setting process has been successful.
Refer to the manual for your model on how to do that.

Depending on your specific watch and host Bluetooth hardware, you may need to
set a different delta correction value to account for transmission losses.
You can do this by altering the -d parameter when running the command. This
parameter defines how many milliseconds are added to the time value to be 
immediately set on the watch. It is 500 ms by default, but tends to be more on
the digital Casio models, so you need to find out yourself which delta gives
the most accurate time setting as a result.

== FAQ ==

- How is this better than the official (and unofficial) Casio syncing apps?

As of now, RCVD focuses on doing one thing well and works on any CLI-enabled
platform, as opposed to the official Casio apps only working on mobile OSes.
It doesn't aim to replace them. Just as its JS-based predecessor, RCVD.py is
a lightweight alternative for those who just want to sync time on the watches
and nothing else.

- Which Casio models are supported as of now?

The following models were directly tested with both (JS and Python) versions:
GW-B5600, GMW-B5000, OCW-T200, GM-B2100, DW-B5600, GA-B001.

The following models were directly tested with the Python version:
ABL-100.

The following models are theoretically supported too but not directly tested:
MRG-B5000, GWR-B1000, GA-B2100, GST-B400, GST-B500, ECB-S100, MSG-B100,
ECB-2000, ECB-2200, G-B001, TRN-50, GD-B500.

If RCVD works with one of the above models (or with some other ones), please
let me know at https://matrix.to/#/@luxferre:hackliberty.org and I'll mark it
as tested.

- Will both JS and Python versions be developed in parallel?

Most likely, no. If there is an issue that really needs to be fixed in the
KaiOS/JS version of RCVD, the fix will be backported there, but all new
feature development will only be focused upon in the Python version, i.e. this
one. This version, by the way, already is ahead of the JS version because it
already integrates NTP support.

For any new Casio models though, if the basic time sync support is trivial to
add into the Python version, it will most likely be added to the JS version as
well.

- Are there going to be advanced features for the models supporting them, like
  alarm setting, reminders, DST rules, timezone DB, waypoints etc?

Probably. Not in the short term though. And it will most likely be a separate
script using rcvd.py as a library.

- Are there going to be any features utilizing "phone finder" and autosync?

A research is planned in both of these directions, but, again, its results
will be implemented in separate applications, not in this one.

== Credits ==

Original research, JS library and KaiOS application by Luxferre, 2022.
Ported to Python in 2024. Released into public domain with no warranties.