Download the main script from github and save it as

Double-click it and choose "Execute in terminal".

The terminal will show a scary (but unimportant) message. More importantly, the OSD will appear and show "Scanning".

Start the Chrome browser, navigate to, and pick whatever kind of video is your catnip.

Start pedaling after a few seconds (give it a good 15 seconds), the sensor will be detected and your cadence in RPMs will be displayed.

In the default script, if you are in the red zone (below 60RPM), the video will pause after 2 seconds. If you're in the yellow zone (60 to 72RPM) or green zone (above 72RPM), the video will continue playing. You can customize these values by editing the script and restarting it.

The script is able to detect when the active window is a Chromium browser window but not whether you're on a YouTube video. If your computer is randomly typing "p" and "k" into websites, make sure you've stopped the script! Just return to the terminal window where you started the script and use the close button in the corner (×) or press Ctrl-C to interrupt it.


The script is set up so that you can easily customize the following values:


Ready to do something more in depth? Here are just a few of the other ideas the author and his friends had while writing this guide:

  • The On Screen Display of cadence is fairly crude. How would you improve it?
  • Can the program manage a whole workout, with changing target cadences and timed breaks (where the video doesn't stop?)
  • Make it to work with additional video services or local video players such as vlc
  • Interface with other BLE sensors or devices—Adafruit Blinka BLE can work with a whole range of Bluetooth Low Energy modules and sensors such as heart rate monitors, temperature sensors, BLE light bulbs, or developer boards like the CircuitPlayground Bluefruit or CLUE

This guide was first published on Dec 02, 2020. It was last updated on Mar 08, 2024.

This page (Using and Customizing the script) was last updated on Mar 08, 2024.

Text editor powered by tinymce.