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.