rcvd

README.md (3973B)

---

 # RCVD: sync BLE-enabled Casio watches from KaiOS and modern Web
 
 RCVD is the missing KaiOS application and, first and foremost, a [JS library](rcvd.js) that allows you to interact with a set of most recent Casio watches via Bluetooth 4.0LE communication protocol.
 
 ## Why?
 
 - Official Casio apps like G-Shock Connected, Oceanus Connected etc. are too bulky, proprietary and opaque, require too many permissions to work and only available for two major mobile platforms.
 - The only existing FOSS alternative for the time being is no less bulky, written for Android only, has a lot of obscure and suboptimal code and also doesn't solve Android's problem with location permission required to be granted to use BLE scanning.
 - As such, up until this point, there was no way to sync these watches from a Bluetooth-enabled PC in a fully cross-platform way. 
 - Up until this point, KaiOS also didn't have any simple and straightforward examples of working with Bluetooth GATT characteristics on real-world consumer-grade devices.
 - BLE Web API interfaces totally differ across KaiOS and modern browsers, so the lowest-level abstraction layer is still necessary.
 
 ## Supported host platforms
 
 - As a certified app: KaiOS 2.5.x (install directly from this repo via WebIDE);
 - As a JS library: Chrome 85+, Opera 43+, Edge 79+ and other modern Chromium-based browsers (including Android ones) except the ones with support explicitly disabled, such as Brave. 
 
 ## Supported models
 
 - GW-B5600
 - GMW-B5000
 - MRG-B5000\*
 - OCW-T200
 - GWR-B1000\*
 - GM-B2100
 - GA-B2100\*
 - GST-B400\*
 - GST-B500\*
 - ECB-S100\*
 - MSG-B100\*
 - ECB-2000\*
 - ECB-2200\*
 - DW-B5600
 - GA-B001
 - G-B001\*
 
 The list is incomplete and your watch may be supported too. Please [let me know](https://matrix.to/#/@luxferre:hackliberty.org) if this is the case!
 
 \* *model theoretically supported but not checked by the author*
 
 ## How to use the app
 
 1. Ensure your phone time is synced from the network.
 2. Open the app and press SYNC (central D-pad key).
 3. Enter the fast or full sync mode on your watch (depends on your model, please refer to the manual).
 4. Wait until the time is set. If the app cannot connect, retry steps 2-3 until the app says your model is synced.
 
 ## How to use the library
 
 The [library](rcvd.js) can be used "as is" or as a building block for more advanced tools. For its purposes, it exposes several methods:
 
 - `RCVD.connect() -> Promise` - connect to a watch, perform the necessary handshake operations and resolve the Promise on success;
 - `RCVD.disconnect()` - disconnect from the currently connected watch's GATT server;
 - `RCVD.sync(Date obj?) -> Promise` - perform time synchronization with the **optional** Date object (if it's not passed, actual current local time will be set), running all the required DST/world time setting cycles before setting the actual time;
 - `RCVD.setSyncDelta(ms)` - update the delta value (in milliseconds) to add to the current time before synchronization to make up for the Bluetooth transmission delay (500 ms by default, can be adjusted according to your host and watch latency);
 - `RCVD.getModel() -> String` - return the watch model name obtained during the connection process;
 - `RCVD.rawRead(uint8 param1, uint8 param2...) -> Promise(Uint8Array)` - accept variable number of integer parameters and execute the read command on the watch, resolving to the result in a Uint8Array value;
 - `RCVD.rawWrite(Uint8Array command) -> Promise` - accept a write command shaped as byte data in Uint8Array and resolve on successful write operation.
 
 The last two methods are not used in the app directly in their exposed format, but allow to use the library to easily create more advanced applications to interact with Casio watches based on already known protocol details, without having to worry about low-level connectivity bits.
 
 ## Credits
 
 Created by Luxferre in 2022. Both the app and the library are released into public domain.
 
 Made in Ukraine.