picchick documentation

picchick is a command-line utility used for programming and debugging microcontrollers.

This software is rapidly evolving while existing features are refined and new ones are added.

Installation

At least version 3.9 of python is needed to use picchick. The only required python dependency is pyserial for communicating with serial devices.

The xc8 compiler can be installed in order to program and debug PIC devices. For other devices types, you must define a custom device file. This is currently the only way to program devices that aren’t PICs.

Requirements

python

Python can be installed using your distro’s package manager. Picchick is developed using the latest version of python (currently 3.10), but has been tested lightly with python 3.92.
You might also have to install pip if you’re planning to install the package.

# Arch Linux
$ pacman -S python python-pip

# Ubuntu/Debian
$ apt-get install python3 python3-pip

xc8-cc (optional)

If you would like to proram PIC devices, you will need the device files provided with the xc8 compiler. The compiler can be downloaded from Microchip’s website. If you run arch linux, an AUR package is also available. Note that this package currently installs the out of date v2.36:

# Arch Linux AUR
$ git clone https://aur.archlinux.org/microchip-mplabxc8-bin.git
$ cd microchip-mplabxc8-bin/
$ makepkg .
$ pacman -U microchip-mplabxc8-bin-2.36-1-x86_64.pkg.tar

Install with pip

The easiest way to install picchick is with pip. It should be installed in the user’s python packages for convenience:

$ pip install --user picchick
<...>
$ picchick --help

This will install picchick and all of it’s python dependencies. If your python installation is configured correctly, the picchick executable will be available on your $PATH. If you installed it to your user python packages, you can find the picchick bin in ~/.local/bin

Install from source

For the latest version you might want to install the utility from the source repository. You might also want to run the utility without installing with pip.

Install source package

After installing the requirements, the git repo should be cloned to the local filesystem. Then the package can be built and installed to your user packages.

The -e, --editable flag can be added to automatically update the utility after a git pull or any other code changes.

$ git clone https://github.org/Rex--/picchick.git
$ cd picchick/
$ pip install --user [-e] .
<...>
$ picchick --help

This will install picchick and all of it’s python dependencies. If your python installation is configured correctly, the picchick executable will be available on your PATH.

Run source package

The package can be run as a python module. The python requirements will have to be installed manually. It accepts the same arguments and flags as if ran as a command-line utility.

$ git clone https://github.org/Rex--/picchick.git
$ cd picchick/
$ pip install --user -r requirements.txt
$ python -m picchick --help

A wrapper script in the root of the repository provides a bit cleaner interface:

$ chmod +x picchick.sh
$ ./picchick.sh --help

Usage

picchick is meant to be used as a general programming and debugging device. You are able to read/write/erase device memory, display hex files, and flash these files onto the device. Picchick tries to keep a common interface across all programmers and devices, so only these basic operations are supported by everything. However, programmers are free to implement their own actions and options, so always check the help for a specific programmer.

Programmers

A programmer is the device that picchick interacts with to program the device. Currently only a few programmers are supported, but plans are to eventually support several common programmers.

Each programmer implements it’s own connection options, for instance all serial programmers implement -P <port> and -B <baudrate> flags to configure the serial connection. Check each programmer’s options by specifying the help flag with the programmer argument.

Example 1. Programmer Options

$ picchick -c picstick --help
<...>
programmer options:
  -P port, --port port  programmer serial port
  -B baud, --baud baud  serial connection baudrate

$ picchick -c picstick -P <port> -B <baud>

Table 1. Supported Programmers
Name	Target	Description	Link
`picstick`	PIC ICSP	The picstick is a ATtiny44A USB-stick that supports the PIC low-voltage ICSP interface.	Github
`flipflop`	PIC	Flipflop runs as the bootloader on some PIC micros, reading and writing the device’s own memory.	Github
`arduino-icsp`	PIC	Arduino sketch that implements a programmer for PIC devices that use the low voltage In Circuit Serial Programming protocol.	Github

Devices

The chip that is being programmed is referred to as the device with the -d, --device flag. The <mcu> argument various between device types, more information can be found in Table 2 below. Some devices require additional software to be installed.

Example 2. Specifying a device

