AVRPROG(1)

NAME
avrprog - driver program for ``simple'' Atmel AVR MCU programmer

SYNOPSIS
avrprog -p partno [-c programmer-id] [-C config-file] [-e] [-E exitspec [,exitspec]] [-f format] [-F] [-i filename] [-m memtype] [-o filename] [-n] [-P parallel] [-t] [-v]

DESCRIPTION
Avrprog is a driver program for a simple programming hardware that allows one to program Atmel AVR microcontrollers, where the programmer is connected directly to a ppi(4) parallel port. In the simplest case, the hardware consists just of a cable, connecting the respective AVR signal lines to the parallel port.

The MCU is programmed in serial programming mode, so the MCU signals ‘/RESET’, ‘SCK’, ‘MISO’ and ‘MOSI’ need to be connected to the parallel port. Optionally, some otherwise unused output pins of the parallel port can be used to supply power for the MCU part, so it is also possible to construct a passive standalone programming device. Some status LEDs indicating the current operating state of the programmer can be connected, and a signal is available to control a buffer/driver IC 74LS367 (or 74HCT367). The latter can be useful to decouple the parallel port from the MCU when in-system programming is used.

See the file ${PREFIX}/share/doc/avrprog/avrprog.pdf for a schematic of the programming hardware.

Input files can be provided, and output files can be written in different file formats, such as raw binary files containing the data to download to the chip, Intel hex format, or Motorola S-record format. There are a number of tools available to produce those files, like asl(1) as a standalone assembler, or avr-objcopy(1) for the final stage of the GNU toolchain for the AVR microcontroller.

Avrprog can program the EEPROM and flash ROM memory cells of supported AVR parts. Where supported by the serial instruction set, fuse bits and lock bits can be programmed as well. These are implemented within avrprog as seperate memory types and can be programmed using data from a file (see the -m option) or from terminal mode (see the dump and write commands). It is also possible to read the chip (provided it has not been code-protected previously, of course) and store the data in a file. Finally, a ``terminal'' mode is available that allows one to interactively communicate with the MCU, and to display or program individual memory cells.

  Options
In order to control all the different operation modi, a number of options need to be specified to avrprog.

-p partno
    This is the only option that is mandatory for every invocation of avrprog. It specifies the type of the MCU connected to the programmer. These are read from the config file. If avrprog does not know about a part that you have, simply add it to the config file (be sure and submit a patch back to the author so that it can be incorporated for the next version). See the sample config file for the format. Currently, the following MCU types are understood:

    Option tag | Official part name
    1200 | AT90S1200
    2313 | AT90S2313
    2333 | AT90S2333
    4433 | AT90S4433
    4434 | AT90S4434
    8515 | AT90S8515
    8535 | AT90S8535
    m163 | ATMEGA163
    m103 | ATMEGA103
    m16 | ATMEGA16
    m8 | ATMEGA8

-c programmer-id
    Use the pin configuration specified by the argument. Pin configurations are read from the config file (see the -C option). New pin configurations can be easily added or modified through the use of a config file to make avrprog work with different programmers as long as the programmer supports the Atmel AVR serial program method. If that file contains an entry named “default”, this one will be used as default if -c programmer-id is missing; otherwise a builtin default will be used.

-C config-file
    Use the specified config file to load configuration data. This file contains all programmer and part definitions that avrprog knows about. If you have a programmer or part that avrprog does not know about, you can add it to the config file (be sure and submit a patch back to the author so that it can be incorporated for the next version). See the sample config file, located at ${PREFIX}/etc/avrprog.conf.sample, which contains a description of the format.

-e  Causes a chip erase to be executed. This will reset the contents of the flash ROM and EEPROM to the value ‘0xff’, and is basically a prerequisite command before the flash ROM can be reprogrammed again. The only exception would be if the new contents would exclusively cause bits to be programmed from the value ‘1’ to ‘0’. Note that in order to reprogram EERPOM cells, no explicit prior chip erase is required since the MCU provides an auto-erase cycle in that case before programming the cell.

