DiscFerret:Downloads

Access libraries

libdiscferret (C library)

Libdiscferret allows applications written in C or C++ to access the DiscFerret, without having to worry about USB transaction management, packetisation and other low-level issues. It is known to run on any UNIX platform which provides the libusb-1.0 API. At the time of writing, this includes:

• Linux
• FreeBSD 8 (or later)
• Mac OS X (Darwin) -- tested and known to work on Lion, but believed to work on Snow Leopard as well (feedback would be appreciated)

To build it:

tar -zxf libdiscferret-version.tar.gz
make

To install it:

make install

By default, the libraries and headers are installed in /usr/local/lib and /usr/local/include respectively. To change this, append "PREFIX=path" to both the "make" and "make install" commands. For example, to install in /opt/discferret, use these commands:

make PREFIX=/opt/discferret
make install PREFIX=/opt/discferret

The latest version is Release 1.5, which can be downloaded from here: libdiscferret-1.5.tar.gz.

Change history

Release 1.5

CRITICAL UPDATE! -- Everyone should immediately update to this version.

• update microcode to REL_0028
• Bugfix: Properly handle situations where INDEX goes active on the same clock cycle as a flux transition
• Bugfix: Missed INDEX transitions were not stored in the ACQ RAM
• Implement test benches for disc reader core (more testbenches to add later)
• Update email addresses in microcode sources

Release 1.4

• update microcode to REL_0027
• Bugfix: if the disc-reader counter overflowed at exactly the same time a data or index pulse arrived, the overflow byte would be stored but the timing byte would be discarded. This corrupts the incoming data stream, rendering it useless.
• Completely new disc reader engine -- massively simplified the logic, debugged, and tested extensively with Icarus Verilog.
• Fix a nasty clock-enable bug in the microcode -- if the acquisition clock was less than 100MHz, carries may be repeated multiple times.

Release 1.3