$ picchick -d <mcu>

In addition to the supported devices, you can specify a custom device by passing a path to an ini device file as the argument to the -d option. An example device file is given below, all of the fields are required.

Example 3. Custom Device Files

$ cat 16lf19197.ini
[16LF19197]
FAMILY = PIC16
ARCH = PIC14EX
BYTE_ORDER = big
WORD_SIZE = 2
ROW_SIZE = 64
FLASH = 8000
CONFIG = 8007-800B
$ picchick -d 16lf19197.ini

Table 2. Supported Devices
Target	MCU Equivalent	Additional Requirements
PIC	`xc8-cc -mcpu=<mcu>`	XC8 Compiler

Flashing

The -f, --flash flag is used in coordination with the hexfile argument in order to flash it to the device. Some devices require you to erase the memory before reprogramming—this is not done automatically. It is the user’s responsibility to include the --erase flag, but the erase is always done before write operations.

Example 4. Flashing a hex file

$ picchick -c <programmer> -d <mcu> -f <hexfile>

The flash command can be chained with multiple actions, like in the following example where we erase a device, flash the hexfile to it, then verify the memory.

Example 5. Erasing, Flashing, and Verifying a hex file

$ picchick -c <programmer> -d <mcu> -f -e -v <hexfile>

Reading

Reading is handled differently by different programmers, however the interface is the same. The -r, --read action takes two argument — a required address to read from <addr>, and an optional length [len]. The length is given in words which is based on the word_size of the device.

Example 6. Reading from a device

$ picchick -c <programmer> -d <mcu> -r <addr> [len]

# Read a single word from 0x400
$ picchick -c <programmer> -d <mcu> -r 400

# Read a block of 1024 words from 0x400
$ picchick -c <programmer> -d <mcu> -r 400 1024

Writing

Writing can only be done one address at a time with the command line. The flash operation may sometimes write more than one address at a time if the device requires it(Some PICs require flash to be written 1 row at a time), but this cannot be achieved with the current ui. Writing is currently used mostly for devices with EEPROM or writing configuration words.

Example 7. Writing to a device

$ picchick -c <programmer> -d <mcu> -w <addr> <word>

Erasing

The -e, --erase flag takes an address argument to determine what to erase. Most devices have to be erased in blocks, in this case (according to the programmer) the block containing the address will be erased.

Example 8. Erasing a device

$ picchick -c <programmer> -d <mcu> -e <addr>

Displaying Hex Files

There is a simple built-in utility to display hex files on the command line. If the device is specified and found, the hexfile will be decoded and displayed according to the specific device. The device flag can also be omitted, and the utility will decode them according to the base INHX32 spec. In either case, the data will be output in table format.

Example 9. Default byte map

$ picchick --map tests/blink.hex
Using hexfile: tests/blink.hex
  ADDR | x0  x1  x2  x3  x4  x5  x6  x7  x8  x9  xA  xB  xC  xD  xE  xF
-------+----------------------------------------------------------------
    x0 | x80 x31 x02 x28 x87 x31 xFD x2F
  xF20 |                                                         x87 x31
  xF30 | xA7 x27 x87 x31 x59 x01 x0C x17 x00 x32 x00 x32 x00 x00 x59 x01
  xF40 | x0C x13 x00 x32 x00 x32 x00 x00 x9A x2F x80 x31 x02 x28 x40 x01
  xF50 | x98 x01 x99 x01 x9A x01 x9B x01 x9C x01 x9D x01 x59 x01 x90 x01
  xF60 | x91 x01 x40 x01 x92 x01 x93 x01 x94 x01 x95 x01 x96 x01 x97 x01
  xF70 | x59 x01 x8E x01 x8F x01 x7E x01 xB8 x01 xC3 x01 xCE x01 xD9 x01
  xF80 | xE4 x01 x7C x01 xD0 x01 xDB x01 x7E x01 xB9 x01 xC4 x01 xCF x01
  xF90 | xDA x01 xE5 x01 x7C x01 xD1 x01 xDC x01 xE7 x01 x7E x01 xBA x01
  xFA0 | xC5 x01 xD0 x01 xDB x01 xE6 x01 x7C x01 xD2 x01 xDD x01 xE8 x01
  xFB0 | xFF x30 x7E x01 xBB x00 xFF x30 xC6 x00 xFF x30 xD1 x00 xFF x30
  xFC0 | xDC x00 xFF x30 xE7 x00 xFF x30 x7C x01 xD3 x00 xFF x30 xDE x00
  xFD0 | xFF x30 xE9 x00 xFF x30 x7E x01 xBC x00 xFF x30 xC7 x00 xFF x30
  xFE0 | xD2 x00 xFF x30 xDD x00 xFF x30 xE8 x00 xFF x30 x7C x01 xD4 x00
  xFF0 | xFF x30 xDF x00 xFF x30 xEA x00 x08 x00 x40 x01 x87 x31 x97 x2F
