What is OpenRabbit?

A free portable replacement for the Digi Rabbit Field Utility and an on-target debugger. This allows Rabbit development on OSes other than Windows. The on-target debugger currently only works with programs created using the non-free Dynamic C (which can be run .e.g via wine).

It currently fully supports the Rabbit 2000, 3000. On the Rabbit 4000 up to 1 MB of 8-bit memory is fully supported (i.e. support includes all Rabbit 4000-based RCM except for the RC4000 and RCM4010). There is a little bit of experimental support for the Rabbit 5000 (readout of CPU, RAM and parallel flash info only so far; to use the internal RAM of the Rabbit 5000 instead of the default, use e.g --ramcr 0x43 - this is required for RCM that do not have external RAM, i.e. RCM5700 and RCM5710).

A free initial loader (coldload.bin) and secondary loader (pilot.bin) are included in OpenRabbit, but it will also work with loader binary blobs from Dynamic C 8 or 9 (however, using an initial loader from Dynamic C 8 or 9 will override any --ramcr command line option, and not work with Rabbit 5000 at all).

See BUILD for how to build it.

Use:

OpenRabbit supports two modes:

* Rabbit Field utility mode, invoke as "openrabbitfu". Flashing only. Works with files from any source, including SDCC and Dynamic C.
* OpenRabbit mode, invoke as "openrabbit". Debugging support. Requires files from Dynamic C.

Examples:

    openrabbitfu user.bin /dev/ttyUSB0

Will upload the user program user.bin onto the target via cable attached to /dev/ttyUSB0 and the default initial and secondary loaders.

    openrabbitfu --coldload coldload.bin --pilot pilot.bin user.bin /dev/ttyUSB0

Will upload the user program user.bin onto the target via cable attached to /dev/ttyUSB0 and using initial loader coldload.bin, secondary loader pilot.bin.

Options:

--help              Show usage information summary.
--verbose           Increase verbosity (this option can be used up to 3 times, with each additional use increasing verbosity).
--slow              Workaround for tcdrain() driver bugs (see below for details).
--run               Run program immediately after programming.
--serialout         Display data from serial line at 38400 baud until EOT
--ramcr <i>         Use specified RAM configuration instead of default 0x45 (/OE1, /CS1, 2 wait states)
--coldload <cl.bin> Use initial loader cl.bin
--pilot <pilot.bin> Use secondary loader pilot.bin

History:

OpenRabbit was initially developed and maintained by Lourens Rozema. His latest release was 0.1.1.
The original homepage can be found at http://www.lourensrozema.nl/index.php/openrabbit.inc

This repository has been created by Philipp Klaus Krause (with endorsement by Lourens Rozema) to continue development.

Troubleshooting (if operation is unreliable, or it doesn't work at all):

* Check if you or your programming cable is using a full-speed USB-to-serial interface with small receive buffer (e.g. the FT232R in the official "USB Programming Cable") with a USB High-Speed or faster hub. This can result in data loss. Suggested workaround: do not use USB hubs, use a high-speed USB-to-serial interface (e.g. FT232H), or one with a larger receive buffer (e.g. CP2102).
* If you are using a serial programming cable with a USB-to-serial converter, try --slow to work around a Linux driver bug (https://bugzilla.kernel.org/show_bug.cgi?id=209359). Most USB-to-serial converters work when using the --slow option.
* If you are using a serial programming cable with a CH340G-based USB-to-serial converter, check if you affected by a Linux driver bug (https://bugzilla.kernel.org/show_bug.cgi?id=220225) or FreeBSD driver bug (https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=287509).