Getting started

Getting Started
You've just bought or built your own OpenPCD device and are eager to get started? Then this is the right section for you to read.

For the beginning, it is recommended to first read the Hardware chapter to get an overview about the OpenPCD hardware.

Attaching OpenPCD to the host PC the first time
Your OpenPCD unit (if bought from the OpenPCD Webshop) will be flashed with a current version of both the sam7dfu bootloader and the main_dumbreader firmware.

The red LED should light up and the green LED should begin to flash as soon as the USB cable is attached.

On the host computer (running Linux), using the lsusb program of the usb-utils package, you should see: ... Bus 001 Device 011: ID 16c0:076b ...
 * 1) lsusb

To get more information, you can use

lsusb -v -d 16c0:076b

Bus 002 Device 010: ID 16c0:076b Device Descriptor: bLength               18 bDescriptorType        1 bcdUSB              2.00 bDeviceClass         255 Vendor Specific Class bDeviceSubClass      255 Vendor Specific Subclass bDeviceProtocol      255 Vendor Specific Protocol bMaxPacketSize0        8 idVendor          0x16c0 idProduct         0x076b bcdDevice           0.30 iManufacturer          3 bitmanufaktur.de IT Solutions and hmw-consulting.de  iProduct                4 OpenPCD RFID Simulator - Runtime Mode iSerial                0 bNumConfigurations     1 Configuration Descriptor: bLength                9 bDescriptorType        2 wTotalLength          57 bNumInterfaces         3 bConfigurationValue    1 iConfiguration         5 OpenPCD Runtime Configuration bmAttributes        0x80 (Bus Powered) MaxPower             500mA Interface Descriptor: bLength                9 bDescriptorType        4 bInterfaceNumber       0 bAlternateSetting      0 bNumEndpoints          3 bInterfaceClass      255 Vendor Specific Class bInterfaceSubClass     0 bInterfaceProtocol   255 iInterface             6 OpenPCD Runtime Interface Endpoint Descriptor: bLength                7 bDescriptorType        5 bEndpointAddress    0x01  EP 1 OUT bmAttributes           2 Transfer Type           Bulk Synch Type              None Usage Type              Data wMaxPacketSize    0x0040  1x 64 bytes bInterval              0 Endpoint Descriptor: bLength                7 bDescriptorType        5 bEndpointAddress    0x82  EP 2 IN        bmAttributes            2 Transfer Type           Bulk Synch Type              None Usage Type              Data wMaxPacketSize    0x0040  1x 64 bytes bInterval              0 Endpoint Descriptor: bLength                7 bDescriptorType        5 bEndpointAddress    0x83  EP 3 IN        bmAttributes            3 Transfer Type           Interrupt Synch Type              None Usage Type              Data wMaxPacketSize    0x0040  1x 64 bytes bInterval            255 Interface Descriptor: bLength                9 bDescriptorType        4 bInterfaceNumber       1 bAlternateSetting      0 bNumEndpoints          0 bInterfaceClass      254 Application Specific Interface bInterfaceSubClass     1 Device Firmware Update bInterfaceProtocol     1 iInterface             1 OpenPCD DFU Interface - Application Partition Interface Descriptor: bLength                9 bDescriptorType        4 bInterfaceNumber       2 bAlternateSetting      0 bNumEndpoints          0 bInterfaceClass      254 Application Specific Interface bInterfaceSubClass     1 Device Firmware Update bInterfaceProtocol     1 iInterface             2 OpenPCD DFU Interface - Bootloader Partition Device Status:    0x0000 (Bus Powered)

USB Debug Cable
On some systems, the CONFIG_USB_SERIAL_FTDI_SIO option has to be enabled as a module in the kernel for successful recognition of the USB-Debug-Cable!

Otherwise there won't be any /dev/ttyUSB* device available.

make menuconfig
When using the "make menuconfig" command to configure the kernel, the setting is under:

Device Drivers -> USB Support -> USB Serial Converter Support.

Press 'Y' when this option is highlighted to mark it to be compiled into the kernel.

Installing librfid
Currently, librfid is not (yet) shipped as a standard component with many Linux distributions. Also, the development status (and steady development progress) recommend that you always get the latest development version of librfid from the subversion server.

First, you will need to have the subversion programm 'svn' installed. All major distributions have a package available for it, many times it will be called 'svn'. Consult your distribution documentation on how to install additional packages. Commands you might want to try are apt-get install subversion yum install svn

You will also need to have installed some development tools and libraries, including: automake libtool libusb-dev libcurl-dev

Next, you can get a current development snapshot from the server by using svn co http://svn.gnumonks.org/trunk/librfid

then, change to the newly-created librfid directory and ./autogen.sh ./configure make

which will compile librfid and the tools in the utils directory.

If you run into problems, just contact the librfid-devel@lists.gnumonks.org mailinglist with a thorough description (including the exact error messages, your distribution version, etc.).

Using opcd_test
Next, let's try the opcd_test program for some peeking and poking of the device.

To compile opcd_test, check out the host and the firmware modules from the OpenPCD svn repository.

svn co http://svn.openpcd.org/trunk/firmware/ svn co http://svn.openpcd.org/trunk/host/ cd host/zebvty make cd .. make

Then look at the possible options.

opcd_test - OpenPCD Test and Debug Program (C) 2006 by Harald Welte  -l     --led-set       led {0,1} -w     --reg-write     reg value -r     --reg-read      reg -W     --fifo-write    hex -R     --fifo-read     hex -s     --set-bits      reg     mask -c     --clear-bits    reg     mask -u     --usb-perf      xfer_size -a     --adc-read -A     --adc-loop -S     --ssc-read -L     --loop -n     --serial-number
 * 1) ./opcd_test --help

Let's try to do something that produces a result in the OpenPCD device:

opcd_test - OpenPCD Test and Debug Program (C) 2006 by Harald Welte  setting LED 2 to off TX: (4): 02 01 02 00
 * 1) ./opcd_test -l 2 0

At this time the red LED should switch off. Similarly


 * 1) ./opcd_test -l 2 1

switches it on again. Or use the -n option to obtain your serial number:

opcd_test - OpenPCD Test and Debug Program (C) 2006 by Harald Welte  TX: (8): 03 01 00 01 00 00 00 00 SERIAL: (4): 91 5c c5 2f
 * 1) ./opcd_test -n

Using librfid
For actually using the main_dumbreader firmware as an RFID reader rather than an expensive USB-attached software-switchable LED, you'll need to obtain and install librfid.

Since librfid is a library, it is by its very nature something that programmers use to create programs. However, to actually make it do something without requiring every user to write his own program, there is a small program included called "librfid-tool".

Using librfid-tool and a supported RFID transponder (such as a Philips Mifare Classic/Ultralight card, or an ICAO compliant ePassport), you can do some further testing.

Scan/autodetect available transponder
Putting any supported RFID transponder on the reader (specifically: within the reading range) and executing the following command will autodetect the transponder type:

librfid-tool -s

Constantly keep scanning
The following command will run in an endless loop (until ctrl+c are pressed), scanning for available (and supported) RFID transponders:

librfid-tool -S

Reading Mifare Ultralight
librfid-tool -p mifare-ultralight

Selecting Master File of a T=CL compliant ISO 14443A PICC
librfid-tool -p tcl

FIXME: more details required.