From eb216dd9e6912e35f18c0bf62fd06ac6bdf4ad90 Mon Sep 17 00:00:00 2001 From: dtourolle Date: Wed, 5 Aug 2026 13:11:32 +0200 Subject: [PATCH] Scaffold workspace, shared types and requirements spec Cargo workspace with core/ble/fit/probe crates. crates/core/src/types.rs is the fixed contract between the BLE layer, ride engine and UI. Co-Authored-By: Claude Opus 5 --- .gitignore | 20 + Cargo.lock | 1335 +++++++++++++++++++++++++++ Cargo.toml | 32 + REQUIREMENTS.md | 675 ++++++++++++++ crates/ble/Cargo.toml | 14 + crates/ble/src/lib.rs | 1 + crates/core/Cargo.toml | 14 + crates/core/src/gpx.rs | 80 ++ crates/core/src/lib.rs | 17 + crates/core/src/physics.rs | 63 ++ crates/core/src/profile.rs | 235 +++++ crates/core/src/session.rs | 117 +++ crates/core/src/types.rs | 170 ++++ crates/fit/Cargo.toml | 10 + crates/fit/src/lib.rs | 1 + crates/probe/Cargo.toml | 20 + crates/probe/src/main.rs | 1 + src-tauri/Cargo.toml | 40 + src-tauri/build.rs | 3 + src-tauri/capabilities/default.json | 14 + src-tauri/tauri.conf.json | 48 + 21 files changed, 2910 insertions(+) create mode 100644 .gitignore create mode 100644 Cargo.lock create mode 100644 Cargo.toml create mode 100644 REQUIREMENTS.md create mode 100644 crates/ble/Cargo.toml create mode 100644 crates/ble/src/lib.rs create mode 100644 crates/core/Cargo.toml create mode 100644 crates/core/src/gpx.rs create mode 100644 crates/core/src/lib.rs create mode 100644 crates/core/src/physics.rs create mode 100644 crates/core/src/profile.rs create mode 100644 crates/core/src/session.rs create mode 100644 crates/core/src/types.rs create mode 100644 crates/fit/Cargo.toml create mode 100644 crates/fit/src/lib.rs create mode 100644 crates/probe/Cargo.toml create mode 100644 crates/probe/src/main.rs create mode 100644 src-tauri/Cargo.toml create mode 100644 src-tauri/build.rs create mode 100644 src-tauri/capabilities/default.json create mode 100644 src-tauri/tauri.conf.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..88e9522 --- /dev/null +++ b/.gitignore @@ -0,0 +1,20 @@ +# Rust +/target +**/*.rs.bk + +# Node +node_modules/ +dist/ +.vite/ + +# Tauri +src-tauri/target/ +src-tauri/gen/ + +# Editors / OS +.DS_Store +*.swp + +# Ride data +*.fit +/rides/ diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..6862968 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,1335 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "android_system_properties" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311" +dependencies = [ + "libc", +] + +[[package]] +name = "anyhow" +version = "1.0.104" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" + +[[package]] +name = "approx" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cab112f0a86d568ea0e627cc1d6be74a1e9cd55214684db5561995f6dad897c6" +dependencies = [ + "num-traits", +] + +[[package]] +name = "async-trait" +version = "0.1.91" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae36dc4177970ef04fde5178d3e2429882def40e57a451f919c098f72baa6cec" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.3", +] + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "bikecontrol-ble" +version = "0.1.0" +dependencies = [ + "bikecontrol-core", + "btleplug", + "futures", + "thiserror 2.0.19", + "tokio", + "tracing", + "uuid", +] + +[[package]] +name = "bikecontrol-core" +version = "0.1.0" +dependencies = [ + "approx", + "roxmltree", + "serde", + "serde_yaml_ng", + "thiserror 2.0.19", +] + +[[package]] +name = "bikecontrol-fit" +version = "0.1.0" +dependencies = [ + "bikecontrol-core", + "chrono", + "thiserror 2.0.19", +] + +[[package]] +name = "bikecontrol-probe" +version = "0.1.0" +dependencies = [ + "anyhow", + "bikecontrol-ble", + "bikecontrol-core", + "btleplug", + "futures", + "tokio", + "tracing", + "tracing-subscriber", + "uuid", +] + +[[package]] +name = "bitflags" +version = "2.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da" + +[[package]] +name = "block2" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2c132eebf10f5cad5289222520a4a058514204aed6d791f1cf4fe8088b82d15f" +dependencies = [ + "objc2", +] + +[[package]] +name = "bluez-async" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "84ae4213cc2a8dc663acecac67bbdad05142be4d8ef372b6903abf878b0c690a" +dependencies = [ + "bitflags", + "bluez-generated", + "dbus", + "dbus-tokio", + "futures", + "itertools", + "log", + "serde", + "serde-xml-rs", + "thiserror 2.0.19", + "tokio", + "uuid", +] + +[[package]] +name = "bluez-generated" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9676783265eadd6f11829982792c6f303f3854d014edfba384685dcf237dd062" +dependencies = [ + "dbus", +] + +[[package]] +name = "btleplug" +version = "0.11.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c9a11621cb2c8c024e444734292482b1ad86fb50ded066cf46252e46643c8748" +dependencies = [ + "async-trait", + "bitflags", + "bluez-async", + "dashmap 6.2.1", + "dbus", + "futures", + "jni", + "jni-utils", + "log", + "objc2", + "objc2-core-bluetooth", + "objc2-foundation", + "once_cell", + "static_assertions", + "thiserror 2.0.19", + "tokio", + "tokio-stream", + "uuid", + "windows", + "windows-future", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cc" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5add81bb678e6cb321aff7fa0dc7689ad82b112dbc032cea19f91d6b8e3582b9" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cesu8" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c" + +[[package]] +name = "cfg-if" +version = "1.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + +[[package]] +name = "chrono" +version = "0.4.45" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327" +dependencies = [ + "iana-time-zone", + "js-sys", + "num-traits", + "wasm-bindgen", + "windows-link 0.2.1", +] + +[[package]] +name = "combine" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd" +dependencies = [ + "bytes", + "memchr", +] + +[[package]] +name = "core-foundation-sys" +version = "0.8.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b" + +[[package]] +name = "crossbeam-utils" +version = "0.8.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "61803da095bee82a81bb1a452ecc25d3b2f1416d1897eb86430c6159ef717c17" + +[[package]] +name = "dashmap" +version = "5.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "978747c1d849a7d2ee5e8adc0159961c48fb7e5db2f06af6723b80123bb53856" +dependencies = [ + "cfg-if", + "hashbrown 0.14.5", + "lock_api", + "once_cell", + "parking_lot_core", +] + +[[package]] +name = "dashmap" +version = "6.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6361d5c062261c78a176addb82d4c821ae42bed6089de0e12603cd25de2059c" +dependencies = [ + "cfg-if", + "crossbeam-utils", + "hashbrown 0.14.5", + "lock_api", + "once_cell", + "parking_lot_core", +] + +[[package]] +name = "dbus" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ab69f03cc8c4340c9c8e315114e1658e6775a9b16a04357973aa21cec22b32e" +dependencies = [ + "futures-channel", + "futures-util", + "libc", + "libdbus-sys", + "windows-sys", +] + +[[package]] +name = "dbus-tokio" +version = "0.7.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "007688d459bc677131c063a3a77fb899526e17b7980f390b69644bdbc41fad13" +dependencies = [ + "dbus", + "libc", + "tokio", +] + +[[package]] +name = "either" +version = "1.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e5e8f6c15a24b9a3ee5efec809ccd006d3b30e8b3bb63c39af737c7f87daa1d" + +[[package]] +name = "equivalent" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "find-msvc-tools" +version = "0.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + +[[package]] +name = "futures" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a88cf1f829d945f548cf8fec32c61b1f202b6d93b45848602fc02af4b12ad218" +dependencies = [ + "futures-channel", + "futures-core", + "futures-executor", + "futures-io", + "futures-sink", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-channel" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "262590f4fe6afeb0bc83be1daa64e52657fe185690a958af7f3ad0e92085c5ae" +dependencies = [ + "futures-core", + "futures-sink", +] + +[[package]] +name = "futures-core" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7" + +[[package]] +name = "futures-executor" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6754879cc9f2c66f88c6e5c35344bb0bdb0708b0352b1201815667c7eabc7458" +dependencies = [ + "futures-core", + "futures-task", + "futures-util", +] + +[[package]] +name = "futures-io" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4577ecaa3c4f96589d473f679a71b596316f6641bc350038b962a5daf0085d7a" + +[[package]] +name = "futures-macro" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2d6d3cde68c518367be28956066ddfef33813991b77a55005a69dae04bf3b10b" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "futures-sink" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e34418ac499d6305c2fb5ad0ed2f6ac998c5f8ca209b4510f7f94242c647e307" + +[[package]] +name = "futures-task" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b231ed28831efb4a61a08580c4bc233ec56bc009f4cd8f52da2c3cb97df0c109" + +[[package]] +name = "futures-util" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa" +dependencies = [ + "futures-channel", + "futures-core", + "futures-io", + "futures-macro", + "futures-sink", + "futures-task", + "memchr", + "pin-project-lite", + "slab", +] + +[[package]] +name = "hashbrown" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "iana-time-zone" +version = "0.1.65" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470" +dependencies = [ + "android_system_properties", + "core-foundation-sys", + "iana-time-zone-haiku", + "js-sys", + "log", + "wasm-bindgen", + "windows-core 0.62.2", +] + +[[package]] +name = "iana-time-zone-haiku" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f" +dependencies = [ + "cc", +] + +[[package]] +name = "indexmap" +version = "2.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9" +dependencies = [ + "equivalent", + "hashbrown 0.17.1", +] + +[[package]] +name = "itertools" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285" +dependencies = [ + "either", +] + +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + +[[package]] +name = "jni" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6df18c2e3db7e453d3c6ac5b3e9d5182664d28788126d39b91f2d1e22b017ec" +dependencies = [ + "cesu8", + "combine", + "jni-sys 0.3.1", + "log", + "thiserror 1.0.69", + "walkdir", +] + +[[package]] +name = "jni-sys" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "41a652e1f9b6e0275df1f15b32661cf0d4b78d4d87ddec5e0c3c20f097433258" +dependencies = [ + "jni-sys 0.4.1", +] + +[[package]] +name = "jni-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c6377a88cb3910bee9b0fa88d4f42e1d2da8e79915598f65fb0c7ee14c878af2" +dependencies = [ + "jni-sys-macros", +] + +[[package]] +name = "jni-sys-macros" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "38c0b942f458fe50cdac086d2f946512305e5631e720728f2a61aabcd47a6264" +dependencies = [ + "quote", + "syn 2.0.119", +] + +[[package]] +name = "jni-utils" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "259e9f2c3ead61de911f147000660511f07ab00adeed1d84f5ac4d0386e7a6c4" +dependencies = [ + "dashmap 5.5.3", + "futures", + "jni", + "log", + "once_cell", + "static_assertions", + "uuid", +] + +[[package]] +name = "js-sys" +version = "0.3.103" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "lazy_static" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe" + +[[package]] +name = "libc" +version = "0.2.189" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2" + +[[package]] +name = "libdbus-sys" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "328c4789d42200f1eeec05bd86c9c13c7f091d2ba9a6ea35acdf51f31bc0f043" +dependencies = [ + "pkg-config", +] + +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + +[[package]] +name = "log" +version = "0.4.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad" + +[[package]] +name = "matchers" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9" +dependencies = [ + "regex-automata", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "mio" +version = "1.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30d65c71f1ce40ab09135ce117d742b9f8a19ff91a41a8b57ed50bc2de59c427" +dependencies = [ + "libc", + "wasi", + "windows-sys", +] + +[[package]] +name = "nu-ansi-term" +version = "0.50.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", +] + +[[package]] +name = "objc-sys" +version = "0.3.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb91bdd390c7ce1a8607f35f3ca7151b65afc0ff5ff3b34fa350f7d7c7e4310" + +[[package]] +name = "objc2" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46a785d4eeff09c14c487497c162e92766fbb3e4059a71840cecc03d9a50b804" +dependencies = [ + "objc-sys", + "objc2-encode", +] + +[[package]] +name = "objc2-core-bluetooth" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a644b62ffb826a5277f536cf0f701493de420b13d40e700c452c36567771111" +dependencies = [ + "bitflags", + "objc2", + "objc2-foundation", +] + +[[package]] +name = "objc2-encode" +version = "4.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ef25abbcd74fb2609453eb695bd2f860d389e457f67dc17cafc8b8cbc89d0c33" + +[[package]] +name = "objc2-foundation" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ee638a5da3799329310ad4cfa62fbf045d5f56e3ef5ba4149e7452dcf89d5a8" +dependencies = [ + "bitflags", + "block2", + "libc", + "objc2", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "parking_lot" +version = "0.12.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a" +dependencies = [ + "lock_api", + "parking_lot_core", +] + +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link 0.2.1", +] + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "pkg-config" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "roxmltree" +version = "0.20.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6c20b6793b5c2fa6553b250154b78d6d0db37e72700ae35fad9387a46f487c97" + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "ryu" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde-xml-rs" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc2215ce3e6a77550b80a1c37251b7d294febaf42e36e21b7b411e0bf54d540d" +dependencies = [ + "log", + "serde", + "thiserror 2.0.19", + "xml", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.3", +] + +[[package]] +name = "serde_yaml_ng" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7b4db627b98b36d4203a7b458cf3573730f2bb591b28871d916dfa9efabfd41f" +dependencies = [ + "indexmap", + "itoa", + "ryu", + "serde", + "unsafe-libyaml", +] + +[[package]] +name = "sharded-slab" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6" +dependencies = [ + "lazy_static", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "signal-hook-registry" +version = "1.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b" +dependencies = [ + "errno", + "libc", +] + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.15.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90" + +[[package]] +name = "socket2" +version = "0.6.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4" +dependencies = [ + "libc", + "windows-sys", +] + +[[package]] +name = "static_assertions" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f" + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53e9bae58849f64dfa4f5d5ae372c8341f7305f82a3868709269343628b659a3" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", +] + +[[package]] +name = "thiserror" +version = "2.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09a43598840e33d5b0331f38c5e30d13bb11c11210a4b58f0d9b18a5a5eefcd9" +dependencies = [ + "thiserror-impl 2.0.19", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "43cbfe0cf76104d42a574802844187e84a305e531ed54455f11fbde0f10541cd" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.3", +] + +[[package]] +name = "thread_local" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "tokio" +version = "1.53.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed" +dependencies = [ + "bytes", + "libc", + "mio", + "parking_lot", + "pin-project-lite", + "signal-hook-registry", + "socket2", + "tokio-macros", + "windows-sys", +] + +[[package]] +name = "tokio-macros" +version = "2.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "78773a2a397f451582ce068015985c33193cf6dea8b74d2a639fe457b2f07b0e" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.3", +] + +[[package]] +name = "tokio-stream" +version = "0.1.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a3d06f0b082ba57c26b79407372e57cf2a1e28124f78e9479fe80322cf53420b" +dependencies = [ + "futures-core", + "pin-project-lite", + "tokio", + "tokio-util", +] + +[[package]] +name = "tokio-util" +version = "0.7.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "494815d09bf52b5548659851081238f0ca39ff638363907596da739561c62c52" +dependencies = [ + "bytes", + "futures-core", + "futures-sink", + "pin-project-lite", + "tokio", +] + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-attributes", + "tracing-core", +] + +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", + "valuable", +] + +[[package]] +name = "tracing-log" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3" +dependencies = [ + "log", + "once_cell", + "tracing-core", +] + +[[package]] +name = "tracing-subscriber" +version = "0.3.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319" +dependencies = [ + "matchers", + "nu-ansi-term", + "once_cell", + "regex-automata", + "sharded-slab", + "smallvec", + "thread_local", + "tracing", + "tracing-core", + "tracing-log", +] + +[[package]] +name = "unicode-ident" +version = "1.0.24" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + +[[package]] +name = "unsafe-libyaml" +version = "0.2.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "673aac59facbab8a9007c7f6108d11f63b603f7cabff99fabf650fea5c32b861" + +[[package]] +name = "uuid" +version = "1.24.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bf3923a6f5c4c6382e0b653c4117f48d631ea17f38ed86e2a828e6f7412f5239" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "valuable" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65" + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasm-bindgen" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4" +dependencies = [ + "cfg-if", + "once_cell", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 2.0.119", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.126" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys", +] + +[[package]] +name = "windows" +version = "0.61.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893" +dependencies = [ + "windows-collections", + "windows-core 0.61.2", + "windows-future", + "windows-link 0.1.3", + "windows-numerics", +] + +[[package]] +name = "windows-collections" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3beeceb5e5cfd9eb1d76b381630e82c4241ccd0d27f1a39ed41b2760b255c5e8" +dependencies = [ + "windows-core 0.61.2", +] + +[[package]] +name = "windows-core" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0fdd3ddb90610c7638aa2b3a3ab2904fb9e5cdbecc643ddb3647212781c4ae3" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link 0.1.3", + "windows-result 0.3.4", + "windows-strings 0.4.2", +] + +[[package]] +name = "windows-core" +version = "0.62.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb" +dependencies = [ + "windows-implement", + "windows-interface", + "windows-link 0.2.1", + "windows-result 0.4.1", + "windows-strings 0.5.1", +] + +[[package]] +name = "windows-future" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e" +dependencies = [ + "windows-core 0.61.2", + "windows-link 0.1.3", + "windows-threading", +] + +[[package]] +name = "windows-implement" +version = "0.60.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-interface" +version = "0.59.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "windows-link" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a" + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-numerics" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9150af68066c4c5c07ddc0ce30421554771e528bde427614c61038bc2c92c2b1" +dependencies = [ + "windows-core 0.61.2", + "windows-link 0.1.3", +] + +[[package]] +name = "windows-result" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56f42bd332cc6c8eac5af113fc0c1fd6a8fd2aa08a0119358686e5160d0586c6" +dependencies = [ + "windows-link 0.1.3", +] + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link 0.2.1", +] + +[[package]] +name = "windows-strings" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56e6c93f3a0c3b36176cb1327a4958a0353d5d166c2a35cb268ace15e91d3b57" +dependencies = [ + "windows-link 0.1.3", +] + +[[package]] +name = "windows-strings" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091" +dependencies = [ + "windows-link 0.2.1", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link 0.2.1", +] + +[[package]] +name = "windows-threading" +version = "0.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b66463ad2e0ea3bbf808b7f1d371311c80e115c0b71d60efc142cafbcfb057a6" +dependencies = [ + "windows-link 0.1.3", +] + +[[package]] +name = "xml" +version = "1.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "636f85e5ca6488e96401b61eb7de54f4e44755c988af0f52cf90230c312a1a89" diff --git a/Cargo.toml b/Cargo.toml new file mode 100644 index 0000000..f69ff02 --- /dev/null +++ b/Cargo.toml @@ -0,0 +1,32 @@ +[workspace] +resolver = "2" +members = ["crates/core", "crates/ble", "crates/fit", "crates/probe"] + +[workspace.package] +version = "0.1.0" +edition = "2021" +license = "MIT" +repository = "https://github.com/dtourolle/BikeControl" + +[workspace.dependencies] +bikecontrol-core = { path = "crates/core" } +bikecontrol-ble = { path = "crates/ble" } +bikecontrol-fit = { path = "crates/fit" } + +anyhow = "1" +thiserror = "2" +serde = { version = "1", features = ["derive"] } +serde_json = "1" +serde_yaml_ng = "0.10" +tokio = { version = "1", features = ["rt-multi-thread", "macros", "sync", "time"] } +tracing = "0.1" +tracing-subscriber = { version = "0.3", features = ["env-filter"] } +btleplug = "0.11" +futures = "0.3" +uuid = "1" +roxmltree = "0.20" +chrono = "0.4" + +[profile.release] +lto = true +opt-level = 3 diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..25233da --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,675 @@ +# BikeControl — Requirements Specification + +**Status:** Draft v0.4 +**Date:** 2026-08-05 +**Target hardware:** Van Rysel D100 trainer + Zwift Cog + **Zwift Click v2** + +> **v0.4 changes — the input decision is reversed.** Further research found that the Click +> v2 "unlock" is **performed by the rider in the free Zwift app**, not by the consuming +> application, and that it then works with *any* third-party app for ~24 h (§2.3). Combined +> with three open-source implementations of the Zwift protocol — one **GPL-3.0**, one +> **MIT** (§3.4–3.6) — **the app talks to the Click v2 directly over BLE.** v0.3's +> OpenBikeControl bridge is dropped: **there is no fallback input path.** New risk: the +> **left pod**, where third-party support is weakest, now carries all gradient and route +> control with nothing behind it (RISK-9). + +--- + +## 1. Overview + +BikeControl is a desktop-first (Android-later) application that connects to a Van Rysel +D100 smart trainer and a handlebar controller over Bluetooth Low Energy, and provides: + +- **Virtual shifting** on the single-cog drivetrain, via the Click's shift paddles. +- **Handlebar gradient control**, via the Click's D-pad. +- **Gradient-adaptive routes** driven from GPX or hand-authored profiles. +- **Synthetic waveform profiles** — sine, square, ramp — applied to resistance, gradient + or target power. +- **Ride recording** exported as a FIT file. +- **A GUI** for connection management and live telemetry visualisation. + +### 1.1 Goals + +| ID | Goal | +|----|------| +| G-1 | Ride a gradient profile end-to-end without touching the computer once started | +| G-2 | Control gearing and gradient entirely from the bars | +| G-3 | Produce a FIT file that imports cleanly into Strava / Garmin Connect | +| G-4 | Run on Linux desktop today; port to Android without rewriting the core | +| G-5 | Fail safe — never leave the trainer at high resistance after a fault | +| G-6 | Prefer documented, openly-licensed protocols; keep any proprietary protocol handling isolated and replaceable | + +### 1.2 Non-goals + +- Multiplayer, social features, or any network service. +- 3D world rendering or avatars. +- ANT+ support (§10.1). +- **Implementing the Click v2 unlock ourselves.** The rider performs it in the free Zwift + app (§2.3); we only need to speak the protocol afterwards. +- Acting as a bridge for *other* training apps — that is what the existing BikeControl + app does, and this project does not duplicate it. +- Any secondary input protocol. The Click v2 client is the only input path. + +--- + +## 2. Hardware & Operating Assumptions + +### 2.1 Van Rysel D100 ✅ + +**FTMS support confirmed** by a working MIT-licensed implementation built specifically for +this trainer (§3.2). + +| Property | Value | Confidence | +|----------|-------|------------| +| Bluetooth profile | FTMS (`0x1826`) | **Confirmed** | +| Target power (`0x05`) | Supported; reference clamps 100–600 W | **Confirmed** | +| Target resistance (`0x04`) | Supported, sint16; reference caps at 100 | **Confirmed** | +| Target inclination (`0x03`) | Implemented in the reference as sint16 | **Confirmed** | +| Sim mode (`0x11`) | Not used by the reference | **Unconfirmed — TASK-1** | +| Concurrent BLE hosts | Assume **one** | Assumed | + +> **A-1:** The reference drives grade via `SetTargetInclination` (`0x03`), not +> `SetIndoorBikeSimulationParameters` (`0x11`). TASK-1 resolves whether `0x11` works. Low +> impact either way, because the app owns the physics (FR-7.1). + +### 2.2 Zwift Cog + +A single 14T cog — **no mechanical gears**. This is why virtual shifting (§5.4) is a core +requirement, not a nicety: without it the rider has exactly one gear. + +### 2.3 Zwift Click v2 ⚠ + +The unit is a **v2** (two pods: navigation D-pad on the left, lettered face buttons on the +right, a shift paddle under each). This is the harder variant, and the difference is not +merely one of degree. + +**The unlock is performed by the rider, not by the app.** This is the key finding of v0.4 +and it changes everything. The Click v2's encryption context times out roughly a minute +after it leaves a Zwift session; refreshing it requires the official Zwift app. But once +refreshed, **the device works with *any* third-party app for ~24 hours**. + +The rider's procedure — **free, no paid subscription required**: + +1. Open the Zwift app (desktop or mobile) and log in. +2. Go to the device pairing screen; pair the Click. +3. Keep it connected 10–30 seconds while pressing a button. +4. Close Zwift completely. + +> **A-2:** BikeControl 6.0.0 (June 2026) added a keep-alive that removes the daily unlock +> entirely — but only for the **right** controller, only for paid Pro users, and the +> implementation lives in a **private submodule**. We therefore assume the manual daily +> unlock. Replicating the keep-alive is explicitly out of scope; see §1.2. + +### 2.3.1 Zwift BLE protocol + +Established from three independent open-source implementations (§3.4–3.6). + +| Item | Value | +|------|-------| +| Custom service | `00000001-19CA-4651-86E5-FA29DCDD09D1` | +| Async (notify) | `00000002-…` — button notifications | +| Sync RX (write) | `00000003-…` — commands to device | +| Sync TX (indicate) | `00000004-…` — responses | +| Unknown (indicate/read/write) | `00000006-…` — purpose undetermined | +| Manufacturer ID | 2378 (`0x094A`); device byte `0x09` = Click v1, `0x0A`/`0x0B` = v2 | +| Handshake | Write `RideOn` (`52 69 64 65 4F 6E`) + 2 bytes to Sync RX; device replies on Sync TX | +| Message types | `0x07` controller notification · `0x15` empty/keepalive · `0x19` battery · `0x37` Click button state (two protobuf varints) | + +**Encryption.** The handshake performs a key exchange and messages are then encrypted: + +| Stage | Mechanism | +|-------|-----------| +| Key agreement | **ECDH on NIST P-256** (`prime256v1`); each side sends a public key | +| Key derivation | **HKDF** → 36 bytes: bytes 0–31 = AES key, bytes 32–35 = IV | +| Cipher | **AES-256-CCM**, 4-byte MAC | +| Framing | 4-byte big-endian counter prepended per message; nonce = IV ‖ counter | + +All of this maps onto pure-Rust RustCrypto crates (`p256`, `hkdf`, `sha2`, `aes`, `ccm`), +so no C dependency is needed. + +> **A-3:** At least one implementation connects to a Click **without** encryption and still +> receives button and battery events (§3.6). Whether that holds for a v2 is unknown — +> TASK-0 tests the unencrypted path first, since it would be far simpler. + +### 2.4 Environmental assumptions + +- **A-3:** BLE peripherals accept a single central connection. Only one host may hold the + trainer, and only one may hold the Click. +- **A-4:** The trainer wakes on pedalling; the Click wakes on button press. Either may be + absent from a scan until woken — the UI must say so rather than report "not found". + +--- + +## 3. Prior Art, Reuse and the Input Decision + +### 3.1 `OpenBikeControl/bikecontrol` — Zwift device reference ⚠ + +Flutter/Dart, 589★, actively maintained. A *bridge* app that translates controller input +into actions for other training apps. Not used as a component here, but its public source +documents Zwift device discrimination (manufacturer-data type bytes, v1 vs v2 response +codes) and the shape of the v2 unlock. + +> **⚠ Licensing.** Current versions are a custom **Non-Commercial** licence (© +> OpenBikeControl UG): personal/educational use only, source-only redistribution under the +> same terms, no commercial use, no marketplace distribution, and the grant is +> **revocable**. Versions before the `gpl3` tag were **GPL-3.0** (copyleft). **No code is +> copied from it** — treat it as a map, and confirm bytes against the device. + +### 3.2 `obostjancic/smart-trainer-control` — D100 FTMS reference ✅ + +React/TypeScript, Web Bluetooth, **MIT**. Literally *"Control a Van Rysel D100 smart +trainer from your browser"*. Working FTMS client, control-point encoders, and FIT and TCX +writers with tests. + +**MIT means this logic can be ported freely, with attribution.** It pre-solves most of +TASK-1 and de-risks the FIT writer. + +### 3.3 `OpenBikeControl/openbikecontrol-protocol` — considered, not used + +An MIT open standard (service `d273f680-…`) for controllers to drive trainer apps, with +Python references for both sides. v0.3 proposed consuming it via a bridge process. **That +approach is dropped** — it required a second app running during every ride. Recorded here +only so the decision is not silently revisited. + +### 3.4 `cagnulein/qdomyos-zwift` (QZ) — GPL-3.0 Zwift protocol implementation ⭐ + +C++/Qt, 826★, **GPL-3.0**. `src/zwift_play/` contains a complete working implementation: +`zapCrypto.h` (ECDH/HKDF/AES-CCM), `localKeyProvider.h` (P-256 keygen), `zapBleUuids.h`, +`zapConstants.h`, `abstractZapDevice.h` (handshake), and `zwiftclickremote.cpp`. + +**This is the reference that makes direct Click v2 support tractable.** It is the source of +the crypto details in §2.3.1. + +> **Licensing:** GPL-3.0 is copyleft. **Porting this code makes BikeControl GPL-3.0.** The +> underlying algorithm — ECDH P-256 + HKDF + AES-256-CCM — is standard cryptography and not +> itself copyrightable, so a clean implementation from the *documented* protocol (§2.3.1) is +> unencumbered. See OQ-9. + +### 3.5 `ajchellew/zwiftplay` — the original reverse-engineering ⚠ + +Kotlin/Android + a C# Windows console app. The origin of most public knowledge here, +including the packet captures, the `RideOn` handshake, and the fourth (`…0006-…`) +characteristic. + +> **⚠ No LICENSE file — all rights reserved.** Excellent *documentation*, but **no code may +> be copied from it.** Its README is the citable protocol description. + +### 3.6 `jat255/zwift_click_handling` — MIT, Python, Linux/BlueZ ✅ + +A small **MIT** script using `bleak` on Linux that connects to a Click and logs button +press/release and battery level. Notably it connects **without encryption** and still +receives events (A-3), and it carries the protocol constants in reusable form. + +**MIT and already proven on Linux/BlueZ** — the natural basis for the `probe` tool. + +### 3.7 Decision: direct Click v2, no fallback + +v0.3 routed all input through a bridge process because the unlock looked insurmountable. +The research above shows it is not: **the rider performs the unlock in the free Zwift app, +and the protocol afterwards is fully documented across three open implementations.** + +``` +Zwift Click v2 ──BLE, ECDH P-256 + HKDF + AES-256-CCM──► This app + (rider unlocks daily in the free Zwift app) +``` + +| | | +|---|---| +| **No second app during rides** | The bridge's real cost was a process running every session. A once-daily 30-second unlock is a far smaller tax. | +| **The protocol is documented** | §2.3.1 is a complete spec, corroborated by three independent implementations. | +| **Standard crypto, pure Rust** | `p256`, `hkdf`, `sha2`, `aes`, `ccm` — no C dependency, no bespoke cryptography. | +| **Lower latency** | No intermediate hop in the NFR-1 budget. | +| **One code path** | No input abstraction to maintain, no divergence between paths. | + +**Accepted consequence.** There is no second way in. If a Zwift firmware update breaks the +client, or the left pod proves unreliable (RISK-9), controller input is lost until the +client is fixed — the keyboard and on-screen controls (FR-3.19) are the only stopgap. This +is a deliberate trade of resilience for simplicity. + +> **OQ-9 — licensing.** Porting QZ's crypto directly makes this project **GPL-3.0**. Writing +> it from the documented algorithm keeps the licence open. Which do you want? For a personal +> project GPL-3.0 costs nothing. + +--- + +## 4. Technology Stack + +**Tauri v2**, Rust core + web frontend. Confirmed; we port rather than import. + +| Layer | Choice | Notes | +|-------|--------|-------| +| Shell | Tauri v2 | Desktop + Android from one codebase | +| Core | Rust | BLE, physics, profiles, gearing, FIT | +| BLE | `btleplug` via `tauri-plugin-blec` | blec supplies Android JNI/permission plumbing | +| Crypto | `p256`, `hkdf`, `sha2`, `aes`, `ccm` | Click v2 session (§2.3.1); pure Rust, no OpenSSL | +| Frontend | Web — Svelte recommended | Connection UI, telemetry | +| Charts | `uPlot` | Canvas, built for streaming series | +| FIT | Ported from §3.2 (MIT) | See RISK-3 | + +**Architectural constraint.** The control loop lives in **Rust, not JavaScript**. +`tauri-plugin-blec` is designed to expose BLE to the frontend; we use its Rust-side API and +keep all device I/O, physics and state in the core. The frontend renders telemetry pushed +over Tauri events and issues intents as commands. This keeps the safety-critical path (§7) +independent of the webview and the core testable without a UI. + +``` +bikecontrol/ +├── crates/ +│ ├── core/ # physics, profiles, gearing, state machine — no BLE, no UI +│ ├── ble/ # FTMS client, Zwift Click v2 client (handshake + crypto) +│ ├── fit/ # FIT encoder (ported from §3.2) +│ └── probe/ # CLI for protocol discovery (Phase 0) +├── src-tauri/ # Tauri shell, commands, event bridge +└── ui/ # web frontend +``` + +--- + +## 5. Functional Requirements + +### 5.1 Device discovery and connection (FR-1) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-1.1 | Scan for BLE peripherals; list name, address, RSSI, advertised services | Must | +| FR-1.2 | Identify trainers by FTMS service UUID and Click pods by the Zwift custom service UUID plus manufacturer-data type byte | Must | +| FR-1.3 | Connect to trainer and controller independently; either may connect first | Must | +| FR-1.4 | Track the left and right pods as separate connections, since each is an independent peripheral | Must | +| FR-1.5 | Remember paired devices and auto-connect on launch | Should | +| FR-1.6 | Auto-reconnect on unexpected disconnect, with backoff, without ending the ride | Must | +| FR-1.7 | Surface per-device connection state (scanning / connecting / connected / lost) | Must | +| FR-1.8 | When nothing is found, prompt to wake the device (per A-4) — pedal the trainer, press a Click button | Must | +| FR-1.9 | Allow riding with the trainer alone; on-screen and keyboard controls substitute | Must | + +### 5.2 Trainer control (FR-2) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-2.1 | Acquire FTMS control (`0x00`) before issuing commands | Must | +| FR-2.2 | Subscribe to Indoor Bike Data (`0x2AD2`); decode all present fields per the flags bitfield | Must | +| FR-2.3 | Set gradient via `SetTargetInclination` (`0x03`), or `0x11` if TASK-1 confirms support | Must | +| FR-2.4 | Set resistance via `SetTargetResistanceLevel` (`0x04`) | Must | +| FR-2.5 | Set target power via `SetTargetPower` (`0x05`) — needed for ERG waveforms | Must | +| FR-2.6 | Read and respect `Fitness Machine Feature` (`0x2ACC`) and `Supported Resistance Level Range` (`0x2AD6`); never send out-of-range values | Must | +| FR-2.7 | Handle control-point indications including error responses, not fire-and-forget | Must | +| FR-2.8 | Rate-limit control writes (≤4 Hz target) | Must | + +**Decoding note (FR-2.2):** Indoor Bike Data is variable-length, determined by a leading +16-bit flags field. **Bit 0 is inverted** — instantaneous speed is present when the bit is +*clear*. Fields must be consumed strictly in specification order. + +### 5.3 Controller input (FR-3) + +Input comes from the **Zwift Click v2 over BLE, directly** (§2.3.1). There is no bridge and +no secondary protocol path. + +**Direct Click v2 client** + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-3.1 | Discover Click pods by Zwift custom service UUID plus manufacturer data; identify left vs right pod | Must | +| FR-3.2 | Perform the `RideOn` handshake and establish the encrypted session — ECDH P-256 → HKDF → AES-256-CCM (§2.3.1) | Must | +| FR-3.3 | Attempt the **unencrypted** path first (A-3) and fall back to encrypted — it is far simpler if the v2 permits it | Should | +| FR-3.4 | Connect **both pods concurrently**; each is an independent BLE peripheral | Must | +| FR-3.5 | Decode controller notifications into press/release events for every button on both pods | Must | +| FR-3.6 | Handle keepalive/empty messages (`0x15`) and maintain the session | Must | +| FR-3.7 | Decode battery level (`0x19`) per pod and warn when low | Should | + +**Unlock handling — the app guides, the rider performs** + +The unlock happens in the Zwift app (§2.3). This application never performs it, never asks +for Zwift credentials, and never talks to Zwift's servers. It detects the state and walks +the rider through the steps. + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-3.8 | Detect the locked failure mode — notifications stop roughly a minute after connecting — and distinguish it from an ordinary dropout | Must | +| FR-3.9 | Track the last known-good unlock per pod and show remaining validity against the ~24 h window | Must | +| FR-3.10 | **Guide** the rider through the unlock with explicit ordered steps (open Zwift → log in → pairing screen → pair the Click → hold a button 10–30 s → close Zwift → return here) | Must | +| FR-3.11 | State plainly that no paid Zwift subscription is required | Should | +| FR-3.12 | Warn before a ride starts when the unlock is stale, expiring soon, or unknown | Must | +| FR-3.13 | Detect and confirm success automatically once events resume, closing the guidance without the rider having to declare it worked | Should | +| FR-3.14 | Offer "mark as unlocked" for riders who unlocked outside the app | Could | +| FR-3.15 | Never store Zwift credentials or contact Zwift services | Must | + +**Input handling** + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-3.16 | Debounce input; support press, release and hold-to-repeat | Must | +| FR-3.17 | All bindings user-configurable; the mapping below is the default | Should | +| FR-3.18 | Hold on D-pad up/down repeats the gradient step at a fixed rate | Should | +| FR-3.19 | Keyboard and on-screen controls mirror every action — needed to develop and test the app before the Click client works, and to keep a ride going if a pod dies mid-session | Must | + +**Button mapping.** Per OQ-1: shift paddles shift, D-pad handles gradient. + +| Click v2 control | Pod | Action | +|------------------|-----|--------| +| Shift paddle `+` | Right | Virtual gear **up** | +| Shift paddle `−` | Left | Virtual gear **down** | +| D-pad up | Left | Gradient **+0.5%** | +| D-pad down | Left | Gradient **−0.5%** | +| D-pad left | Left | **Previous** route / profile | +| D-pad right | Left | **Next** route / profile | +| Face button A | Right | Cycle control mode (§5.4) | +| Face button Z | Right | Reset gradient offset to zero | +| Face button B | Right | Pause / resume ride | +| Face button Y | Right | Insert lap marker | + +> **RISK-9 applies here.** Every gradient and route control sits on the **left** pod, which +> is where third-party support is weakest (§10). With no bridge fallback, the left pod is a +> single point of failure for gradient control — TASK-0 must prove it works before this +> mapping is committed to. + +### 5.4 Control modes (FR-4) + +| ID | Mode | Behaviour | Priority | +|----|------|-----------|----------| +| FR-4.1 | **Virtual gearing** | Paddles shift a configurable virtual cassette; resistance follows gear × terrain | **Must** | +| FR-4.2 | **Manual grade** | D-pad adjusts simulated gradient in ±0.5% steps | Must | +| FR-4.3 | **Resistance** | Buttons step trainer resistance directly, ignoring physics | Must | +| FR-4.4 | **Route** | Gradient driven by route profile at current distance; paddles shift | Must | +| FR-4.5 | **Waveform** | Gradient/resistance/power driven by a synthetic profile (§5.6) | Must | +| FR-4.6 | **ERG** | Trainer holds a fixed target power | Should | + +Gearing and gradient are **simultaneously active**, not alternatives — the paddles always +shift while the D-pad always trims gradient. "Mode" selects where the *base* gradient comes +from (manual, route, or waveform). + +**Virtual shifting design (FR-4.1).** No mechanical shifting exists, and FTMS has no +virtual-shifting opcode. Approach: + +1. Define a virtual cassette: N gears (default ~24), ratios configurable. +2. The app owns the physics (FR-7.1), so it knows the wheel force required for the current + virtual speed and gradient. +3. The selected gear sets the cadence needed to hold that speed: + `cadence = v / (gear_ratio × wheel_circumference)`. +4. The app sets trainer resistance so effort at that cadence matches the physics — + effectively `resistance = f(gradient, speed, gear_ratio)`. +5. Mapping that target onto a D100 resistance level needs **empirical calibration** of the + trainer's resistance curve (TASK-3). + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-4.1.1 | Configurable gear count and ratios, with sensible defaults | Must | +| FR-4.1.2 | Display current gear prominently, with clear feedback on each shift | Must | +| FR-4.1.3 | Clamp at top and bottom gear; never wrap around | Must | +| FR-4.1.4 | Shift response ≤250 ms end-to-end (NFR-1) | Must | +| FR-4.1.5 | Persist gear selection across a reconnect | Should | + +### 5.5 Routes (FR-5) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-5.1 | Import GPX; derive a distance/elevation profile | Must | +| FR-5.2 | Smooth GPX elevation before differentiating into gradients — raw GPS elevation is far too noisy to send to a trainer | Must | +| FR-5.3 | Clamp derived gradients to a configurable range (default −10%…+15%) | Must | +| FR-5.4 | Hand-authored routes as an ordered segment list in a human-editable file | Must | +| FR-5.5 | Interpolate between profile points so grade changes are continuous, not stepped | Must | +| FR-5.6 | Support looping, and support finishing at the end | Should | +| FR-5.7 | Show distance covered, remaining, and elevation profile with current position | Must | +| FR-5.8 | Cycle routes from the D-pad mid-ride (`0x12`/`0x13`) | Must | + +### 5.6 Synthetic waveform profiles (FR-6) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-6.1 | Waveform types: **sine, square, triangle, sawtooth, ramp, constant** | Must | +| FR-6.2 | Apply to any of three channels: **gradient (%)**, **resistance level**, **target power (W)** | Must | +| FR-6.3 | Parameterise by amplitude, midpoint, period, phase, and duration or repeat count | Must | +| FR-6.4 | Support **time-based** and **distance-based** periods | Should | +| FR-6.5 | Compose into a sequence of blocks — warm-up ramp, sine intervals, cool-down | Must | +| FR-6.6 | Share a file format with hand-authored routes, so a profile may mix terrain and waveform blocks | Should | +| FR-6.7 | Render a preview chart before the ride; show position within it during | Must | +| FR-6.8 | Clamp generated values to the safe range at transmission (SAF-3) | Must | +| FR-6.9 | Smooth transitions between blocks so the trainer does not step discontinuously | Should | + +**Illustrative format** (TBD): + +```yaml +name: "Over-unders + hill repeats" +blocks: + - { type: ramp, channel: power, from_w: 100, to_w: 200, duration_s: 600 } + - { type: sine, channel: power, midpoint_w: 240, amplitude_w: 40, + period_s: 120, repeats: 8 } + - { type: segments, channel: gradient, loop: true, segments: [ + { distance_m: 800, gradient_pct: 6.5 }, + { distance_m: 400, gradient_pct: -3.0 } ] } + - { type: constant, channel: power, watts: 120, duration_s: 300 } +``` + +### 5.7 Ride engine (FR-7) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-7.1 | Compute virtual speed from measured power, gradient and mass — the app owns the physics rather than trusting the trainer's reported speed | Must | +| FR-7.2 | Integrate speed into distance, which drives route position | Must | +| FR-7.3 | Model inertia so speed changes feel natural rather than snapping to steady state | Must | +| FR-7.4 | Expose rider mass, bike mass, Crr, CdA and wheel circumference as configurable | Must | +| FR-7.5 | Use the trainer's reported speed as diagnostic/fallback only | Should | +| FR-7.6 | Track elapsed time, moving time, elevation gained, average and normalised power | Should | + +``` +F_propulsive = (P_measured × drivetrain_efficiency) / max(v, v_min) +F_gravity = m × g × sin(atan(gradient)) +F_rolling = m × g × Crr × cos(atan(gradient)) +F_aero = ½ × ρ × CdA × v² +a = (F_propulsive − F_gravity − F_rolling − F_aero) / m +v += a × Δt (clamped at ≥ 0) +``` + +Owning the physics is a prerequisite for virtual shifting, makes behaviour reproducible in +tests, and removes dependence on the trainer's internal mass assumptions. + +### 5.8 Recording and export (FR-8) + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-8.1 | Record a 1 Hz series: timestamp, power, cadence, speed, distance, gradient, gear, mode | Must | +| FR-8.2 | Export a valid FIT activity (file_id, session, lap, record, activity; correct CRC) | Must | +| FR-8.3 | Verify exported FIT files import into Strava and Garmin Connect | Must | +| FR-8.4 | Persist the raw series so a FIT can be regenerated after a crash | Must | +| FR-8.5 | Continue recording across a BLE dropout, marking the gap rather than aborting | Must | +| FR-8.6 | Write incrementally — a crash must not lose the session | Must | +| FR-8.7 | Record lap markers triggered from the controller (`0x35`) | Should | + +> Only FIT export was requested. In-app ride *history* is not in scope for v1 — the FIT +> file is the ride artifact. FR-8.4's raw log is crash safety, not a history feature. + +### 5.9 GUI (FR-9) + +**Connection screen** + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-9.1 | Live device list with signal strength and identified type | Must | +| FR-9.2 | Per-device connect / disconnect / forget, with clear state and error text | Must | +| FR-9.3 | Show FTMS control acquisition separately from BLE connection — connected ≠ controllable | Must | +| FR-9.4 | Show per-pod connection and unlock state, with a **guided walkthrough** of the Zwift unlock (FR-3.10) launched from here and from any locked-state warning | Must | + +**Ride screen** + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-9.5 | Large, legible readouts (power, cadence, speed, gradient, gear, elapsed) readable at ~1 m | Must | +| FR-9.6 | Live streaming charts of power and gradient/target | Must | +| FR-9.7 | Route elevation profile or waveform preview with current position marked | Must | +| FR-9.8 | Prominent display of active mode, current gear, and current target | Must | +| FR-9.9 | Visible feedback on every button press, so the rider knows input registered | Must | +| FR-9.10 | On-screen and keyboard equivalents for all controller actions | Must | +| FR-9.11 | Instantaneous power is noisy — show a rolling average alongside or instead | Should | +| FR-9.12 | Dark theme suitable for indoor training | Should | + +**Post-ride** + +| ID | Requirement | Priority | +|----|-------------|----------| +| FR-9.13 | Summary: duration, distance, elevation, average/max power, average cadence | Must | +| FR-9.14 | Save FIT to a chosen location, with the path confirmed | Must | + +--- + +## 6. Non-Functional Requirements + +| ID | Requirement | +|----|-------------| +| NFR-1 | **Input latency** — button press to trainer resistance change ≤ 250 ms | +| NFR-2 | **Telemetry** — process trainer notifications at native rate (1–4 Hz) without backlog | +| NFR-3 | **UI** — charts stay smooth for a 2-hour ride without unbounded memory growth | +| NFR-4 | **Resilience** — no BLE dropout, malformed packet or missing characteristic may crash the app | +| NFR-5 | **Portability** — `core` and `fit` compile for Android with no platform-specific code | +| NFR-6 | **Offline** — full functionality with no internet connection. The app never contacts Zwift or any other service; only the rider's separate daily unlock needs the internet | +| NFR-7 | **Startup** — launch to scanning in under 3 seconds | +| NFR-8 | **Observability** — all BLE traffic loggable at debug level, including decrypted Click frames, for protocol diagnosis | + +--- + +## 7. Safety Requirements + +| ID | Requirement | +|----|-------------| +| SAF-1 | On controller disconnect, hold the last target — never continue applying pending increments | +| SAF-2 | On app exit, crash, or ride end, reset the trainer to 0% grade / minimum resistance | +| SAF-3 | Clamp gradient, resistance and target power to configurable safe ranges **at the point of transmission**, regardless of source | +| SAF-4 | If the trainer stops acknowledging control-point writes, stop sending and alert the rider | +| SAF-5 | Never issue a step larger than one configured increment per input event | +| SAF-6 | Waveform parameter errors must not command an unsafe target (enforced by SAF-3) | +| SAF-7 | A stale or replayed Click frame must not re-trigger an action — enforce the session counter and reject out-of-order frames | + +--- + +## 8. Architecture + +``` +┌──────────────────────────────────────────────────────┐ +│ Frontend (webview) │ +│ Connection manager · Gauges · uPlot · Profile editor│ +└──────────────▲────────────────────────┬──────────────┘ + events │ │ commands +┌──────────────┴────────────────────────▼──────────────┐ +│ Rust core │ +│ ┌──────────┐ ┌──────────┐ ┌─────────┐ ┌──────────┐ │ +│ │ Ride │ │ Profile │ │ Virtual │ │ Recorder │ │ +│ │ engine │◄┤ engine │ │ gearing │ │ → FIT │ │ +│ │(physics) │ │(GPX/wave)│ └────┬────┘ └──────────┘ │ +│ └────▲─────┘ └──────────┘ │ target │ +│ ┌────┴───────────┐ ┌──────────▼──────┐ │ +│ │ FTMS client │ │ Click v2 client │ │ +│ │ (trainer, BLE) │ │ (BLE + crypto) │ │ +│ └────────▲───────┘ └────────▲────────┘ │ +│ │ btleplug / blec │ │ +└───────────┼───────────────────┼──────────────────────┘ + │ │ ECDH P-256 → HKDF + │ │ → AES-256-CCM + ┌──────┴──────┐ ┌──────┴──────────────┐ + │ D100 │ │ Click v2 L + R pods │ + └─────────────┘ └─────────────────────┘ + ▲ + daily unlock performed + by the rider in Zwift +``` + +--- + +## 9. Delivery Plan + +### Phase 0 — D100 protocol discovery *(blocking for Phase 1)* + +| Task | Description | +|------|-------------| +| **TASK-1** | `probe` against the D100: enumerate services, dump `Fitness Machine Feature` and `Supported Resistance Level Range`, log decoded Indoor Bike Data, resolve whether `0x11` works (A-1) | +| **TASK-2** | Write control commands to the D100; confirm physical resistance change | + +**Exit criteria:** telemetry decodes correctly and a written command produces a felt +resistance change. + +### Phase 0b — Deferred discovery *(blocking for Phase 3 only)* + +| Task | Description | +|------|-------------| +| **TASK-0** | **Prove the Click v2 — the riskiest thing in the project.** Unlock both pods in the Zwift app, then with `probe`: (a) try the **unencrypted** path (A-3); (b) if that fails, do the full `RideOn` + ECDH/HKDF/AES-CCM handshake; (c) log raw and decrypted frames against a known button sequence; (d) **confirm every button on *both* pods registers** (RISK-9); (e) measure how long events survive without a fresh unlock. Prototyping in Python against §3.6's MIT code is legitimate — the goal is knowledge, not shipped code | +| **TASK-3** | **Characterise the D100 resistance curve** — required to map virtual gears onto it (FR-4.1) | +| **TASK-4** | Android BLE spike: minimal Tauri v2 Android build scanning via `blec` (RISK-1) | + +> If TASK-0(d) fails on the left pod, resolve OQ-10 before building the button mapping. + +### Phase 1 — D100 + GUI + profiles ⭐ *(current focus)* + +**The Click is deferred to Phase 3.** All control in this phase is on-screen; the app is +fully rideable from the keyboard and mouse before any Zwift protocol work begins. This +removes the only component with unknown protocol risk from the critical path. + +FR-1 (trainer only), FR-2, FR-4.2/4.3/4.4/4.5, FR-5 (GPX), FR-6 (waveforms), FR-7 +(physics), FR-3.19 (keyboard/on-screen), FR-9.1–9.3, 9.5–9.8, 9.10–9.12, §7 safety. + +*Milestone: load a GPX or a sine-wave profile, ride it, and control gradient from the GUI.* + +### Phase 2 — Recording +FR-8 (recording, FIT, crash safety), FR-9.13/9.14. +*Milestone: a ride lands in Strava.* + +### Phase 3 — Zwift Click v2 +TASK-0 (protocol discovery), then FR-3.1–3.18, FR-9.4, FR-4.1 (virtual gearing, which needs +TASK-3's resistance-curve calibration), RISK-9 resolution. +*Milestone: shift gears and trim gradient from the bars.* + +### Phase 4 — Polish and stretch +FR-1.5 (auto-connect), FR-3.7 (battery), FR-3.14 (mark as unlocked), FR-3.17 (rebinding), +FR-4.6 (ERG), FR-9.11/9.12, Android. + +--- + +## 10. Risks + +| ID | Risk | Impact | Mitigation | +|----|------|--------|------------| +| **RISK-1** | `btleplug`'s Android backend is the least mature part of the stack | Android target lost | TASK-4 spikes it in Phase 0 | +| **RISK-2** | Virtual shifting feel may be poor if the D100's resistance curve is coarse or laggy | Core feature degraded | TASK-3 characterises it early; fall back to fewer, wider-spaced gears | +| **RISK-3** | Rust FIT *encoders* are thin — most crates read rather than write | FR-8.2 slips | Port the MIT writer from §3.2; TCX fallback | +| **RISK-4** | **No fallback input path (§3.7).** A firmware change or a protocol error leaves no second way in | Controller input lost entirely until the client is fixed | Accepted deliberately. Keep protocol handling isolated in `ble`; pin known-good behaviour in tests; keyboard/on-screen controls (FR-3.19) are the only stopgap | +| **RISK-5** | The Click v2 crypto is more involved than the D100 work — ECDH, HKDF, AES-CCM, session counters — and a subtle error yields silence rather than a clear failure | Phase 1 slips | Three reference implementations to check against (§3.4–3.6); `probe` logs raw and decrypted frames side by side (NFR-8) | +| **RISK-6** | The unencrypted path (A-3) may not work on a v2, forcing full crypto immediately | Less schedule slack | TASK-0 tests it first; the crypto path is specified either way | +| **RISK-7** | The unlock expires ~24 h, so a forgotten re-unlock blocks a ride | Frustration at session start | Detect and warn *before* the ride (FR-3.12), with a guided walkthrough (FR-3.10) | +| **RISK-8** | D100 lacks `0x11` sim mode | Reduced fidelity | Low impact — the app owns the physics | +| **RISK-9** | **The left pod is where third-party support is weakest.** QZ has an open `wontfix` issue where the left Click's `−` never registers, and BikeControl's keep-alive covers only the right pod. All gradient and route control is mapped to the left pod | Gradient and route control lost; shifting-up survives | **TASK-0 proves both pods before the mapping is committed.** If the left pod is unreliable, remap onto the right pod and move gradient to a modifier gesture | + +### 10.1 On ANT+ + +The D100 likely supports ANT+ FE-C, which permits multiple simultaneous connections and +would sidestep BLE contention. Excluded because it needs a USB stick on desktop and is +effectively dead on Android — the opposite of G-4. Revisit only if BLE contention proves +intolerable. + +--- + +## 11. Open Questions + +| ID | Question | +|----|----------| +| **OQ-2** | Gradient step size — is ±0.5% per D-pad press right? And what repeat rate on hold? | +| **OQ-3** | How many virtual gears, and what ratio spread? (Default: 24, roughly a 2×12 road setup.) | +| **OQ-4** | Should route mode auto-advance to the next route on completion, or stop and wait? | +| **OQ-5** | Is heart rate wanted? A BLE HRM strap is a small increment now and awkward to retrofit into the FIT writer later. | +| **OQ-6** | Which frontend framework? Svelte recommended. | +| **OQ-9** | *(§3.7)* Port QZ's GPL-3.0 crypto and licence this project GPL-3.0, or reimplement from the documented algorithm and stay unencumbered? | +| **OQ-10** | If TASK-0 shows the left pod is unreliable (RISK-9), do you want gradient remapped onto the right pod, or would you rather chase the left-pod bug? | + +**Resolved:** OQ-1 (paddles shift, D-pad adjusts gradient) · OQ-7 (stay on Tauri, port the +MIT logic) · OQ-8 (no bridge, no fallback input path) · Click version (v2). + +--- + +## 12. Glossary + +| Term | Meaning | +|------|---------| +| **FTMS** | Fitness Machine Service — standard BLE profile for trainer telemetry and control | +| **Pod** | One half of a Click v2 — left (D-pad) or right (face buttons); each is an independent BLE peripheral | +| **Unlock** | Refreshing the Click v2's encryption context via the free Zwift app; lasts ~24 h | +| **ECDH / HKDF / AES-CCM** | The key agreement, key derivation and cipher used by the Zwift session (§2.3.1) | +| **ERG mode** | Trainer holds fixed target power regardless of cadence | +| **Sim mode** | Trainer applies resistance simulating a gradient; power varies with rider effort | +| **Virtual shifting** | Synthesising gear changes by varying trainer resistance, on a single-cog drivetrain | +| **Crr** | Coefficient of rolling resistance | +| **CdA** | Drag coefficient × frontal area | +| **Normalised power** | Weighted average power reflecting physiological cost of variable efforts | diff --git a/crates/ble/Cargo.toml b/crates/ble/Cargo.toml new file mode 100644 index 0000000..6ab6926 --- /dev/null +++ b/crates/ble/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "bikecontrol-ble" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +bikecontrol-core = { workspace = true } +btleplug = { workspace = true } +tokio = { workspace = true } +futures = { workspace = true } +uuid = { workspace = true } +thiserror = { workspace = true } +tracing = { workspace = true } diff --git a/crates/ble/src/lib.rs b/crates/ble/src/lib.rs new file mode 100644 index 0000000..14f3033 --- /dev/null +++ b/crates/ble/src/lib.rs @@ -0,0 +1 @@ +//! FTMS client and BLE transport. See REQUIREMENTS.md §5.1–5.2. diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml new file mode 100644 index 0000000..a8c044e --- /dev/null +++ b/crates/core/Cargo.toml @@ -0,0 +1,14 @@ +[package] +name = "bikecontrol-core" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +serde = { workspace = true } +serde_yaml_ng = { workspace = true } +thiserror = { workspace = true } +roxmltree = { workspace = true } + +[dev-dependencies] +approx = "0.5" diff --git a/crates/core/src/gpx.rs b/crates/core/src/gpx.rs new file mode 100644 index 0000000..fa05c0c --- /dev/null +++ b/crates/core/src/gpx.rs @@ -0,0 +1,80 @@ +//! GPX import: turn a recorded ride into a gradient profile (§5.5). +//! +//! The hard part is not parsing — it is that **raw GPS elevation is far too +//! noisy to differentiate directly** (FR-5.2). Differentiating unsmoothed +//! elevation produces wild gradient spikes that would make the trainer lurch. +//! Elevation must be smoothed before gradients are derived, and the result +//! clamped (FR-5.3). + +use crate::profile::{Profile, TerrainPoint}; + +/// A single trackpoint read from a GPX file. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct TrackPoint { + pub lat_deg: f64, + pub lon_deg: f64, + pub elevation_m: f32, +} + +/// Tuning for elevation smoothing and gradient derivation. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct SmoothingConfig { + /// Resample the track to this spacing before differentiating, in metres. + /// Larger values give smoother, less twitchy gradients. + pub resample_m: f64, + /// Width of the smoothing window, in metres. + pub window_m: f64, + pub min_gradient_pct: f32, + pub max_gradient_pct: f32, +} + +impl Default for SmoothingConfig { + fn default() -> Self { + Self { + resample_m: 10.0, + window_m: 100.0, + min_gradient_pct: -10.0, + max_gradient_pct: 15.0, + } + } +} + +#[derive(Debug, thiserror::Error)] +pub enum GpxError { + #[error("malformed GPX: {0}")] + Malformed(String), + #[error("GPX contains no track points with elevation")] + NoElevation, + #[error("GPX track is too short to derive a gradient profile")] + TooShort, +} + +/// Parse the track points out of a GPX document. +/// +/// Must tolerate real-world GPX: `//` and `/`, +/// missing `` on some points, multiple segments, and namespaced documents. +pub fn parse(xml: &str) -> Result, GpxError> { + let _ = xml; + todo!("implemented in crates/core/src/gpx.rs — see AGENT task A") +} + +/// Great-circle distance between two points, in metres. +pub fn haversine_m(a: TrackPoint, b: TrackPoint) -> f64 { + let _ = (a, b); + todo!("implemented in crates/core/src/gpx.rs — see AGENT task A") +} + +/// Turn track points into a smoothed, clamped gradient profile. +pub fn to_terrain( + points: &[TrackPoint], + cfg: &SmoothingConfig, +) -> Result, GpxError> { + let _ = (points, cfg); + todo!("implemented in crates/core/src/gpx.rs — see AGENT task A") +} + +/// Convenience: GPX document to a ready-to-ride single-block profile. +pub fn import(xml: &str, name: &str, cfg: &SmoothingConfig) -> Result { + let _ = (xml, name, cfg); + todo!("implemented in crates/core/src/gpx.rs — see AGENT task A") +} diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs new file mode 100644 index 0000000..6f82e73 --- /dev/null +++ b/crates/core/src/lib.rs @@ -0,0 +1,17 @@ +//! Pure ride logic: physics, profiles, GPX import and session state. +//! +//! This crate has no I/O and no platform dependencies (NFR-5). Everything here +//! is unit-testable with synthetic telemetry, and it must stay that way — BLE +//! lives in `bikecontrol-ble`, file writing in `bikecontrol-fit`. + +pub mod gpx; +pub mod physics; +pub mod profile; +pub mod session; +pub mod types; + +pub use profile::{Block, Channel, Extent, Profile, Segment, Waveform}; +pub use session::{RideSession, SessionEvent}; +pub use types::{ + ConnectionState, ControlMode, ControlTarget, RideSnapshot, RiderConfig, SafetyLimits, Telemetry, +}; diff --git a/crates/core/src/physics.rs b/crates/core/src/physics.rs new file mode 100644 index 0000000..c759947 --- /dev/null +++ b/crates/core/src/physics.rs @@ -0,0 +1,63 @@ +//! Virtual speed from measured power (§5.7 of REQUIREMENTS.md). +//! +//! The app owns the physics rather than trusting the trainer's reported speed +//! (FR-7.1). This makes ride behaviour reproducible in tests, independent of +//! the trainer's internal mass assumptions, and is a prerequisite for virtual +//! gearing later. +//! +//! Per tick: +//! ```text +//! F_propulsive = (P × drivetrain_efficiency) / max(v, v_min) +//! F_gravity = m × g × sin(atan(gradient)) +//! F_rolling = m × g × Crr × cos(atan(gradient)) +//! F_aero = ½ × ρ × CdA × v² +//! a = (F_propulsive − F_gravity − F_rolling − F_aero) / m +//! v += a × Δt (clamped at ≥ 0) +//! ``` + +use crate::types::RiderConfig; + +pub const GRAVITY: f32 = 9.80665; + +/// Speed floor used to keep `P / v` finite at a standstill. Also the speed +/// below which the rider is considered stopped. +pub const MIN_SPEED_MPS: f32 = 0.5; + +/// Evolving physical state of the virtual rider. +#[derive(Debug, Clone, Copy, PartialEq, Default)] +pub struct PhysicsState { + /// Virtual speed, metres per second. + pub speed_mps: f32, + /// Virtual distance travelled, metres. + pub distance_m: f64, + /// Cumulative elevation gained, metres. + pub elevation_gain_m: f32, +} + +impl PhysicsState { + /// Advance the simulation by `dt` seconds under `power_w` at `gradient_pct`. + /// + /// Must model inertia (FR-7.3) — speed accelerates toward equilibrium + /// rather than snapping to it — and must never produce negative speed, + /// NaN, or unbounded values for any finite input. + pub fn step(&mut self, power_w: f32, gradient_pct: f32, cfg: &RiderConfig, dt: f32) { + let _ = (power_w, gradient_pct, cfg, dt); + todo!("implemented in crates/core/src/physics.rs — see AGENT task A") + } + + pub fn speed_kph(&self) -> f32 { + self.speed_mps * 3.6 + } + + pub fn is_moving(&self) -> bool { + self.speed_mps > MIN_SPEED_MPS + } +} + +/// Steady-state speed for a given power and gradient — the speed at which +/// propulsive and resistive forces balance. Useful for tests and for sanity +/// checks on the resistance curve later. +pub fn equilibrium_speed_mps(power_w: f32, gradient_pct: f32, cfg: &RiderConfig) -> f32 { + let _ = (power_w, gradient_pct, cfg); + todo!("implemented in crates/core/src/physics.rs — see AGENT task A") +} diff --git a/crates/core/src/profile.rs b/crates/core/src/profile.rs new file mode 100644 index 0000000..8fbee65 --- /dev/null +++ b/crates/core/src/profile.rs @@ -0,0 +1,235 @@ +//! Ride profiles: terrain segments, synthetic waveforms, and the file format +//! that carries both (§5.5, §5.6 of REQUIREMENTS.md). +//! +//! A profile is an ordered list of blocks. Each block drives one channel +//! (gradient, resistance or power) for either a duration or a distance. The +//! engine asks the profile for a target given elapsed time and distance +//! travelled, and the profile decides which block is active and what it wants. + +use serde::{Deserialize, Serialize}; + +use crate::types::ControlTarget; + +/// Which trainer parameter a block drives (FR-6.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum Channel { + Gradient, + Resistance, + Power, +} + +/// Waveform shapes (FR-6.1). All are evaluated as a function of phase in +/// `[0, 1)` and produce a value in `[-1, 1]`, which the block then scales by +/// amplitude and offsets by midpoint. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "lowercase")] +pub enum Waveform { + Sine, + Square, + Triangle, + Sawtooth, +} + +impl Waveform { + /// Evaluate at `phase` in `[0, 1)`, returning `[-1, 1]`. + pub fn eval(self, phase: f32) -> f32 { + let p = phase.rem_euclid(1.0); + match self { + Waveform::Sine => (p * std::f32::consts::TAU).sin(), + Waveform::Square => { + if p < 0.5 { + 1.0 + } else { + -1.0 + } + } + Waveform::Triangle => { + // Rises 0→1 over the first quarter, falls 1→-1, returns to 0. + 4.0 * (p - (p + 0.25).floor()).abs() - 1.0 + } + Waveform::Sawtooth => 2.0 * p - 1.0, + } + } +} + +/// How a block measures its own extent — by time or by distance (FR-6.4). +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Extent { + Seconds(f64), + Metres(f64), +} + +/// A single terrain segment: hold a gradient for a distance (FR-5.4). +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub struct Segment { + pub distance_m: f64, + pub gradient_pct: f32, +} + +/// One block of a profile. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +#[serde(tag = "type", rename_all = "lowercase")] +pub enum Block { + /// Hold a fixed value. + Constant { + channel: Channel, + value: f32, + extent: Extent, + }, + /// Linear sweep between two values. + Ramp { + channel: Channel, + from: f32, + to: f32, + extent: Extent, + }, + /// Oscillate around a midpoint. + Wave { + channel: Channel, + shape: Waveform, + midpoint: f32, + amplitude: f32, + /// Length of one full cycle. + period: Extent, + /// Number of cycles. Total extent = period × repeats. + repeats: f32, + /// Phase offset in `[0, 1)`. + #[serde(default)] + phase: f32, + }, + /// A terrain profile: gradient as a function of distance, interpolated + /// between points (FR-5.5). + Segments { segments: Vec }, + /// A gradient/distance profile derived from a GPX import. Points are + /// cumulative distance in metres paired with gradient in percent. + Terrain { points: Vec }, +} + +/// One point of an elevation-derived gradient profile. +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub struct TerrainPoint { + pub distance_m: f64, + pub gradient_pct: f32, + /// Elevation in metres, retained for display of the profile chart. + pub elevation_m: f32, +} + +/// A complete ride profile. +#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)] +pub struct Profile { + pub name: String, + #[serde(default)] + pub description: Option, + pub blocks: Vec, + /// Restart from the beginning on completion (FR-5.6). + #[serde(default)] + pub looping: bool, +} + +/// Where the rider currently is within a profile. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct Position { + pub elapsed_s: f64, + pub distance_m: f64, +} + +#[derive(Debug, thiserror::Error)] +pub enum ProfileError { + #[error("failed to parse profile: {0}")] + Parse(String), + #[error("profile has no blocks")] + Empty, + #[error("block {index} is invalid: {reason}")] + InvalidBlock { index: usize, reason: String }, +} + +impl Profile { + /// Parse a profile from YAML. + pub fn from_yaml(src: &str) -> Result { + let profile: Profile = + serde_yaml_ng::from_str(src).map_err(|e| ProfileError::Parse(e.to_string()))?; + profile.validate()?; + Ok(profile) + } + + /// Reject profiles that cannot be evaluated, so failures surface at load + /// time rather than mid-ride. + pub fn validate(&self) -> Result<(), ProfileError> { + if self.blocks.is_empty() { + return Err(ProfileError::Empty); + } + for (index, block) in self.blocks.iter().enumerate() { + block + .validate() + .map_err(|reason| ProfileError::InvalidBlock { index, reason })?; + } + Ok(()) + } + + /// The target this profile wants at `position`, or `None` if the profile + /// has finished and is not looping. + /// + /// Implementations must clamp nothing here — safety clamping happens once, + /// at transmission (SAF-3). + pub fn sample(&self, position: Position) -> Option { + let _ = position; + todo!("implemented in crates/core/src/profile.rs — see AGENT task A") + } + + /// Total extent of the profile, if finite. Used for progress display + /// (FR-9.7) and to know when a non-looping profile has ended. + pub fn total_extent(&self) -> ProfileExtent { + todo!("implemented in crates/core/src/profile.rs — see AGENT task A") + } + + /// Sample the whole profile ahead of time for the preview chart (FR-6.7). + /// Returns `(x, value)` pairs where `x` is seconds or metres depending on + /// the profile's dominant extent kind. + pub fn preview(&self, samples: usize) -> Vec<(f64, f32)> { + let _ = samples; + todo!("implemented in crates/core/src/profile.rs — see AGENT task A") + } +} + +/// Total length of a profile, which may be measured in time, distance, both or +/// neither (a profile of only unbounded blocks). +#[derive(Debug, Clone, Copy, PartialEq, Default)] +pub struct ProfileExtent { + pub seconds: Option, + pub metres: Option, +} + +impl Block { + pub fn channel(&self) -> Channel { + match self { + Block::Constant { channel, .. } + | Block::Ramp { channel, .. } + | Block::Wave { channel, .. } => *channel, + Block::Segments { .. } | Block::Terrain { .. } => Channel::Gradient, + } + } + + fn validate(&self) -> Result<(), String> { + match self { + Block::Wave { repeats, period, .. } => { + if *repeats <= 0.0 { + return Err("repeats must be positive".into()); + } + match period { + Extent::Seconds(s) if *s <= 0.0 => Err("period must be positive".into()), + Extent::Metres(m) if *m <= 0.0 => Err("period must be positive".into()), + _ => Ok(()), + } + } + Block::Segments { segments } if segments.is_empty() => { + Err("segments block is empty".into()) + } + Block::Terrain { points } if points.len() < 2 => { + Err("terrain block needs at least two points".into()) + } + _ => Ok(()), + } + } +} diff --git a/crates/core/src/session.rs b/crates/core/src/session.rs new file mode 100644 index 0000000..6a4c063 --- /dev/null +++ b/crates/core/src/session.rs @@ -0,0 +1,117 @@ +//! The ride state machine: ties telemetry, physics and the active profile +//! together and decides what to command the trainer. +//! +//! This is the piece the Tauri layer drives. It takes telemetry in, produces +//! snapshots and control targets out, and knows nothing about BLE or the UI. + +use crate::physics::PhysicsState; +use crate::profile::{Position, Profile}; +use crate::types::{ + ControlMode, ControlTarget, RideSnapshot, RiderConfig, SafetyLimits, Telemetry, +}; + +/// Something the session wants the outside world to do or know about. +#[derive(Debug, Clone, PartialEq)] +pub enum SessionEvent { + /// Send this target to the trainer. Already clamped (SAF-3). + Command(ControlTarget), + /// A new snapshot is available for the UI. + Snapshot(RideSnapshot), + /// A non-looping profile reached its end. + ProfileFinished, + /// The rider crossed into a new lap. + Lap { index: u32 }, +} + +/// Ride lifecycle. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum RideStatus { + Idle, + Running, + Paused, + Finished, +} + +pub struct RideSession { + pub config: RiderConfig, + pub limits: SafetyLimits, + pub mode: ControlMode, + pub status: RideStatus, + physics: PhysicsState, + profile: Option, + /// Manual gradient trim applied on top of the profile's gradient. + gradient_offset_pct: f32, + elapsed_ms: u64, + last_target: Option, +} + +impl RideSession { + pub fn new(config: RiderConfig, limits: SafetyLimits) -> Self { + Self { + config, + limits, + mode: ControlMode::ManualGrade, + status: RideStatus::Idle, + physics: PhysicsState::default(), + profile: None, + gradient_offset_pct: 0.0, + elapsed_ms: 0, + last_target: None, + } + } + + pub fn load_profile(&mut self, profile: Profile) { + self.profile = Some(profile); + self.mode = ControlMode::Profile; + } + + pub fn profile(&self) -> Option<&Profile> { + self.profile.as_ref() + } + + pub fn position(&self) -> Position { + Position { + elapsed_s: self.elapsed_ms as f64 / 1000.0, + distance_m: self.physics.distance_m, + } + } + + pub fn start(&mut self) { + self.status = RideStatus::Running; + } + + pub fn pause(&mut self) { + self.status = RideStatus::Paused; + } + + /// Adjust the manual gradient trim by `delta` percent (FR-4.2). + pub fn nudge_gradient(&mut self, delta_pct: f32) { + self.gradient_offset_pct += delta_pct; + } + + pub fn reset_gradient_offset(&mut self) { + self.gradient_offset_pct = 0.0; + } + + /// Advance the ride by one tick. + /// + /// Feeds telemetry into the physics model, advances the profile, and + /// returns whatever the outside world needs to act on. Must be safe to call + /// when paused (no distance accrues) and when telemetry is missing power + /// (treat as zero rather than panicking). + pub fn tick(&mut self, telemetry: Telemetry, dt_s: f32) -> Vec { + let _ = (telemetry, dt_s); + todo!("implemented in crates/core/src/session.rs — see AGENT task A") + } + + /// Build the snapshot the UI renders. + pub fn snapshot(&self, telemetry: Telemetry) -> RideSnapshot { + let _ = telemetry; + todo!("implemented in crates/core/src/session.rs — see AGENT task A") + } + + /// The target that should be in force right now, before clamping. + fn desired_target(&self) -> Option { + todo!("implemented in crates/core/src/session.rs — see AGENT task A") + } +} diff --git a/crates/core/src/types.rs b/crates/core/src/types.rs new file mode 100644 index 0000000..8b7d8b5 --- /dev/null +++ b/crates/core/src/types.rs @@ -0,0 +1,170 @@ +//! Shared types. This module is the contract between the BLE layer, the ride +//! engine, the recorder and the UI. Change it deliberately. + +use serde::{Deserialize, Serialize}; + +/// One telemetry sample decoded from the trainer's Indoor Bike Data +/// characteristic. Every field is optional because FTMS packets are +/// variable-length — presence is driven by the leading flags bitfield, and a +/// given trainer may never send some of them. +#[derive(Debug, Clone, Copy, Default, PartialEq, Serialize, Deserialize)] +pub struct Telemetry { + /// Milliseconds since the ride started. + pub elapsed_ms: u64, + pub power_w: Option, + pub cadence_rpm: Option, + /// Trainer-reported speed. Diagnostic only — the ride engine computes its + /// own virtual speed from power (FR-7.1, FR-7.5). + pub speed_kph: Option, + pub resistance_level: Option, + pub heart_rate_bpm: Option, + pub total_distance_m: Option, + pub total_energy_kcal: Option, +} + +/// A command to the trainer. Which variant is used depends on the active +/// [`ControlMode`] and on what the trainer actually supports (FR-2.6). +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub enum ControlTarget { + /// Simulated gradient, in percent. Positive is uphill. + Gradient { percent: f32 }, + /// Raw trainer resistance level, in the trainer's own units. + Resistance { level: i16 }, + /// Target power in watts (ERG-style). + Power { watts: u16 }, +} + +/// Hard limits applied at the point of transmission, regardless of where the +/// target came from (SAF-3, SAF-6). A profile with absurd parameters must not +/// be able to command an unsafe target. +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub struct SafetyLimits { + pub min_gradient_pct: f32, + pub max_gradient_pct: f32, + pub min_resistance: i16, + pub max_resistance: i16, + pub min_power_w: u16, + pub max_power_w: u16, +} + +impl Default for SafetyLimits { + fn default() -> Self { + // Gradient range per FR-5.3; power range per the D100 reference + // implementation (§3.2 of REQUIREMENTS.md). + Self { + min_gradient_pct: -10.0, + max_gradient_pct: 15.0, + min_resistance: 0, + max_resistance: 100, + min_power_w: 50, + max_power_w: 600, + } + } +} + +impl SafetyLimits { + /// Clamp a target into the safe range. Every path to the trainer must go + /// through this. + pub fn clamp(&self, target: ControlTarget) -> ControlTarget { + match target { + ControlTarget::Gradient { percent } => ControlTarget::Gradient { + percent: percent.clamp(self.min_gradient_pct, self.max_gradient_pct), + }, + ControlTarget::Resistance { level } => ControlTarget::Resistance { + level: level.clamp(self.min_resistance, self.max_resistance), + }, + ControlTarget::Power { watts } => ControlTarget::Power { + watts: watts.clamp(self.min_power_w, self.max_power_w), + }, + } + } +} + +/// Where the base target comes from (§5.4). Note that in the full design +/// gearing and gradient are simultaneously active; mode selects the *source* of +/// the base gradient, not whether shifting works. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub enum ControlMode { + /// Rider sets gradient directly; no profile running. + ManualGrade, + /// Rider sets raw resistance; physics ignored. + Resistance, + /// Gradient driven by a loaded profile at the current distance/time. + Profile, + /// Fixed target power. + Erg, +} + +/// Rider and bike parameters feeding the physics model (FR-7.4). +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub struct RiderConfig { + pub rider_kg: f32, + pub bike_kg: f32, + /// Coefficient of rolling resistance. + pub crr: f32, + /// Drag coefficient × frontal area, m². + pub cda: f32, + /// Fraction of measured power reaching the wheel. + pub drivetrain_efficiency: f32, + /// Air density, kg/m³. + pub air_density: f32, + pub wheel_circumference_m: f32, +} + +impl Default for RiderConfig { + fn default() -> Self { + Self { + rider_kg: 75.0, + bike_kg: 8.0, + crr: 0.004, + cda: 0.32, + drivetrain_efficiency: 0.97, + air_density: 1.225, + wheel_circumference_m: 2.105, + } + } +} + +impl RiderConfig { + pub fn total_mass_kg(&self) -> f32 { + self.rider_kg + self.bike_kg + } +} + +/// A snapshot of the ride, pushed to the UI each tick. This is what the +/// frontend renders; it should contain everything the ride screen needs and +/// nothing it does not. +#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)] +pub struct RideSnapshot { + pub elapsed_ms: u64, + pub telemetry: Telemetry, + /// Virtual speed computed by the physics engine, km/h. + pub virtual_speed_kph: f32, + /// Virtual distance travelled, metres. + pub virtual_distance_m: f64, + /// Gradient currently commanded, percent. + pub gradient_pct: f32, + /// Cumulative elevation gained, metres. + pub elevation_gain_m: f32, + pub mode: ControlMode, + /// The target most recently sent to the trainer, post-clamp. + pub target: Option, + /// Fractional progress through the loaded profile, 0.0–1.0, if one is + /// loaded and has finite length. + pub profile_progress: Option, +} + +/// Connection state for a single BLE peripheral (FR-1.7). +#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] +pub enum ConnectionState { + Idle, + Scanning, + Connecting, + /// Connected at the BLE level but control not yet acquired. For a trainer, + /// connected ≠ controllable (FR-9.3). + Connected, + /// FTMS control point acquired; commands will be accepted. + Controlling, + Reconnecting, + Lost { reason: String }, +} diff --git a/crates/fit/Cargo.toml b/crates/fit/Cargo.toml new file mode 100644 index 0000000..b4c1d18 --- /dev/null +++ b/crates/fit/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "bikecontrol-fit" +version.workspace = true +edition.workspace = true +license.workspace = true + +[dependencies] +bikecontrol-core = { workspace = true } +thiserror = { workspace = true } +chrono = { workspace = true } diff --git a/crates/fit/src/lib.rs b/crates/fit/src/lib.rs new file mode 100644 index 0000000..c62a281 --- /dev/null +++ b/crates/fit/src/lib.rs @@ -0,0 +1 @@ +//! FIT activity file encoder. See REQUIREMENTS.md §5.8. diff --git a/crates/probe/Cargo.toml b/crates/probe/Cargo.toml new file mode 100644 index 0000000..764e5a2 --- /dev/null +++ b/crates/probe/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "bikecontrol-probe" +version.workspace = true +edition.workspace = true +license.workspace = true + +[[bin]] +name = "probe" +path = "src/main.rs" + +[dependencies] +bikecontrol-core = { workspace = true } +bikecontrol-ble = { workspace = true } +btleplug = { workspace = true } +tokio = { workspace = true, features = ["full"] } +futures = { workspace = true } +uuid = { workspace = true } +anyhow = { workspace = true } +tracing = { workspace = true } +tracing-subscriber = { workspace = true } diff --git a/crates/probe/src/main.rs b/crates/probe/src/main.rs new file mode 100644 index 0000000..ae4a540 --- /dev/null +++ b/crates/probe/src/main.rs @@ -0,0 +1 @@ +fn main() { println!("probe: not yet implemented"); } diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml new file mode 100644 index 0000000..07599d7 --- /dev/null +++ b/src-tauri/Cargo.toml @@ -0,0 +1,40 @@ +[package] +name = "bikecontrol-app" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +description = "BikeControl desktop shell: Tauri commands and the event bridge to the UI" + +[lib] +# Tauri v2 convention: the app lives in a lib so the same code can be reused by +# the Android/iOS entry points later (G-4). +name = "bikecontrol_app_lib" +crate-type = ["staticlib", "cdylib", "rlib"] + +[build-dependencies] +tauri-build = { version = "2", features = [] } + +[dependencies] +bikecontrol-core = { workspace = true } + +tauri = { version = "2", features = [] } +tauri-plugin-dialog = "2" + +serde = { workspace = true } +serde_json = { workspace = true } +serde_yaml_ng = { workspace = true } +tokio = { workspace = true } +anyhow = { workspace = true } +thiserror = { workspace = true } +tracing = { workspace = true } +tracing-subscriber = { workspace = true } + +[features] +default = ["mock-ride"] +# Drive the UI from the synthetic ride simulator in `src/mock.rs`. This is what +# ships today, while `crates/core` and `crates/ble` are still being written. +mock-ride = [] +# Drive the UI from `bikecontrol_core::RideSession` fed by real FTMS telemetry. +# Swap `default` to this once core's `session`/`physics` are implemented. +real-session = [] diff --git a/src-tauri/build.rs b/src-tauri/build.rs new file mode 100644 index 0000000..261851f --- /dev/null +++ b/src-tauri/build.rs @@ -0,0 +1,3 @@ +fn main() { + tauri_build::build(); +} diff --git a/src-tauri/capabilities/default.json b/src-tauri/capabilities/default.json new file mode 100644 index 0000000..c7cd5d8 --- /dev/null +++ b/src-tauri/capabilities/default.json @@ -0,0 +1,14 @@ +{ + "$schema": "../gen/schemas/desktop-schema.json", + "identifier": "default", + "description": "Permissions for the BikeControl main window.", + "windows": ["main"], + "permissions": [ + "core:default", + "core:event:default", + "core:window:default", + "core:webview:default", + "core:app:default", + "dialog:default" + ] +} diff --git a/src-tauri/tauri.conf.json b/src-tauri/tauri.conf.json new file mode 100644 index 0000000..123fcf0 --- /dev/null +++ b/src-tauri/tauri.conf.json @@ -0,0 +1,48 @@ +{ + "$schema": "https://schema.tauri.app/config/2", + "productName": "BikeControl", + "version": "0.1.0", + "identifier": "paris.tourolle.bikecontrol", + "build": { + "frontendDist": "../ui/dist", + "devUrl": "http://localhost:1420", + "beforeDevCommand": { + "cwd": "../ui", + "script": "npm run dev" + }, + "beforeBuildCommand": { + "cwd": "../ui", + "script": "npm run build" + } + }, + "app": { + "windows": [ + { + "title": "BikeControl", + "width": 1440, + "height": 900, + "minWidth": 960, + "minHeight": 640, + "resizable": true, + "fullscreen": false, + "backgroundColor": "#07090d" + } + ], + "security": { + "csp": "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src ipc: http://ipc.localhost" + } + }, + "bundle": { + "active": true, + "targets": "all", + "icon": [ + "icons/32x32.png", + "icons/128x128.png", + "icons/128x128@2x.png", + "icons/icon.png" + ], + "category": "Utility", + "shortDescription": "Indoor cycling trainer control", + "longDescription": "Control a smart trainer over BLE, ride gradient profiles and synthetic waveforms, and record the result." + } +}