# lpc-prg, a serial programmer (needs Tcl/Tk)
[LPC2xxx related tools running on the host]

A very simple programming tool. More...

A very simple programming tool.

Although this tool is fairly limited, it is sufficient to program a target board through the serial port and it even provides a very simple console to talk to your application. The tool is actually a `wish` (the Tk shell) script, therefore you can only use it if you have Tcl/Tk installed. The script assumes that `wish` can be found in the `/usr/bin` directory.

Also, the program relies on the Serial programming Tcl library. Thus, you have to have that library in your library path. If you installed the library at the default location, that means that you will have to add the following lines to you shell init script (if you use bash or similar):

`LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/armlib/bin
export LD_LIBRARY_PATH`

## Usage

When you start the program, you will get a simple GUI:

As you can see, it is divided to several panels:

### Serial port settings

The bottom panel deals with the serial port settings. You can set the serial device by clicking in the field and editing it; you have to press Enter to finalise the editing. You have to specify the full pathname to the serial device file, i.e. `/dev/ttyS0` or `/dev/ttyUSB2` or similar.

Underneath the device selection you will find three spinboxes that set the initial baudrate and the maximum baudrate to use while talking to the target chip's ISP and a third baud rate to use when the serial console is talking to your application code. Note that it is best to leave the initial baud rate at 9600 baud, it is in use for a very short time anyway.

The reset and the ISP lines of your target can be controlled manually or automatically, which you can select using the bottom-left radiobuttons. If you choose manual mode, every time one of those signals must be changed, you will get a message box asking you to assert or negate it. In case of automatic control, which you can only use if your reset and ISP signals are connected to the serial port's RTS and DTR signals, you have to specify whether you connected the reset to RTS or DTR (and, obviously, ISP to the other one). Furthermore, you have to specify if you inverted any of these signals. The non inverted signal means that you logically connected the serial chip's TTL level RTS and DTR, which are active low signals, to reset and ISP (or the other way around), which also are active low signals. On the RS-232 lines it means that whenever the RS-232 signal is active (i.e. it is above +3V) you have to activate (i.e. pull down) the target's reset or ISP.

### Trace

The middle-right panel is your trace panel. Most of the time you do not need it, but it can be handy to debug serial problems. The `Open trace window` button opens a window where internal messages from the low level C library, Serial programming C library are shown. Error messages are always shown. Target action messages tell you what is happening through the ISP command set, at a high level, such as reading/writing memory, erasing sectors and so on. If you are interested in the actual communication between your computer and the target chip, enable the serial comms tracing as well. The file I/O trace tells you about opening files, reading/writing them and so on. Finally, if you enable timstamping, then each log entry will have a timestamp, which is the time since the previous log entry, in milliseconds. If you opened the trace window, the button will change from open to close and you can use that to close the window, if you don't need it any more.

### Target

The target panel has only one field that you can edit. It is the target chip's clock frequency, in MHz. It is only important for chips that do not start up from an internal RC oscillator, such as the LPC2103. For chips that come up with an internally generated clock, this value is ignored. However, if it is set to the frequency of the internal clock, connecting becomes a tad faster. In any case, after connecting to the target, if the target has an internal clock, this field will be automatically set to the correct value. If you edit this field, you have to finish your editing by pressing Enter.

Below the clock field there are three fields that tell you information about the target if you are connected. The bottom line of the target panel is used to give you a progress feedback for slower operations.

### Options

The tool can handle Motorola S-record or Intel hex file formats. You can select one or the other to be used for all further file operations.

When you burn the FLASH in the target chip, you can select one of three modes. The simplest case is to erase only the sectors into which your code will go. That is, if you burn a 200 byte long code into an LPC2378, only the first 4KB of the FLASH (i.e. the first sector) will be erased, the remaining 500KB will not be touched.
By choosing `Erase the entire FLASH` you can tell the tool to wipe the whole chip before burning your code into it.
Your third option is to keep every byte in the FLASH that is not actually modified by your code. Although sectors modified by your code must be erased entirely, they will be read from the chip and merged with your code before the sector gets erased and burned.

If you save the content of the chip's FLASH into a file, you can choose not to save erased (i.e. containing 0xFF) sections. This makes your save file smaller, if you use only part of the FLASH.

In addition, you can tell the tool to automatically calculate the checksum of the vector table that the chip's ISP uses to decide whether to start the application or not. Note that the vector table checksum is only calculated if you loaded code into the vector table area (the first 32 bytes of the FLASH).

The manual power control option is helpful when your target chip gets seemingly unprogrammable. Due to a bug in the ISP code in the LPC2xxx chips, under certain circumstances the chip ignores the ISP line after reset, thus it starts the application code. However, if you power cycle the chip and keep reset low when you apply the power, you can force it to go to ISP mode. If you turn that option on, you will get a message box asking you to remove or apply the power so that the above method can be used to recover a chip that went to gaga land. It is a rarely needed option, but at those occasions it is indeed very useful.

### Actions

Initially, you can only connect to the target. Pressing the `Connect` button makes the program to attempt to drive the chip into ISP mode and get its identifier. If that fails, you get an error message. If it succeeds, then the button changes from `Connect` to `Disconnect` and the other actions become available.

The `Load hexfile` button pops up a file selection box. You can select a hexfile, which will be loaded into the internal buffer of the program. The hexfile must not contain addresses outside of the range of the target's FLASH.

The `Save the FLASH` button copies the content of the chip into the program's internal buffer then saves the buffer content into a hexfile. You have to provide the name of the hexfile, naturally. Note that this command makes the program's buffer to be a copy of the FLASH, therefore any previously loaded data will be lost.

The `Burn the FLASH` button burns the content that was loaded into the buffer into the target's FLASH, optionally calculating the checksum for the vector table before doing so.

The `Start console` button opens the console window, see below. Once you start the console, you will lose the content of the buffer and you will have to re-connect to the chip.

### The console window