'\" t
.TH "HKTOOL" "1" "2016-05-22" "hktool 0.1" "hktool Manual"

.SH "NAME"
hktool \- a simple HalfKay protocol flashing tool

.SH "SYNOPSIS"
.BR hktool\  [ -hlvr ]
.RB [ -f
.IR file ]
.RB [ -- ]
.I mcu

.SH "DESCRIPTION"
hktool is a HalfKay protocol flashing tool. hktool is currently only able to
flash to one connected device at a time, if multiple devices are connected,
only one will be flashed. hktool is designed to flash raw binary data and NOT
intel hex files. Converting from intel hex files to binary data can be easily
done with
.BR objcopy (1).
The main advantages of hktool over the teensy loader command line tool is that
devices are not hard coded, additionally, the command line interface is
noticeably simpler.

.SH "OPTIONS"
.BI \-f\  file
.RS
Flash specified binary file to the device. Specifying '-' as the file name
causes hktool to read input from stdin.
.RE

.B \-h
.RS
Show help.
.RE

.B \-l
.RS
Show a list of supported devices.
.RE

.B \-v
.RS
Show version and license information.
.RE

.B \-r
.RS
Reboot device (if specified with -f, will happen after flashing).
.RE

.SH "NOTES"
.SS Device parameter files
The list of devices that hktool can flash can be configured, either by creating
device parameter file and passing it to hktool as a relative path in the mcu
argument, or by adding more device parameter files to the hktool data
directories.

hktool searches for data in the hktool subdirectory of any directories found in
the XDG_DATA_DIRS environment variable (which should be a colon delimited list
of directories), if this variable is not set or empty then hktool proceeds as
if XDG_DATA_DIRS was set to "/usr/local/share:/usr/local". Device parameter
files should bear the name of the device and should be located directly in the
hktool subdirectory of the aforementioned locations. If two or more files are
found to have the same name, the file which was found first will be used.
Directories are processed in the order that they appear in the XDG_DATA_DIRS
environment variable.

The format of the device parameter files is very simple. These files should
consist of only one line detailing the flashing parameters and optionally the
canonical board name. The files are formatted as such:

.RS 4
.I memory_size block_size command_size address_shift
.RI [ board_name ]
.RE

For example, to create a file for the Teensy 3.1 place a file with the name
"MK20DX256" in one of the aforementioned locations and include the contents:

.RS 4
0x40000 1024 64 0 Teensy 3.1
.RE

This would describe a Teensy 3.1 which hosts MK20DX256 MCU with a memory size
of 262144 bytes, memory block size of 1024 bytes, HalfKay transfer prefix size
of 64 bytes with no shift applied to the write address. (Also note: the board
name can be multiple words in length.)

The table below shows the details for all the Teensy boards as of writing of
this man page.

.TS
box;
lb lb rb rb rb rb
l l r r r r .
Chip	Board	Memory	Block	Prefix	Shift
AT90USB162	Teensy 1.0	0x3e00	128	2	0
AT90USB646	Teensy++ 1.0	0xfc00	256	2	8
AT90USB1286	Teensy++ 2.0	0x1fc00	256	2	8
ATMEGA32U4	Teensy 2.0	0x7e00	128	2	0
MK20DX128	Teensy 3.0	0x20000	1024	64	0
MK20DX256	Teensy 3.1	0x40000	1024	64	0
MK64FX512	Teensy 3.5	0x100000	1024	64	0
MK66FX1M0	Teensy 3.6	0x80000	1024	64	0
MKL26Z64	Teensy LC	0xf800	512	64	0
.TE

.SS Unprivileged flashing
To be able to flash as an unprivileged user, udev must be configured correctly,
the rules recommended by PJRC can be found at:
\%http://www.pjrc.com/teensy/49-teensy.rules

.SS Converting from intel hex to binary
Converting from an intel hex file to a binary file is very simple with the use
of the
.BR objcopy (1)
program:

.RS 4
objcopy -I ihex -O binary in.hex out.bin
.RE

.SH "BUGS"
If multiple devices are connected at the same time, the device which will be
flashed is unspecified.

Providing unusual but valid flashing parameters to hktool will cause it to exit
(usually from an allocation failure). This is unlikely to happen during correct
operation.

If you find any other bugs, please report them to hktool.bugs@the-tk.com

.SH "FILES"
.TP
.I /etc/hktoolrc
System device list configuration file.
.TP
.IR $XDG_CONFIG_HOME/hktoolrc " or " ~/.config/hktoolrc
User device list configuration file (XDG will be preferred).

.SH "EXAMPLES"
hktool -f blink.bin MK20DX256
.RS
Flash the file "blink.bin" to a connected Teensy 3.1 board which is currently
in HalfKay bootloader mode.
.RE

hktool -r ATMEGA32U4
.RS
Reboot a connected Teensy 2.0 board which is currently in HalfKay bootloader
mode.
.RE

hktool -f prog.bin -r MKL26Z64
.RS
Flash the file "prog.bin" to a connected Teensy LC board which is currently in
HalfKay bootloader mode and then reboot the device out of bootloader mode.
.RE

.SH "SEE ALSO"
.BR objcopy (1),
.BR udev (7)