-E exitspec
    [,exitspec] By default, avrprog leaves the parallel port in the same state at exit as it has been found at startup. This option modifies the state of the ‘/RESET’ and ‘Vcc’ lines the parallel port is left at, according to the exitspec arguments provided, as follows:

    reset
        The ‘/RESET’ signal will be left activated at program exit, that is it will be held low, in order to keep the MCU in reset state afterwards. Note in particular that the programming algorithm for the AT90S1200 device mandates that the ‘/RESET’ signal is active before powering up the MCU, so in case an external power supply is used for this MCU type, a previous invocation of avrprog with this option specified is one of the possible ways to guarantee this condition.

    noreset
        The ‘/RESET’ line will be deactivated at program exit, thus allowing the MCU target program to run while the programming hardware remains connected.

    vcc This option will leave those parallel port pins active (i. e. high) that can be used to supply ‘Vcc’ power to the MCU.

    novcc
        This option will pull the ‘Vcc’ pins of the parallel port down at program exit.

    Multiple exitspec arguments can be separated with commas.

-f format
    This option specifies the file format for the input or output files to be processed. Format can be one of:

    i   Intel Hex

    s   Motorola S-record

    r   raw binary; little-endian byte order, in the case of the flash ROM data

    a   auto detect; valid for input only, and only if the input is not provided at stdin.

    The default is to use auto detection for input files, and raw binary format for output files.

-F  Normally, avrprog tries to verify that the device signature read from the part is reasonable before continuing. Since it can happen from time to time that a device has a broken (erased or overwritten) device signature but is otherwise operating normally, this options is provided to override the check.

-i filename
    Specifies the input file to be programmed into the MCU. Can be specified as ‘-’ to use stdin as the input.

-m memtype
    Specifies which program area of the MCU to read or write; allowable values depend on the MCU being programmed, but most support at least eeprom for the EEPROM, and flash for the flash ROM. Use the -v option on the command line or the part command from terminal mode to display all the memory types supported by a particular device. The default is flash.

-n  No-write - disables actually writing data to the MCU (useful for debugging avrprog ).

-o filename
    Specifies the name of the output file to write, and causes the respective memory area to be read from the MCU. Can be specified as ‘-’ to write to stdout.

-P parallel
    Use parallel as the ppi(4) device to communicate with, instead of the default /dev/ppi0.

-t  Tells avrprog to enter the interactive ``terminal'' mode instead of up- or downloading files. See below for a detailed description of the terminal mode.

  Terminal mode
In this mode, avrprog only initializes communication with the MCU, and then awaits user commands on standard input. Commands and parameters may be abbreviated to the shortest unambiguous form. Terminal mode provides a command history using readline(3), so previously entered command lines can be recalled and edited. The following commands are currently implemented:

dump memtype addr nbytes
    Read nbytes bytes from the specified memory area, and display them in the usual hexadecimal and ASCII form.

dump
    Continue dumping the memory contents for another nbytes where the previous dump command left off.

write memtype addr byte1 ... byteN
    Manually program the respective memory cells, starting at address addr, using the values byte1 through byteN. This feature is not implemented for bank-addressed memories such as the flash memory of ATMega devices.

erase
    Perform a chip erase.

send b1 b2 b3 b4
    Send raw instruction codes to the AVR device. If you need access to a feature of an AVR part that is not directly supported by avrprog, this command allows you to use it, even though avrprog does not implement the command.

sig Display the device signature bytes.

part
    Display the current part settings.

file ...?

help
    Give a short on-line summary of the available commands.

quit
    Leave terminal mode and thus avrprog.

  Default Parallel port pin connections
(these can be changed, see the -c option)
Pin number | Function
2-5 | Vcc (optional power supply to MCU)
7 | /RESET (to MCU)
8 | SCK (to MCU)
9 | MOSI (to MCU)
10 | MISO (from MCU)
18-25 | GND

FILES

/dev/ppi0
    default device to be used for communication with the programming hardware

${PREFIX}/etc/avrprog.conf.sample
    sample pin configuration file

${PREFIX}/etc/avrprog.conf
    default pin configuration file

~/.inputrc
    Initialization file for the readline(3) library

${PREFIX}/share/doc/avrprog/avrprog.pdf
    Schematic of programming hardware

SEE ALSO
avr-objcopy(1), ppi(4), readline(3)

The AVR microcontroller product description can be found at

    http://www.atmel.com/atmel/products/prod23.htm

AUTHORS
Avrprog was written by Brian S. Dean <bsd@bsdhome.com>.

This man page by Joerg Wunsch.

BUGS
Motorola S-record files are not yet implemented.