Add README.

diff --git a/README b/README
index 8b137891791fe96927ad78e64b0aad7bded08bdc..165d0cc3970347c2c5b0ea25f489c0ab18b6766c 100644 (file)
--- a/README
+++ b/README
@@ -1 +1,110 @@
+gps-watch
+=========
 
+This is custom firmware for the Decathlon Kalenji OnMove 220 and
+OnMove 500 GPS watches.
+
+
+Supported features
+------------------
+
+* Show GPS fix status
+* Display current time (UTC)
+* Start recording, stop recording
+* Display meters travelled in current recording
+* Display pace in current recording
+* Shell interface that offers listing, removing and retrieving of recordings
+
+
+Unsupported features
+--------------------
+
+* Backlight
+* Battery level measurement
+* Pulse measurement unit
+
+
+Supported watch models
+----------------------
+
+This firmware is known to work with Decathlon Kalenji OnMove 220 and
+OnMove 500 watches.
+
+
+Build
+-----
+
+This firmware is written in Rust and C and thus the build requires `rustc`
+and gcc for ARM Cortex M0+ targets. By default, the build system uses
+the `arm-none-eabi` toolchain for the latter.
+
+Run `scons` to build the firmware and test programs.
+
+
+Installation
+------------
+
+This firmware can be installed on supported watches without opening them up.
+To do so, we will first install an intermediate bootloader at the flash's
+location for the application firmware (0x8000) and run it.
+Afterwards, we can install the final bootloader at flash offset 0x0,
+then we can install the custom application firmware at 0x8000.
+
+Note that doing this has the potential to brick your watch.
+
+Instructions:
+1. Register udev rules with the system:
+```
+sudo install -o root -g root -m 0644 contrib/99-gps-watch.rules /etc/udev/rules.d
+sudo udevadm control -R
+```
+2. Connect watch via USB.
+3. Mount watch's USB mass storage to `/mnt`.
+4. Install intermediate bootloader. Instructions vary slightly depending on your watch's model.
+
+For OnMove 220:
+```cp build-target/gps-watch-bootloader-intermediate.frm /mnt/firm220.frm```
+For OnMove 500:
+```cp build-target/gps-watch-bootloader-intermediate.frm /mnt/firm500.frm```
+5. Unmount watch's USB mass storage.
+6. Press watch's "Brightness" (middle left) button to initiate firmware update.
+7. Install final bootloader:
+```
+tools/update-firmware -d /dev/gps-watch-bootloader-intermediate -o 0x0 -l 4 -wv build-target/gps-watch-bootloader-final.bin
+```
+8. Start final bootloader and prepare to press and hold the "Brightness" button (middle left):
+```
+tools/update-firmware -d /dev/gps-watch-bootloader-intermediate -l 4 -s
+```
+9. Press and hold the "Brightness" button to avoid booting into application code.
+10. Install and start application firmware:
+```
+tools/update-firmware -d /dev/gps-watch-bootloader -o 0x8000 -l 4 -wvs build-target/gps-watch-application.bin
+```
+11. After a couple of seconds, the watch should show up as `/dev/gps-watch`.
+
+To update a watch to a later build, run the following command while the watch
+is still in the bootloader (see below):
+```
+tools/update-firmware -d /dev/gps-watch-bootloader -o 0x8000 -l 4 -wvs build-target/gps-watch-application.bin
+```
+
+
+Usage
+-----
+
+Connect the watch via USB, start a terminal program and point it at `/dev/gps-watch` to use the serial interface. Run the `help` command to get a list of supported commands.
+
+Note that the `clear_storage` command has the potential to brick your watch.
+Do *not* run it unless you have opened up your watch and connected it to a debugger!
+
+To start a new recording, or to stop a running recording, press and hold the "Play" button (upper right) for 1.5s.
+While a recording is running, press the "Next" or "Previous" button (lower left and lower right) to cycle through display of time, distance and pace.
+
+To retrieve a recording, run the `get` command in the shell interface, then make
+your terminal send an upper case `R` within 5s. This instructs the watch to
+send the recording's data in Y encoding (`yenc`). Running `tools/gpxify` on the
+decoded data yields a GPX file.
+
+To reset the watch, press the upper left and lower right buttons at the same time.
+The bootloader will avoid starting the application code if the "Brightness" button (middle left) is pressed in the first 3s after startup.