[website_subgeniuskitty.com] / data / development / misc / garmin_edge_305_linux.md

# Linux Support #

## Overview ##

Linux support for Garmin GPS devices, especially those which monitor non-location data such as heartrate, is very poor. The situation is further confused by a plethora of conflicting, poorly documented file formats and outdated instructions. The following covers my process for downloading information from my Garmin Edge 305 bicycling GPS to a Linux workstation, including automatic file conversion to the TCX format since it is both supported by GoldenCheetah cycling software and, as an easily manipulated XML based format, should be easily convertable into other formats for many years to come.

## Instructions ##

First, disable the `garmin_gps` kernel module. On Debian wheezy this is accomplished by writing the following line to `/etc/modprobe.d/garmin-gps-blacklist.conf`

    blacklist garmin_gps

Download, build and install the `garmintools` package. The tarball contains a README that explains this process. This provides the `garmin_save_runs` program which will download data from your Garmin GPS and save it in the Garmin binary GMN format. It also includes the `garmin_dump` program which will convert a GMN file to an XML-life format. Note that you will need to be root, or set appropriate permissions for your user to have USB access. A sample run is shown below.

    Extracting data from Garmin EDGE305 Software Version 3.20
    Files will be saved in '/mnt/documents/Bicycling/logged_data'
    Wrote:   /mnt/documents/Bicycling/logged_data/2014/07/20140724T230419.gmn
    Wrote:   /mnt/documents/Bicycling/logged_data/2014/07/20140729T152915.gmn

Once you have obtained a GMN file, download the garmin-dev-master zip file. The `gmn2tcx` program accepts the GMN file as its sole argument and outputs the TCX file to stdout, as well as status messages (including success messages) to stderr. You will need to have `garmin_dump` from the garmintools package in your PATH environment variable. As an example, the following will create a new TCX file from an existing GMN file while still displaying status messages on the terminal.

    ataylor:~$ /usr/bin/gmn2tcx ./sample.gmn > ./sample.tcx
    - validates

To simplify the process, I created a small wrapper script that wraps these tools and performs the following operations.

* Extract new tracks from GPS as GMN for archiving
* Create TCX copy of new tracks for use performance tracking software
* Save session log for troubleshooting

The script uses python and can be configured by editing the configuration values located in the first few lines. After each cycling session you will only need to connect your Garmin device, execute the script and then launch the cycling software of your choice. 

## Wrapper Script ##

    #!/usr/bin/python
    
    # Wrapper script to dump files from Garmin Edge 305 and convert to TCX for import into GoldenCheetah
    # Requires garmintools and garmin-dev-master packages
    # Needs root permissions for USB access
    
    # Aaron Taylor
    # ataylor@subgeniuskitty.com
    
    # Configuration
    # path to garmin_save_runs, garmin_dump and libgarmintools.so
    path_garmintools = "/home/ataylor/bin/garmintools"
    # path to gmn2tcx and support files (saxon, etc)
    path_gmn2tcx = "/home/ataylor/bin/gmn2tcx"
    # path to save gmn data files
    path_save_gmn = "/mnt/documents/Bicycling/logged_data"
    # path to save tcx files
    path_save_tcx = "/mnt/documents/Bicycling/logged_data/temp_tcx"
    # path to log file for garmintools output
    path_log = "/tmp/garmintools.log"
    # UID/GID to set on new files
    uid = 1000
    gid = 1000
    
    import subprocess, os
    
    # Set up the environment. We want to append to PATH and LD_LIBRARY_PATH
    # in case some system files are in a funky place. However, we must first
    # check that the variables exist since they might be blank (like 
    # LD_LIBRARY_PATH on my system).
    my_env = os.environ
    try:
        my_env["PATH"]
    except:
        my_env["PATH"] = path_garmintools + ":" + path_gmn2tcx
    else: 
        my_env["PATH"] = my_env["PATH"] + ":" + path_garmintools + ":" + path_gmn2tcx
    try:
        my_env["LD_LIBRARY_PATH"]
    except: 
        my_env["LD_LIBRARY_PATH"] = path_garmintools
    else:
        my_env["LD_LIBRARY_PATH"] = my_env["LD_LIBRARY_PATH"] + ":" + path_garmintools
    my_env["GARMIN_SAVE_RUNS"] = path_save_gmn
    
    # Export the data from the GPS as binary gmn files and store STDOUT in result.
    result = subprocess.check_output(['/home/ataylor/bin/garmintools/garmin_save_runs'])
    
    # Newly written files will have a line starting with "Wrote:   " and then the full 
    # path to the new file. We want to extract only these lines and add them to the 
    # written_files list.
    line_start = 0
    written_files = []
    n = 0
    for i in result:
        if i == b'\n':
            line_start = n+1
        elif line_start == n:
            first_chars = "" 
            for k in range(9):
                first_chars += result[n+k]
            if first_chars == b'Wrote:   ':
                k = 9
                temp_string = ""
                while result[n+k] != b'\n':
                    temp_string += result[n+k]
                    k += 1
                written_files.append(temp_string)
        n += 1
    
    # Dump output of garmintools run for analysis in case something goes wrong
    file_log = open(path_log, 'w')
    file_log.write(result)
    file_log.close()
    
    # For any newly written gmn files, save a copy as tcx format in directory specified
    # by path_save_tcx so I can import to GoldenCheetah next time I start it.
    devnull = open(os.devnull, 'w')
    if not written_files:
        print "No new files to process."
    else:
        print "New TCX files:"
    for path_gmn in written_files:
        path_tcx = path_save_tcx + "/" + os.path.split(path_gmn)[1].replace(".gmn", ".tcx")
        print path_tcx
        file_tcx = open(path_tcx, 'w')
        subprocess.call(["gmn2tcx", path_gmn], stdout=file_tcx, stderr=devnull)
        file_tcx.close()
        os.chown(path_tcx, uid, gid)
    devnull.close()

