+ +Using the Command Line Utilities + + +
+In addition to the GUI, Golden Cheetah comes with
+several command line utilities:
+ptdl, which downloads ride data from a PowerTap Pro version 2.21
+cycling computer, ptunpk, which unpacks the raw bytes downloaded
+by ptdl and outputs more human-friendly ride information, and
+cpint, which computes your critical power (see below). We've
+also written several Perl scripts to help you graph and summarize the data.
+
+
+NOTE: We no longer support the use of the command-line tools. Please use the +graphical version of GoldenCheetah instead. This documentation is here for +the benefit of the brave alone. + +
+ +Extracting the Data + +
+First, make sure you have the FTDI drivers installed, as described in the User's Guide. You can then run ptdl
+without arguments:
+
+
+$ ./ptdl +Reading from /dev/tty.usbserial-3B1. +Reading version information...done. +Reading ride time...done. +Writing to 2006_05_15_11_34_03.raw. +Reading ride data..............done. +$ head -5 2006_05_15_11_34_03.raw +57 56 55 64 02 15 +60 06 05 0f 6b 22 +40 08 30 00 00 00 +86 0e 74 99 00 55 +81 06 77 a8 40 55 ++ +
+If everything goes well, ptdl will automatically detect the
+device (/dev/tty.usbserial-3B1 in the example above), read the
+ride data from it, and write to a file named by the date and time at which the
+ride started (2006_05_15_11_34_03.raw in the example; the format
+is YYYY_MM_DD_hh_mm_ss.raw).
+
+
+ +Unpacking the Data + +
As shown by the head command above, the data in this
+.raw file is just the raw bytes that represent your ride. To
+unpack those bytes and display them in a more human-friendly format, use
+ptunpk:
+
+
+$ ./ptunpk 2006_05_15_11_34_03.raw +$ head -5 2006_05_15_11_34_03.dat +# Time Torq MPH Watts Miles Cad HR Int +# 2006/5/15 11:34:03 1147707243 +# wheel size=2096 mm, interval=0, rec int=1 +0.021 13.1 2.450 43 0.00781 0 85 0 +0.042 13.4 5.374 97 0.00912 64 85 0 ++ +
ptunpk takes a .raw file for input and writes a
+.dat file as output. Lines that start with an ampersand ("#") in
+this file are comments; the other lines represent measured samples. As shown
+by the first comment in the file, the columns are: time in minutes, torque in
+Newton-meters, speed in miles per hour, power in watts, distance in miles,
+cadence, heart rate, and interval number.
+
++ +Summarizing the Data + +
+We hope to have a graphical interface to these programs soon, but until then,
+the only summarization tools we have are command-line programs. The script
+intervals.pl summarizes the intervals performed in a workout:
+
+
+
+$ ./intervals.pl 2006_05_03_16_24_04.dat
+ Power Heart Rate Cadence Speed
+Int Dur Dist Avg Max Avg Max Avg Max Avg Max
+ 0 77:10 19.3 213 693 134 167 82 141 16.0 27.8
+ 1 4:03 0.9 433 728 175 203 84 122 13.0 18.8
+ 2 7:23 1.0 86 502 135 179 71 141 16.0 28.2
+ 3 4:27 0.9 390 628 170 181 70 100 12.0 17.6
+ 4 8:04 0.9 60 203 130 178 50 120 18.0 30.1
+ 5 4:30 0.9 384 682 170 179 79 113 11.0 18.6
+ 6 8:51 1.1 53 245 125 176 70 141 8.0 26.6
+ 7 2:48 0.4 400 614 164 178 62 91 8.0 13.6
+ 8 7:01 1.1 46 268 128 170 71 141 12.0 28.8
+ 9 4:30 0.9 379 560 168 180 81 170 11.0 18.3
+10 28:46 6.5 120 409 128 179 79 141 15.0 31.0
+
+
+
+
+In the example above, a rider performed five hill intervals, four of which +climbed a medium size hill that took about 4-5 minutes to climb (intervals +1, 3, 5, and 9), and one on a shorter hill that took just under 3 minutes to +climb (interval 7). + +
+ +Graphing the Data + +
+For graphing the data in the ride, we use smooth.pl and the
+gnuplot program. You can use sample.gp
+to graph the power, heart rate, cadence, and speed for the hill workout above:
+
+
+$ gnuplot sample.gp ++ +
+
++ +Finding Your "Critical Power" + +
+Joe Friel calls the maximum average power a rider can sustain over an interval
+the rider's "critical power" for that duration. The cpint
+program automatically computes your critical power over all interval lengths
+using the data from all your past rides. This program looks at all the
+.raw files in a directory, calculating your maximum power over
+every subinterval length and storing them in a corresponding .cpi
+file. It then combines the data in all of the .cpi files to find
+your critical power over all subintervals of all your rides.
+
+
+$ ls *.raw +2006_04_28_10_48_33.raw 2006_05_10_17_08_30.raw 2006_05_18_16_32_53.raw +2006_05_03_16_24_04.raw 2006_05_13_10_29_12.raw 2006_05_21_12_25_07.raw +2006_05_05_10_52_05.raw 2006_05_15_11_34_03.raw 2006_05_22_18_28_47.raw +... +2006_05_09_09_54_29.raw 2006_05_17_16_44_35.raw +$ ./cpint +Compiling data for ride on Fri Apr 28 10:48:33 2006...done. +Compiling data for ride on Sat Apr 29 10:07:48 2006...done. +Compiling data for ride on Sun Apr 30 14:00:17 2006...done. + ... +Compiling data for ride on Mon May 22 18:28:47 2006...done. + 0.021 1264 + 0.042 1221 + 0.063 1216 + ... + 5.019 391 + ... +171.885 163 ++ +
+Over this set of rides, the rider's maximum power is 1264 watts, achieved over +an interval of 0.021 minutes (1.26 seconds). Over all five-minute +subintervals, he has achieved a maximum average power of 391 watts. The +longest ride in this set was 171.885 minutes long, and he averaged 163 watts +over it. + +
+We can graph the output of cpint using gnuplot with
+cpint.gp:
+
+
+$ ./cpint > cpint.out +$ gnuplot cpint.gp ++ +
+
+
+The first time you run cpint it will take a while, as it has to
+analyze all your past rides. On subsequent runs, however, it will only
+analyze new files.
+
+
Training and Racing with a Power Meter (see the FAQ) contains a table of critical powers of Cat 5 cyclists
+up through international pros at interval lengths of 5 seconds, 1 minute, 5
+minutes, and 60 minutes. Using this table and the cpint program,
+you can determine whether you're stronger than others in your racing category
+at each interval length and adapt your training program accordingly.
+
+
+ +Converting Old Data + + +
+If you've used the PowerTuned software that comes with the PowerTap you may
+have lots of old ride data in that program that you'd like to include in your
+critical power graph. You can convert the .xml files that
+PowerTuned produces to .raw files using the ptpk
+program:
+
+
+
+$ ./ptpk 2006_04_27_00_23_28.xml +$ head -5 2006_04_27_00_23_28.raw +57 56 55 64 02 15 +60 06 04 7b 80 17 +40 08 30 00 00 00 +84 04 00 24 00 ff +83 03 00 d7 00 ff ++ +
+ptpk assumes the input .xml file was generated with
+a wheel size of 2,096 mm and a recording interval of 1. If this is not the
+case, you should specify the correct values with the -w and
+-r options.
+
+
+Note that the PowerTuned software computes the output speed in miles per hour
+by multiplying the measured speed in kilometers per hour by 0.62, and the
+miles per hour values in a .xml file are thus only accurate to
+two significant figures, even though they're printed out to three decimal
+places. Because of this limitation, the sequence ptpk,
+ptunpk is not quite the identity function; in particular, the
+wattage values from ptpk may only be accurate to two significant
+digits.
+
diff --git a/doc/critical-power.png b/doc/critical-power.png
new file mode 100644
index 000000000..48a387f92
Binary files /dev/null and b/doc/critical-power.png differ
diff --git a/doc/main-window.png b/doc/main-window.png
new file mode 100644
index 000000000..5f1fae5f0
Binary files /dev/null and b/doc/main-window.png differ
diff --git a/doc/power.zones b/doc/power.zones
new file mode 100644
index 000000000..1f2add41f
--- /dev/null
+++ b/doc/power.zones
@@ -0,0 +1,27 @@
+From BEGIN until 2006/07/17, CP=297:
+ 1, Active Recovery, 122, 167
+ 2, Endurance, 167, 228
+ 3, Tempo, 228, 274
+ 4, Lactate Threshold, 274, 319
+ 5, VO2 Max, 319, 365
+ 6, Anaerobic Capacity, 365, 678
+ 7, Sprinting, 678, MAX
+
+From 2006/07/17 until 2007/02/05, CP=329:
+ 1, Active Recovery, 135, 185
+ 2, Endurance, 185, 253
+ 3, Tempo, 253, 303
+ 4, Lactate Threshold, 303, 354
+ 5, VO2 Max, 354, 404
+ 6, Anaerobic Capacity, 404, 752
+ 7, Sprinting, 752, MAX
+
+From 2007/02/05 until END, CP=347:
+ 1, Active Recovery, 139, 191
+ 2, Endurance, 191, 260
+ 3, Tempo, 260, 312
+ 4, Lactate Threshold, 312, 364
+ 5, VO2 Max, 364, 416
+ 6, Anaerobic Capacity, 416, 774
+ 7, Sprinting, 774, MAX
+
diff --git a/doc/users-guide.content b/doc/users-guide.content
index 2a106ced5..6a406b9ac 100644
--- a/doc/users-guide.content
+++ b/doc/users-guide.content
@@ -1,241 +1,226 @@
-Using the GUI
+Step 1: Installing the FTDI drivers
-Using the graphical version of Golden Cheetah should be pretty -self-explanatory. Download the disk image from the download page, drag the Golden Cheetah application -into your Applications folder, open your Applications folder, and then double -click on Golden Cheetah. +Before you can download rides from your PowerTap, you may need to install the +FTDI Virtual COM Port (VCP) drivers. If you're running Linux kernel 2.6.9 or +greater, they're already included. If you're running Mac OS X or an earlier +version of Linux, download them from +FTDI's website and follow +FTDI's +instructions to install them. + +
+If you're running Linux, you may also need to uninstall the brtty
+(Braille TTY) application, as it interferes with FTDI's driver. The command
+
+
+sudo apt-get remove brtty ++ +should do the trick on Debian/Ubuntu. + +
+The latest version (7.1.1) of Saris's PowerAgent software uses an incompatible +version of FTDI's driver from the one GoldenCheetah uses, and PowerAgent +removes the driver that GoldenCheetah needs when you install PowerAgent. If +you want to run both GoldenCheetah and PowerAgent, you need to use PowerAgent +version 7.0.1 or earlier. We're working to correct this problem, but we're +not there yet.
-Using the Command Line Utilities +Step 2: Installing GoldenCheetah
-In addition to the GUI, Golden Cheetah comes with
-several command line utilities:
-ptdl, which downloads ride data from a PowerTap Pro version 2.21
-cycling computer, ptunpk, which unpacks the raw bytes downloaded
-by ptdl and outputs more human-friendly ride information, and
-cpint, which computes your critical power (see below). All three
-are written in simple C code but have only been tested on Mac OS X so far.
-We've also written several Perl scripts to help you graph and summarize the
-data.
+To install GoldenCheetah, go to the download page
+and download the version for your operating system and processor.
+
+
+On Mac OS X, when the download finishes, Mac OS X should automatically open
+the .dmg file for you. If not, double-click to open it. Drag
+the GoldenCheetah icon into your Applications folder, and you're done.
+
+
+The Linux version of GoldenCheetah is distributed as a tarball. Download this
+file and save it to /tmp, then from a terminal:
+
+
+cd /tmp +tar xzvf GoldenCheetah_DATE_Linux_x86.tgz +cd GoldenCheetah_DATE_Linux_x86 +sudo cp GoldenCheetah /usr/local/bin +cd .. +rm -rf GoldenCheetah_DATE_Linux_x86.tgz ++ +Be sure to replace "DATE" with the date of the revision you downloaded, such +as "2007-09-23".
-Extracting the Data +Step 3: Running GoldenCheetah -
-To use ptdl, you'll first need to install
-the drivers for the
-FTDI chip the PowerTap Pro USB Downloader uses. Once these are installed, you
-should be able to just run ptdl without arguments:
-
-
-$ ./ptdl -Reading from /dev/tty.usbserial-3B1. -Reading version information...done. -Reading ride time...done. -Writing to 2006_05_15_11_34_03.raw. -Reading ride data..............done. -$ head -5 2006_05_15_11_34_03.raw -57 56 55 64 02 15 -60 06 05 0f 6b 22 -40 08 30 00 00 00 -86 0e 74 99 00 55 -81 06 77 a8 40 55 -
-If everything goes well, ptdl will automatically detect the
-device (/dev/tty.usbserial-3B1 in the example above), read the
-ride data from it, and write to a file named by the date and time at which the
-ride started (2006_05_15_11_34_03.raw in the example; the format
-is YYYY_MM_DD_hh_mm_ss.raw).
+To run GoldenCheetah on Mac OS X, double-click on the GoldenCheetah icon in
+your Applications folder. On Linux, just type "GoldenCheetah" at the prompt.
+
+
+The first time you run GoldenCheetah, you'll get an empty "Choose a Cyclist" +dialog box: + +
+
+Click on "New...", enter your name, and then select your name and click +"Open". After that, the main GoldenCheetah window will open: + +
+
+Your main window won't yet have any rides in it, of course. To fix that, you
+need either to download a ride from your PowerTap or import one from another
+program. GoldenCheetah can import .srm files recorded on SRM
+power meters and .csv files created by other programs. To
+download a file from your PowerTap, select "Ride->Download from device..."
+from the menu. To import one, select either "Ride->Import from SRM..." or
+"Ride->Import from CSV...".
+
+
+Once you've downloaded or imported a ride, you can see some simple statistics +about it on the "Ride Summary" page: your total riding time and average power, +for example. If you click on the "Ride Plot" tab at the top of the screen, +you can see a graph of your speed, power, cadence, and heart rate during the +ride. The "Power Histogram" shows how much time you spent at each power +during the ride, and the "Notes" tab allows you to record notes about the +ride. The "Weekly Summary" shows your total time and work for the week. + +
+The "Critical Power Plot" is one of the most useful features of GoldenCheetah. +It shows the highest average power you attained for every interval length +during the ride. Some people call this the "Mean Maximal Power" graph. The +green line shows values for this ride; the red line shows the combination of +all your rides. (If you only have one ride so far, the two lines will +overlap.) Clicking on the graph with your mouse brings up a blue line, and +the values under this line are shown at the bottom of the screen. + +
+It helps to think about an example: + +
+
+In this example, the blue line is right around the 14-second mark on the +x-axis. So the values shown under "Today" and "All Rides", at the bottom, are +the hardest the cyclist went for any 14-second period during the ride itself +and during all rides he's ever recorded in GoldenCheetah. Since the two +values are the same, he set a new personal record during this ride. + +
+The Critical Power Plot is most useful before you're going to go do intervals +or a time trial. Say you want to do six 2-minute intervals with three minutes +rest in between. Click on the Critical Power Plot, drag the blue line to the +2-minute mark, and read the value shown in "All Rides". That's the hardest +you've ever gone for two minutes. Now go out and try to beat it!
-Unpacking the Data +Step 4: Setting Up Your Power Zones -
As shown by the head command above, the data in this
-.raw file is just the raw bytes that represent your ride. To
-unpack those bytes and display them in a more human-friendly format, use
-ptunpk:
+
+
+If you look back at the screenshot above, you may notice that there are +several things shown in the "Ride Summary" tab that aren't on your version. +The picture above shows a non-zero "Bike Score", and there's a list of how +much time the cyclist spent in each "Power Zone" during the ride as well. + +
+BikeScore(TM) is a measure of the physiological stress you underwent during a +ride. It was developed by Dr. Philip Skiba, and you can read more about it in +an article he wrote. + +
+For GoldenCheetah to compute your BikeScore and the time spent in each power +zone, you first need to tell it what your power zones and critical power +are. You can define your power zones however you like, maybe using the ones +defined by Joe Friel, for example. Your critical power should be the +maximum power you can sustain over an hour. Some people call this your +"lactate threshold" or "functional threshold power". Our friend Bill says a +rose by any other name would smell as sweet. + +
+We'll have a dialog box that will let you set up your power zones and +critical power in a future version of GoldenCheetah, but for now you'll need +to use a text editor. On Linux, that probably means nano, vi, or emacs. +On Mac, it means TextEdit, which is in your Applications folder. Start by +downloading this sample file and saving it in
-$ ./ptunpk 2006_05_15_11_34_03.raw -$ head -5 2006_05_15_11_34_03.dat -# Time Torq MPH Watts Miles Cad HR Int -# 2006/5/15 11:34:03 1147707243 -# wheel size=2096 mm, interval=0, rec int=1 -0.021 13.1 2.450 43 0.00781 0 85 0 -0.042 13.4 5.374 97 0.00912 64 85 0 +~/Library/GoldenCheetah/Your Name/power.zones-
ptunpk takes a .raw file for input and writes a
-.dat file as output. Lines that start with an ampersand ("#") in
-this file are comments; the other lines represent measured samples. As shown
-by the first comment in the file, the columns are: time in minutes, torque in
-Newton-meters, speed in miles per hour, power in watts, distance in miles,
-cadence, heart rate, and interval number.
+
+where "~" is your home directory (e.g., /Users/srhea on Mac or
+/home/srhea on Linux) and "Your Name" is the name you chose when
+you first opened GoldenCheetah. Open the power.zones file in a text editor
+and you'll see this:
+
+
++ ++From BEGIN until 2006/07/17, CP=297: + 1, Active Recovery, 122, 167 + 2, Endurance, 167, 228 + 3, Tempo, 228, 274 + 4, Lactate Threshold, 274, 319 + 5, VO2 Max, 319, 365 + 6, Anaerobic Capacity, 365, 678 + 7, Sprinting, 678, MAX + +From 2006/07/17 until 2007/02/05, CP=329: + 1, Active Recovery, 135, 185 + 2, Endurance, 185, 253 + 3, Tempo, 253, 303 + 4, Lactate Threshold, 303, 354 + 5, VO2 Max, 354, 404 + 6, Anaerobic Capacity, 404, 752 + 7, Sprinting, 752, MAX + +From 2007/02/05 until END, CP=347: + 1, Active Recovery, 139, 191 + 2, Endurance, 191, 260 + 3, Tempo, 260, 312 + 4, Lactate Threshold, 312, 364 + 5, VO2 Max, 364, 416 + 6, Anaerobic Capacity, 416, 774 + 7, Sprinting, 774, MAX ++
+The format of the file is simple. You define a range of time, starting with a +date or "BEGIN" to indicate the oldest possible time and ending with a date or +"END" to indicate the latest possible time. Then you put your critical power +(CP) for that date range. Then you list your zones, where each zone has a +number, a name, a minimum power value, and a maximum power value. You can +have as many time ranges and zones as you like. Most people enter a new time +range every time their critical power goes up--right after a fitness test, for +example.
-Summarizing the Data - -
-We hope to have a graphical interface to these programs soon, but until then,
-the only summarization tools we have are command-line programs. The script
-intervals.pl summarizes the intervals performed in a workout:
-
-
-
-$ ./intervals.pl 2006_05_03_16_24_04.dat
- Power Heart Rate Cadence Speed
-Int Dur Dist Avg Max Avg Max Avg Max Avg Max
- 0 77:10 19.3 213 693 134 167 82 141 16.0 27.8
- 1 4:03 0.9 433 728 175 203 84 122 13.0 18.8
- 2 7:23 1.0 86 502 135 179 71 141 16.0 28.2
- 3 4:27 0.9 390 628 170 181 70 100 12.0 17.6
- 4 8:04 0.9 60 203 130 178 50 120 18.0 30.1
- 5 4:30 0.9 384 682 170 179 79 113 11.0 18.6
- 6 8:51 1.1 53 245 125 176 70 141 8.0 26.6
- 7 2:48 0.4 400 614 164 178 62 91 8.0 13.6
- 8 7:01 1.1 46 268 128 170 71 141 12.0 28.8
- 9 4:30 0.9 379 560 168 180 81 170 11.0 18.3
-10 28:46 6.5 120 409 128 179 79 141 15.0 31.0
-
-
-
-
-In the example above, a rider performed five hill intervals, four of which -climbed a medium size hill that took about 4-5 minutes to climb (intervals -1, 3, 5, and 9), and one on a shorter hill that took just under 3 minutes to -climb (interval 7). - -
- -Graphing the Data - -
-For graphing the data in the ride, we use smooth.pl and the
-gnuplot program. You can use sample.gp
-to graph the power, heart rate, cadence, and speed for the hill workout above:
-
-
-$ gnuplot sample.gp -- -
-
-- -Finding Your "Critical Power" - -
-Joe Friel calls the maximum average power a rider can sustain over an interval
-the rider's "critical power" for that duration. The cpint
-program automatically computes your critical power over all interval lengths
-using the data from all your past rides. This program looks at all the
-.raw files in a directory, calculating your maximum power over
-every subinterval length and storing them in a corresponding .cpi
-file. It then combines the data in all of the .cpi files to find
-your critical power over all subintervals of all your rides.
-
-
-$ ls *.raw -2006_04_28_10_48_33.raw 2006_05_10_17_08_30.raw 2006_05_18_16_32_53.raw -2006_05_03_16_24_04.raw 2006_05_13_10_29_12.raw 2006_05_21_12_25_07.raw -2006_05_05_10_52_05.raw 2006_05_15_11_34_03.raw 2006_05_22_18_28_47.raw -... -2006_05_09_09_54_29.raw 2006_05_17_16_44_35.raw -$ ./cpint -Compiling data for ride on Fri Apr 28 10:48:33 2006...done. -Compiling data for ride on Sat Apr 29 10:07:48 2006...done. -Compiling data for ride on Sun Apr 30 14:00:17 2006...done. - ... -Compiling data for ride on Mon May 22 18:28:47 2006...done. - 0.021 1264 - 0.042 1221 - 0.063 1216 - ... - 5.019 391 - ... -171.885 163 -- -
-Over this set of rides, the rider's maximum power is 1264 watts, achieved over -an interval of 0.021 minutes (1.26 seconds). Over all five-minute -subintervals, he has achieved a maximum average power of 391 watts. The -longest ride in this set was 171.885 minutes long, and he averaged 163 watts -over it. - -
-We can graph the output of cpint using gnuplot with
-cpint.gp:
-
-
-$ ./cpint > cpint.out -$ gnuplot cpint.gp -- -
-
-
-The first time you run cpint it will take a while, as it has to
-analyze all your past rides. On subsequent runs, however, it will only
-analyze new files.
-
-
Training and Racing with a Power Meter (see the FAQ) contains a table of critical powers of Cat 5 cyclists
-up through international pros at interval lengths of 5 seconds, 1 minute, 5
-minutes, and 60 minutes. Using this table and the cpint program,
-you can determine whether you're stronger than others in your racing category
-at each interval length and adapt your training program accordingly.
-
-
- -Converting Old Data +Legacy Command-Line Tools
-If you've used the PowerTuned software that comes with the PowerTap you may
-have lots of old ride data in that program that you'd like to include in your
-critical power graph. You can convert the .xml files that
-PowerTuned produces to .raw files using the ptpk
-program:
-
-
-
-$ ./ptpk 2006_04_27_00_23_28.xml -$ head -5 2006_04_27_00_23_28.raw -57 56 55 64 02 15 -60 06 04 7b 80 17 -40 08 30 00 00 00 -84 04 00 24 00 ff -83 03 00 d7 00 ff -- -
-ptpk assumes the input .xml file was generated with
-a wheel size of 2,096 mm and a recording interval of 1. If this is not the
-case, you should specify the correct values with the -w and
--r options.
-
-
-Note that the PowerTuned software computes the output speed in miles per hour
-by multiplying the measured speed in kilometers per hour by 0.62, and the
-miles per hour values in a .xml file are thus only accurate to
-two significant figures, even though they're printed out to three decimal
-places. Because of this limitation, the sequence ptpk,
-ptunpk is not quite the identity function; in particular, the
-wattage values from ptpk may only be accurate to two significant
-digits.
+You can still build the older, command-line tools from the source code, but we
+no longer include them in releases. You can find
+documentation for them here.