A small howto about creating new PURRR projects from scratch, including the darcs revision control. 1. Environment -------------- BROOD_HOME location of the brood source tree BROOD_STATE location of your brood project tree The system will guess the location of the first, and take $HOME/.brood to be the default state tree location. Your purrr project will be directory tree $BROOD_STATE/purrr/ Note that the relative path 'dir/subdir/file' is referred to in CAT as (dir subdir file) which is a list of symbols. 2. Init project tree -------------------- The first thing to do for a new project is to compile a monitor. This is the program that will run on the microcontroller, providing the PIC end of the communication link. It's a very simple program that can transfer data to and from the microcontroller, and execute code resident in flash on demand. To build a monitor, you need a seed file. This is just a configuration file for the part of purrr that creates a new project, including a boot monitor. The directory $BROOD_HOME/purrr/seed contains some examples. For example the '252-40.cat' file is a configuration file for a 18f252 chip running at 40MHz cpu freq (10MIPS), and contains the following: ((name . 252-40) (monitor . serial) (baud . 19200) (chip . p18f252) (fosc . 40000000)) init-project Here 'name' is the name of the purrr project. This determines the location of the project as $BROOD_STATE/purrr/252-40 The 'monitor' attribute determines which monitor to use. This refers to the file in $BROOD_HOME/purrr/monitor/serial.cat The 'baud' attribute is the baud rate of the serial monitor comm. The 'chip' attribute specifies which chip is used. And finally the 'fosc' attribute gives the chip main oscillator frequency in Hz. The word 'init-project' takes a dictionary -- a list of of ( name . value ) pairs -- and creates a project tree including a 'state.cat', 'init.cat' and 'monitor.cat' file. The latter is the binary monitor code in standard Intel HEX format, usable by any programmer. The former two contain data about the state of the chip. Most importantly, they contain the dictionary which maps symbols to code addresses on the PIC, and a set of macros which define the (extendable) forth language. To create a project based on this particular file to (purrr seed 252-40) use 3. Uploading the monitor ------------------------ In case you obtained a pre-programmed pic chip which already contains a PURRR monitor application, make sure you have the associated project directory containing the 'state.cat' and 'init.cat' in the directory $BROOD_STATE/purrr/ Use your favourite programmer to upload the 'monitor.hex' file to the PIC. If you obtained the file from somebody else, it might contain chip configuration bits, most imporantly the oscillator configuration bits. If not, you might have to adjust these to fit your particular setup. This should put you at the point where you can type 'ping' in CAT, and the chip will reply. Happy hacking! 4. Loading a project -------------------- Once a project is bootstrapped, meaning the chip is programmed with the monitor code, and a the files reflecting the state of the chip are present, you can load a project into cat by issuing for example (purrr 252-40) restore Which will bring you to the point where you last left of. 5. Resetting a project ---------------------- To get the chip back to the state after freshly initializing it with a monitor, you can type 'forget'. This will erase all machine code stored after the monitor image, and reverts 'state.cat' to 'init.cat'. 6. Using darcs -------------- If you follow the instructions above, you'll get an error message: darcs failed: Unable to "darcs record" here. The reason for this is that CAT uses DARCS for version control of the state files. This means that all changes to a chip are saved in the event that you need to backtrack some changes. The entire memory image is stored, so if you can backtrack the state file, it is possible to reprogram the PIC chip itself with this backtracked state. To configure darcs for a project, simply type init-darcs You have to do this only once. To delete a darcs archive, cd to the project directory and remove the _darcs/ tree. To revert the pic to the memory image present in the host computer project database, use the word 'relead-binary' which takes start and end address as arguments.