## Files ##

Where possible, obtain the latest version of these files from their original creators. What follows is an archived copy of the versions I used when first setting this project up, in case the author's pages disappear.

* [garmintools-0.10](garmin_edge_305_linux.files/Garmintools-0.10.tar.gz)
* [garmin-dev-master](garmin_edge_305_linux.files/Garmin-dev-master.zip)
* [edge305.py](garmin_edge_305_linux.files/Edge305.py)
Commit	Line	Data
f6e94cb2 AT	1	# Linux Support #
	2
	3	## Overview ##
	4
	5	Linux support for Garmin GPS devices, especially those which monitor non-location data such as heartrate, is very poor. The situation is further confused by a plethora of conflicting, poorly documented file formats and outdated instructions. The following covers my process for downloading information from my Garmin Edge 305 bicycling GPS to a Linux workstation, including automatic file conversion to the TCX format since it is both supported by GoldenCheetah cycling software and, as an easily manipulated XML based format, should be easily convertable into other formats for many years to come.
	6
	7	## Instructions ##
	8
	9	First, disable the `garmin_gps` kernel module. On Debian wheezy this is accomplished by writing the following line to `/etc/modprobe.d/garmin-gps-blacklist.conf`
	10
	11	blacklist garmin_gps
	12
	13	Download, build and install the `garmintools` package. The tarball contains a README that explains this process. This provides the `garmin_save_runs` program which will download data from your Garmin GPS and save it in the Garmin binary GMN format. It also includes the `garmin_dump` program which will convert a GMN file to an XML-life format. Note that you will need to be root, or set appropriate permissions for your user to have USB access. A sample run is shown below.
	14
	15	Extracting data from Garmin EDGE305 Software Version 3.20
	16	Files will be saved in '/mnt/documents/Bicycling/logged_data'
	17	Wrote: /mnt/documents/Bicycling/logged_data/2014/07/20140724T230419.gmn
	18	Wrote: /mnt/documents/Bicycling/logged_data/2014/07/20140729T152915.gmn
	19
	20	Once you have obtained a GMN file, download the garmin-dev-master zip file. The `gmn2tcx` program accepts the GMN file as its sole argument and outputs the TCX file to stdout, as well as status messages (including success messages) to stderr. You will need to have `garmin_dump` from the garmintools package in your PATH environment variable. As an example, the following will create a new TCX file from an existing GMN file while still displaying status messages on the terminal.
	21
	22	ataylor:~$ /usr/bin/gmn2tcx ./sample.gmn > ./sample.tcx
	23	- validates
	24
	25	To simplify the process, I created a small wrapper script that wraps these tools and performs the following operations.
	26
	27	* Extract new tracks from GPS as GMN for archiving
	28	* Create TCX copy of new tracks for use performance tracking software
	29	* Save session log for troubleshooting
	30
	31	The script uses python and can be configured by editing the configuration values located in the first few lines. After each cycling session you will only need to connect your Garmin device, execute the script and then launch the cycling software of your choice.
	32
	33	## Wrapper Script ##
	34
	35	#!/usr/bin/python
	36
	37	# Wrapper script to dump files from Garmin Edge 305 and convert to TCX for import into GoldenCheetah
	38	# Requires garmintools and garmin-dev-master packages
	39	# Needs root permissions for USB access
	40
	41	# Aaron Taylor
	42	# ataylor@subgeniuskitty.com
	43
	44	# Configuration
	45	# path to garmin_save_runs, garmin_dump and libgarmintools.so
	46	path_garmintools = "/home/ataylor/bin/garmintools"
	47	# path to gmn2tcx and support files (saxon, etc)
	48	path_gmn2tcx = "/home/ataylor/bin/gmn2tcx"
	49	# path to save gmn data files
	50	path_save_gmn = "/mnt/documents/Bicycling/logged_data"
	51	# path to save tcx files
	52	path_save_tcx = "/mnt/documents/Bicycling/logged_data/temp_tcx"
	53	# path to log file for garmintools output
	54	path_log = "/tmp/garmintools.log"
	55	# UID/GID to set on new files
	56	uid = 1000
	57	gid = 1000
	58
	59	import subprocess, os
	60
	61	# Set up the environment. We want to append to PATH and LD_LIBRARY_PATH
	62	# in case some system files are in a funky place. However, we must first
	63	# check that the variables exist since they might be blank (like
	64	# LD_LIBRARY_PATH on my system).