x10000 |                                                         xE8 x3F
x10010 |         x9F x3F

Example 10. PIC 2-byte words

$ picchick -d 16lf19197 --map tests/blink.hex
Found device: pic16lf19197
Using hexfile: tests/blink.hex
  ADDR |   x0    x1    x2    x3    x4    x5    x6    x7    x8    x9    xA    xB    xC    xD    xE    xF
-------+------------------------------------------------------------------------------------------------
    x0 | x3180 x2802 x3187 x2FFD
  x790 |                                           x3187 x27A7 x3187 x0159 x170C x3200 x3200 x0000 x0159
  x7A0 | x130C x3200 x3200 x0000 x2F9A x3180 x2802 x0140 x0198 x0199 x019A x019B x019C x019D x0159 x0190
  x7B0 | x0191 x0140 x0192 x0193 x0194 x0195 x0196 x0197 x0159 x018E x018F x017E x01B8 x01C3 x01CE x01D9
  x7C0 | x01E4 x017C x01D0 x01DB x017E x01B9 x01C4 x01CF x01DA x01E5 x017C x01D1 x01DC x01E7 x017E x01BA
  x7D0 | x01C5 x01D0 x01DB x01E6 x017C x01D2 x01DD x01E8 x30FF x017E x00BB x30FF x00C6 x30FF x00D1 x30FF
  x7E0 | x00DC x30FF x00E7 x30FF x017C x00D3 x30FF x00DE x30FF x00E9 x30FF x017E x00BC x30FF x00C7 x30FF
  x7F0 | x00D2 x30FF x00DD x30FF x00E8 x30FF x017C x00D4 x30FF x00DF x30FF x00EA x0008 x0140 x3187 x2F97
 x8007 = x3FE8
 x8009 = x3F9F

picchick(1)

Synopsis

picchick [-d <mcu>] [-c <programmer>] [-r <addr> [len] | -w <addr> <word> | -f] [-e [addr]] [-v] [hexfile]
picchick [-d <mcu>] --map <hexfile>
picchick --list-devices

picchick [-c <programmer>] -h/--help

Options

picchick accepts some common configuration options that dictate how to go about performing the action. Other options provide information about picchick itself. The programmer flag is required for all actions that involve a programmer. The device flag is required for all actions that involve a device.

-c <programmer>: The name of the programmer to use. Different programmers require different options, see the programmer’s options with picchick -c <programmer> -h.
-d, --device <mcu>: The device being programmed. The mcu argument is either a chip part number, or a path to a custom device file.
--version: Print the version number and exit.
-h, --help: Print usage information and a short help message. Can be combined with -c to get help about a specific programmer.

Actions

At least one action is required, else picchick would have nothing to do! Some actions cannot be used together, i.e. you cannot flash and write in the same command. Other actions can be chained, for instance you can erase a device, flash a hexfile, then verify the memory in one command.

-r, --read <addr> [len]: Read length words starting from addr. Length defaults to 2 if omitted.
-w, --write <addr> <word>: Write word to address.
-f, --flash: Flash hexfile to device.
-e, --erase [addr]: Erase addr. Address can be a hex number, 'all' or 'flash'.
-v, --verify: Verify written data. This can be used with either the write or flash actions, or by itself to verify against a hexfile.
--map: Pretty print hexfile, mapped to device if the -d flag is given.
--list-ports: List available serial ports.