initial upload

README

@@ -0,0 +1,101 @@
+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 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.
+
+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.