65	my_env = os.environ
66	try:
67	my_env["PATH"]
68	except:
69	my_env["PATH"] = path_garmintools + ":" + path_gmn2tcx
70	else:
71	my_env["PATH"] = my_env["PATH"] + ":" + path_garmintools + ":" + path_gmn2tcx
72	try:
73	my_env["LD_LIBRARY_PATH"]
74	except:
75	my_env["LD_LIBRARY_PATH"] = path_garmintools
76	else:
77	my_env["LD_LIBRARY_PATH"] = my_env["LD_LIBRARY_PATH"] + ":" + path_garmintools
78	my_env["GARMIN_SAVE_RUNS"] = path_save_gmn
79
80	# Export the data from the GPS as binary gmn files and store STDOUT in result.
81	result = subprocess.check_output(['/home/ataylor/bin/garmintools/garmin_save_runs'])
82
83	# Newly written files will have a line starting with "Wrote: " and then the full
84	# path to the new file. We want to extract only these lines and add them to the
85	# written_files list.
86	line_start = 0
87	written_files = []
88	n = 0
89	for i in result:
90	if i == b'\n':
91	line_start = n+1
92	elif line_start == n:
93	first_chars = ""
94	for k in range(9):
95	first_chars += result[n+k]
96	if first_chars == b'Wrote: ':
97	k = 9
98	temp_string = ""
99	while result[n+k] != b'\n':
100	temp_string += result[n+k]
101	k += 1
102	written_files.append(temp_string)
103	n += 1
104
105	# Dump output of garmintools run for analysis in case something goes wrong
106	file_log = open(path_log, 'w')
107	file_log.write(result)
108	file_log.close()
109
110	# For any newly written gmn files, save a copy as tcx format in directory specified
111	# by path_save_tcx so I can import to GoldenCheetah next time I start it.
112	devnull = open(os.devnull, 'w')
113	if not written_files:
114	print "No new files to process."
115	else:
116	print "New TCX files:"
117	for path_gmn in written_files:
118	path_tcx = path_save_tcx + "/" + os.path.split(path_gmn)[1].replace(".gmn", ".tcx")
119	print path_tcx
120	file_tcx = open(path_tcx, 'w')
121	subprocess.call(["gmn2tcx", path_gmn], stdout=file_tcx, stderr=devnull)
122	file_tcx.close()
123	os.chown(path_tcx, uid, gid)
124	devnull.close()
125
126	## Files ##
127
128	Where possible, obtain the latest version of these files from their original creators. What follows is an archived copy of the versions I used when first setting this project up, in case the author's pages disappear.
129
130	* [garmintools-0.10](garmin_edge_305_linux.files/Garmintools-0.10.tar.gz)
131	* [garmin-dev-master](garmin_edge_305_linux.files/Garmin-dev-master.zip)
132	* [edge305.py](garmin_edge_305_linux.files/Edge305.py)