ODKI VBT
odki.tech — project site, pre-orders, and the companion app.
ODKI VBT is an open-core Velocity-Based Training (VBT) sensor — a small wireless device that clips onto a barbell (or is otherwise attached to the load being lifted) and measures bar velocity, displacement, and rep count in real time, streaming the results to a companion app over Bluetooth Low Energy. Build your own from the files here for personal or research use, or buy a ready-made, ODKI-branded unit at odki.tech — see the license note below for exactly what "open core" means here.
Velocity-based training uses how fast a lift moves — not just the weight on the bar — to gauge effort, fatigue, and training intensity in real time, which is the whole reason this project exists: an accessible, understandable, hackable device to do that.
Licenses, in short (the map of which file is under which license is in LICENSE):
- Tracking engine (
Firmware/VBT_Quaternions/MotionTracker.cpp/.h, the two offline tools that compile it in, and Firmware/DOCUMENTATION.md) — source-available, not open source: PolyForm Noncommercial 1.0.0 with additional permissions. Free for personal, hobby and study use, for research for the benefit of public knowledge, and for universities, public research organisations, charities and the other organisations the license lists. Research by or for a company is commercial use. Commercial use — including selling devices or kits that run the engine — needs a commercial licence from ODKI ([email protected]). Units from ODKI may be used for any purpose, including in a gym or for professional coaching.
- Rest of the firmware and all the tools (
TrackingTypes.h, FusionOrientation, BLE, power, battery, LED, the .ino, the Python and C++ tools) — open source under the Apache License 2.0 (see also NOTICE).
- Hardware design (
Hardware/) — CC BY-NC-SA 4.0: build, modify and share for noncommercial purposes; selling the files, prints made from them, or kits or devices that include such prints needs ODKI's permission.
- BLE protocol specification (
Firmware/BLE_PROTOCOL.md) — CC0 1.0, so anyone can build a client or a compatible device.
- Third-party code keeps its own license: the vendored x-io Fusion library is MIT; the libraries linked into the firmware binaries are listed in THIRD_PARTY_NOTICES.md.
- Companion app — proprietary, see Apps/README.md. The ODKI name is not licensed by any of the above (TRADEMARKS.md).
Firmware and tools up to and including v3.11.31 were released under the GNU GPL v3.0 with the Commons Clause; copies received under those terms stay under them. See CONTRIBUTING.md for how contributing to the official repository works.
Status
How it works, briefly
The sensor fuses its onboard accelerometer and gyroscope into a stable orientation estimate, uses that to isolate real acceleration from gravity, integrates it into velocity along the vertical axis, and detects individual reps from that velocity signal — continuously correcting for drift using brief natural pauses in motion, without requiring the athlete to explicitly mark the start/end of each rep. Every rep's peak/mean velocity, acceleration, displacement, and a data-quality score are reported live. The full algorithm is documented in detail in Firmware/DOCUMENTATION.md.
Repository layout
- Hardware/ — bill of materials, CAD/mechanical design files, and assembly instructions for building a unit.
- Firmware/ — the Arduino C++ firmware source (
VBT_Quaternions/), DOCUMENTATION.md (a chapter-by-chapter reference covering what every source file does and the rep-detection algorithm in detail), BLE_PROTOCOL.md (the byte-exact Bluetooth protocol spec — everything a third-party app needs to talk to the sensor), and the tools in tools/: vbt_log_viewer.py, for replaying and visualizing a raw debug-log capture from the device (with an interactive GUI to pick which columns to plot); vbt_live_monitor.py, a desktop GUI that shows that same data live over a USB-serial connection and can drive calibration/start/stop directly, no phone app needed; host_replay/ and full_replay/, which run a captured log through the real tracking engine on a PC to evaluate algorithm changes offline (their C++ programs, replay.cpp and harness.cpp, compile the engine in and are under its license; the Python scripts are Apache-2.0); plus the regression, calibration and validation tools.
- Apps/ — download links and usage instructions for the companion app (Android, iOS, Windows).
- LICENSE — which file is under which license: LICENSE-ENGINE (tracking engine, PolyForm Noncommercial 1.0.0 with additional permissions), LICENSE-APACHE + NOTICE (rest of the firmware and the tools, Apache-2.0), LICENSE-HARDWARE (CC BY-NC-SA 4.0), THIRD_PARTY_NOTICES.md (libraries in the firmware binaries), (the ODKI name). The BLE protocol specification () is released under CC0 (public domain), so third-party apps can be built against it without restriction.
以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗
