Documentation

Introduction

tcx2hrm is a Java based command line tool to convert Garmin TCX training files into Polar HRM data files. It offers a variety of features to influence the conversion, however in most cases the default settings should be sufficient for most applications.

Note, that the information given below always applies to the latest version of tcx2hrm. Please refer to the version history for information on previous functionality.

Installation

Download the latest version of the application and extract it to your favourite directory. The distributable comes as GZIP compressed file, any unzip tool should be sufficient. Ensure that Java at least version 1.6 is installed on your machine, that’s it!

The application is compiled with a 32 bit JDK, however I recommend to run a 64 bit state of the art JRE which is fully backwards compatible.

Running the application

Running the application is quite simple if you do not need to use extended parameters:

java -jar tcx2hrm.jar inputname

This will start the tool with the TCX file inputname with default settings. The tool will analyze the input file, extract the first track of the first lap and convert it to an HRM file in the local directory. The HRM filename will follow Polar’s convention: YYYYMMDD.hrm, where YYYY is the year, MM the month and DD the day of the month, filled up with leading zero’s if required. The HRM file content will follow the specifications for version v1.07 with a virtual S725X monitor and five second interval. This ensures, that most of the TCX training data can be transferred to the HRM format. If you want to understand in detail, what is going on during conversion, please refer to this page.

Advanced parameters

To make a long story short, the tool supports the following list of command line options:

java -jar tcx2hrm.jar tcxfilename [hrmfilename] [-a N] [-c N] [-g] [-G XYZ] [-i Interval] [-l N] [-m Monitor] [-o N] [-s] [-t N] [-u] [-v Version]

inputname

Fully qualified name of the TCX file. This is a mandatory parameter in normal operation mode.

outputname

Fully qualified name of the HRM file to create. If not used, the Polar standard convention will be used (see above).

-a N

Selects the sport session to use in a so-called „MultiSportSession“ record. Defaults to 1. Please refer to your Garmin device manual for more information on multi sport sessions. Use the -s switch if you are not sure, whether a multi sport session was recorded.

-c N

Selects the method to be applied for converting the input data. For N use the following values:

• 1 … replicator, simply replicating data rows
• 2 … linear mean algorithm, calculates mean values between predecessor and successor; default

This is mainly related to the difference on data recording between TCX (time variance) and HRM (fixed time interval). During conversion, tcx2hrm calculates one data record per second.

-g

If this option is provided, the GPS data will be stored in a separate GPX compatible XML file. A GPX file is used by various applications to manage recorded GPS information. For example, Polar Pro Trainer uses GPX files together with Google Earth in case the Polar device used a G3 sensor to record GPS coordinates.

Using this option the filename of the GPX file will be equal to the HRM file, except of the file extension being „gpx“, as both files belong together. tcx2hrm will store waypoint, route and track information per default. Lap information will be kept, as the track is segmented accordingly. Use -G option to influence behaviour as required.

Note, that GPX file data will be compiled out of the raw TCX file content, no data manipulation will be applied.

-G XYZ


The more advanced version of the -g option. XYZ is a three digit, numeric value, where tcx2hrm expects:

• X … If 0, turns off generation of waypoint information within the GPX file. Defaults to 1.
• Y … If 0, turns off generation of route information within the GPX file. Defaults to 1.
• Z … If 0, turns off generation of track information within the GPX file. Defaults to 1.  If value is 2, track segmentation according to initial lap information will not be obtained.

Note, this switch is for advanced users only, who are experienced in GPS data. Default values are designed to be applicable for most users. In fact -G 111 would give the same result as -g.

-h

Prints out the help splash screen with a short summary on available command line options. No further operations will be executed.

-i Interval

Selects the time interval the data will be aligned to in the HRM output file. According to the specifications, following values are available for the parameter Interval:

• X1S: one second interval; this interval was initially not supported by the original specification, but accepted by most of the HRM applications on the market, hence tcx2hrm supports it. A one second interval is recommended in case you want to optimize data accurracy. X1S has the same effect as I1S.
• I1S, I2S, I5S, I15S, I30S, I60S, I120S, I240S,  I480S:  interval in seconds, default = I1S (changed in v0.45)
• I5M: five minutes interval (300 seconds)

-l N

Selects a lap, that should be considered for data conversion. N is the positive integer number of the lap, starting with 1. Setting this value to zero forces the application to combine all laps into one output file but keep lap information in the intermediate times section. Default = 1.

-m Monitor

Sets the Polar device, which is used as the virtual source for the data. Following values are supported for parameter Monitor:

• ST, VXL, VNV, AP, XTP,  Coach, E600, AXN500, AXN700: Polar legacy devices, no or limited support for cycling data
• S210, S410, S510, S520, S610, S610i, S625X: Polar S-series, limited support for cycling data
• S710, S710i, S720i, S725, S725X: Polar S-series, specifically designed for bikers, hence full support of cycling data
• CS400, CS600X, CS600, RS400, RS800, RS800X: Latest professional monitors for cycling and running

Default values is S725X. Setting this to a different value might cause issues, as tcx2hrm does not check, whether the monitor supports all the data which is in the HRM file. However, the list only covers monitors with data download capabilities.

-n N

Selects the method to be applied for normalizing the input data. For N use the following values:

• 1 … extractor, deleting inconsistent data rows
• 2 … zero filler, fills up missing data columns with „0“ values
• 3 … linear mean algorithm, calculates mean values between valid predecessor and valid successor; default

 

-o N

Use this option to define the (restrictive) log level. Following values are available:

• 0 … debug
• 1 … info, default
• 2 … warn
• 3 … error

Setting the level to 1 means, that info, warning and error messages will be printed.

-s

Analyses the TCX input file and prints out statistical data. No further operations will be executed.

-t N

Selects a track, that should be considered for data conversion. N is the positive integer number of the track, starting with 1. Settings this value to  zero triggers the concatenation mode, where all tracks (of the selected lap) are concatenated. Default = 1.

-u

Requests unit conversion, any data values will be converted from SI units (km/h, km, m) to US units (mp/h, miles, ft). TCX data is always in SI units, HRM supports both.

-v Version

Sets the HRM file version to be used as output format. String Version can be V102, V105, V106 or V107. Default is V107 which provides the most flexibility. Using a different version restricts the support for specific data content, monitors and further options in the HRM file.

For any questions you would like to dig into in terms of data accuracy, please refer to this article.

Configuration file

Since v0.22 tcx2hrm supports an external configuration file, storing static fitness data. tcx2hrm searches for a file tcx2hrm.cfg on startup. The (text) configuration file follows a quite simple convention, where the application expects a single parameter/value pair per line, separated via „=“. Following parameters are supported:

• HRM_MAXHR
  Integer value of your maximum heart rate in bpm. Default is 0.
• HRM_RESTHR
  Integer value of your resting heart rate in bpm. Default is 0.
• HRM_VO2MAX
  Integer value of your maxium oxygen consumption value in ml/kg/min. Default is 0. Only used in HRM file version 1.06 or higher.
• HRM_WEIGHT
  Integer value of your weight in kg. Default is 0. Only used in HRM file version 1.06 or higher
• HRM_HRZONEX
  Use these parameters to define your personal HR zones, which will be written in the corresponding section in the HRM file. X starts with one (zone 1 upper limit) and ends with eleven (zone 10 lower limit), e.g. HRM_ZONE5
• DC_ADD_HR_DATA
  Use this parameter with value „1“ in case you want to override the check for heartrate presence in the input file. tcx2hrm will then be forced to zero fill heartbeat information in the output file.
• DC_FILL_BREAKS_LAPS
  If this parameter is provided with the value „1“, breaks within laps will be interpolated. Use this, if the lap segmentation in the exercise data is not desired.
• DC_FILL_BREAKS_TRACKS
  If this parameter is provided with the value „1“, breaks within tracks will be interpolated. Use this, if the track segmentation in the exercise data is not desired.

Return values

Beside of creating an outputfile (default operation), the tool returns different exit codes, depending on the stop condition. Those can be evaluated, e.g. via shell or batch script:

• 0 … no error occurred, application was terminated successfully
• 10 … a mandatory parameter was missing
• 11 … the format of the passed parameter was incorrect
• 12 … the parameter value was invalid
• 20 … errors while accessing the input file
• 21 … input file is empty, hence no data available to be converted