1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
'\" 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)
|
