FIXME: this needs edit
Assumptions:
* the project is part of (your branch of) the brood distribution
* you're using darcs version control
1) Make a directory in brood/prj, and add to darcs
cd brood/prj
mkdir proto
darcs add proto
2) Copy the following files from another project. i.e. prj/CATkit and
add them to the darcs archive
cd proto
cp ../CATkit/init.ss
cp ../CATkit/monitor.f .
darcs add *
3) Edit the init.ss file to reflect your project settings.
skip step 4-6 if you have a chip with a purrr bootloader
4) Edit monitor.f for your chip
That file includes the support for the chip in the form of a
statement:
load p18f2620.f
Look in the directory brood/pic18 to see if such a file exists. If
it does, go to step 5).
If not, you need to create one and generate a constants file from
the header files provided by Microchip. I.e.:
cd brood/pic18
../bin/snarf-constants.pl \
< /usr/share/gputils/header/p18f2620.inc \
> p18f2620-const.f
The .INC file can alternatively be found in the MPLAB distribution,
in the MPASM directory.
Now you need to create the setup file for the chip. Start from a
chip that is similar
cp 18f1220.f p18f2620.f
And edit the file to reflect changes necessary for chip startup and
serial port initialization.
Don't forget to add the files to darcs, and send a patch!
darcs add p18f2620*.f
darcs record -m 'added p18f2620 configuration files'
darcs send --to brood@zwizwa.be http://zwizwa.be/darcs/brood
In case you can't send email from your host directly, replace the
"--to brood@zwizwa.be" option with an "--output darcs.bundle" option and
send the resulting darcs.bundle file.
5) To compile the monitor in the interactive console type this:
project prj/proto
scrap
6) Make a backup copy of the monitor state.
cp prj.ss monitor.ss
And flash the microcontroller using the monitor.hex file. In case
you're using the ICD2 together with piklab, the command line would
be:
piklab-prog -t usb -p icd2 --debug --firmware-dir
\
-c program monitor.hex
Here is the directory containing the ICD2 firmware, which can
be found in the microchip MPLAB distribution.
7) Next when you start the console, go back to the project by typing:
project prj/proto
8) Now you can start uploading forth files using commands like:
ul file.f
This will erase the previously uploaded file and replace it the new
one. If you want to upload multiple files, use the 'mark' word
after upload to prevent deletion:
ul file1.f
mark
ul file2.f
Now the next 'ul' will erase file2.f before uploading a new
file. To erase files manually, use the 'empty' word.
--- LIVE MODE ONLY ---
bin/purrr
project prj/CATkit
ping
FIXME: rest is old doc:
programming CATkit consists of 3 phases
1. INITIALIZATION: Burning monitor.hex
Starting from scratch, the first step is to run the command 'scrap' in
the interactive PURRR18 console. This will create a file called
'monitor.hex' which contains the code for the 'chip monitor', used to
load more code onto the chip later, and to perform basic interaction
with the host system.
When a chip comes from the factory, it is completely empty. It will
respond only to Microchip's in circuit programming protocol. You need
special hardware to talk to the chip, which is called a 'programmer',
and some software that supports this programmer device, to burn a hex
file to the chip.
One such programmer is the ICD2 obtainable from microchip, of which
there are several cheaper clones available. One such clone is
manufactured by Olimex. This one is the most complete: it is supported
by Microchip in the MPLAB toolchain, and there are several open source
tools available that can use this programmer device. We suggest to use
the command line tool 'piklab-prog' which is bundled with PikLab, an
open source MPLAB replacement.
There are other cheaper and simpler solutions, for example Broccoli18,
which uses the PC parallel port, and has some bundled software.
The CATkit board has a connector labeled ICD2. This is a standard
in-circuit programming connector, as used on the Olimex board, using 6
pins to connect the board to a programmer device.
To summarize: burning the monitor will transfer a hex image of the
monitor code, here referred to as 'monitor.hex' to the device, using
some programmer hardware and supporting software.
As an illustration, this is the command line used to burn the monitor
using 'pikab-prog':
piklab-prog -t usb -p icd2 --firmware-dir \
-d 18F1320 -c program monitor.hex
The parameter is the directory containing the Microchip ICD2
firmware, which is bundled with MPLAB.
2. APPLICATION DEVELOPMENT: using PURRR18 interactively
Once the monitor (bootloader / interactive interpreter) is installed
on the chip, you only need a serial cable to interact with the BROOD
tool chain. BROOD is a collection of tools used to compile low level,
PIC18 specific forth code (PURRR18) to binary code the microcontroller
understands, to upload this code and to inspect and interact with the
running system.
3. CONFIGURATION: using PURRR in a terminal emulator
(not finished yet)
Once an application (the low level part) is finished, interaction with
a target system can be done without the assistance of the BROOD tool
chain, using a fairly standard, standalone FORTH language called
PURRR, which hides most of the low-level details of PURRR18.