• update microcode to REL_0026
• fix bad syntax in register header (ahem)
• update registers for microcode 0025 and later
• fix building of test application
• update udev rules for newer versions of udev
• Add udev rules file for DiscFerret devices
• hide output from rm during solib link
• fix makefile so libdiscferret also builds on Linux
• add idplatform.sh (req'd for new build system)
• Changes to allow libdiscferret to build on Mac OS X
• More fixes to use stdlib.h instead of malloc.h
• use stdlib.h instead of malloc.h (ooops!)
• fix uninitialized value warning
• tag release builds in the copyright notice, not just debug builds
• separate building of docs from main library
• Add missing microcode image (RBF file) and a README
• BUGFIX: fix issues with accidental double-stepping
• increase USB timeout to 1 second (from 100ms)
• fix issue with discferret_microcode.o not being linked into solib
• fixes for const-correctness, bump version to 1.2r2
• Include local copy of the DiscFerret microcode
• use DISCFERRET_ERROR enum where appropriate

Release 1.1r1

• Add support for the "Track 0 Reached During Seek" status bit
• Add discferret_seek_* functions to simplify head seek operations

Microcode

Microcode bundles (RBF files) are included with release versions of the C and Python APIs. Generally speaking, you should only use the microcode version which was included with a given version of the API. To upgrade to a later microcode version, upgrade the API.

For reference, the latest 'release' Microcode is version 0028, which is available to download here: microcode_0028.rbf.

Microcode change log

Rev 0028 (2012-JAN-11)

CRITICAL UPDATE -- included in libdiscferret 1.5

• Multiple fixes for disc reader engine (missing transition and missed-transition delay-slot logic).

Rev 0027 (2012-JAN-07)

CRITICAL UPDATE -- included in libdiscferret 1.4

• New disc reader engine (simplified and bugfixed)
• Major bug-fix: if a carry occurs at the same time a data pulse arrives, the data pulse will be ignored.

Rev 0026 (2011-DEC-31)

• fix clock divider logic
• Move ACQ clocksel bits to separate register, bump version to 0025
• Fix sync-word detector PJL counter value
• Data separator rewrite.
• Refactor data separator to use clock enable instead of divider, redesign sync logic
• Add clock divider for data acquisition engine

Rev 0021 (2011-MAR-21)

• Add "track 0 reached during seek" status bit.
• Improve seek logic to prevent "over-stepping" (seeking to a track below Track 0).

Firmware

The latest firmware package is version 001C, which can be downloaded from here.

Change history

Version 001C (2011-FEB-13)

• Fix a serious bug relating to USB hot-plugging. If the DiscFerret was powered up before the USB cable was connected, then the USB stack may not start up correctly. Additionally, if the USB cable is unplugged while the DiscFerret is powered up, the USB PHY may lose sync with the host.

Identifying the firmware version your DiscFerret is running

To identify the current firmware version of your DiscFerret (and its MCU Serial Number), use the id_program.py tool from the Firmware Source Code archive:

./id_program.py --info

This will display a screen similar to the following:

Device opened successfully
Device information:
	product:        DiscFerret magnetic disc analyser
	microcode_ver:  0x0020
	serialnumber:   TARKA
	firmware_ver:   0x001B
	microcode_type: 0xDD55
	hardware_rev:   0I06
	manufacturer:   Red Fox Engineering

The Microcode Type and Microcode Version will only be valid if a microcode bundle has been uploaded to the DiscFerret (i.e. if an application which uses the DiscFerret has already been run). If the Microcode Type is anything other than `0xDD55`, then the microcode version will not be valid. Device information can only be queried when the DiscFerret is running the operating firmware; the bootloader has no support for firmware version querying.

Upgrading the firmware

To upgrade the firmware on a DiscFerret, you will need a copy of the "mphidflash" program from http://code.google.com/p/mphidflash/.

The upgrade procedure is as follows:

1. Disconnect the USB and power cables from the DiscFerret.
2. Install a jumper cap over the two-pin header marked "BOOT".
3. Reconnect the USB cable, then the power cable.
4. The amber "MCU Status" LED should now be blinking rapidly.
5. Copy the firmware HEX file and mphidflash into the same directory.
6. From a command prompt, change into the directory containing mphidflash (e.g. `cd mphidflash`).
7. On Linux, run the following command:

   ./mphidflash -r -n -v 04d8 -p fbba -w discferret_firmware_XXXX.hex

   (replace XXXX with the firmware version number).
8. On Windows, run the following command:

   mphidflash -r -n -v 04d8 -p fbba -w discferret_firmware_XXXX.hex

   (replace XXXX with the firmware version number).
9. Unplug the DiscFerret, remove the BOOT jumper, then reconnect the USB and power cables (in that order). Your DiscFerret should now be running the latest firmware.

Bootloader

If the DiscFerret will not enter the bootloader even with the BOOT jumper installed, the bootloader may have become corrupted. In normal use, this should not be possible. It is, however, still possible to recover the DiscFerret, as long as you have a suitable PIC programmer. To do this, five wires must be soldered to the programming pads on the bottom of the DiscFerret PCB, and a PIC programmer (e.g. a Microchip PICKit 2) is connected to these wires. See the DiscFerret circuit diagram for the pin configuration of these pads.

NOTE: The DiscFerret uses a PIC18F85J50 microcontroller, which uses 3.3V Low Voltage Programming. Make ABSOLUTELY SURE your PIC programmer supports this programming mode (the PICKit 2, PICKit 3 and ICD3 do; the ICD2 DOES NOT), and that the device is set to "PIC18F85J50" (NOT auto-detect). Failure to follow these instructions WILL destroy the microcontroller IC!

After reprogramming the bootloader, the Unit Serial Number must be reprogrammed using id_program.py, which is included in the Firmware Source-Code Bundle, under the "test" directory. You will need to install the Python LibUSB wrapper library (on an Ubuntu Linux system, this is in the package `python-usb`) in order to use this tool.

DISCLAIMER: Damage caused by incorrectly reflashing the bootloader is NOT covered by the warranty! If you are not confident in your abilities, contact Red Fox Engineering to arrange for your DiscFerret to be re-programmed (a small charge may be made in order to cover postage and packing costs).

Bootloader HEX file: Bootloader Release 1.0 Final.