From 464847c5b25588448e550017a6d91447c076b944 Mon Sep 17 00:00:00 2001 From: Tomasz Kramkowski Date: Wed, 23 Nov 2016 21:23:09 +0000 Subject: init commit --- hktool.1 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 hktool.1 (limited to 'hktool.1') diff --git a/hktool.1 b/hktool.1 new file mode 100644 index 0000000..12b8f81 --- /dev/null +++ b/hktool.1 @@ -0,0 +1,161 @@ +'\" 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 +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) -- cgit v1.2.3-54-g00ecf