librfid - low-level RFID access library
-(C) 2005 by Harald Welte <laforge@gnumonks.org>
+(C) 2005-2008 by Harald Welte <laforge@gnumonks.org>
======================================================================
-This library intends to provide a reader- and (as much as possible)
+This library intends to provide a reader and (as much as possible)
PICC / tag independent API for RFID applications.
-1. Supported Prodocols:
+1. Supported Protocols:
-At this early stage of implementaition, it offers only ISO 14443-2, ISO 14443-3
-A and B as well as ISO 14443-4 (T=CL) support. Other protocols, both open
-(such as ISO 15693) and proprietary are to be added as soon as I find some more
-time.
+At this stage of implementation, it offers only ISO 14443-2, ISO 14443-3 A and
+B as well as ISO 14443-4 (T=CL) support. ISO15693 is only partiall
+implemented. Other protocols are to be added as soon as I find some more time.
2. Supported Readers:
-At this time only the Omnikey Cardman 5121 reader is supported.
+At this time, the Omnikey Cardman 5121/5321 and the OpenPCD readers are supported.
+
+2.1 Omnikey Cardman 5121/5321 RFID (http://www.omnikey.de/)
The cm5121 is a relatively stupid piece of hardware. Basically a contact-based
cm3121 that was enhanced by putting a Philips CL RC632 reader ASIC next to it.
the host (PC) software. Four primitives (read/write byte/fifo) are provided
via simple PC_to_RDR_Escape CCID messages.
+The cm5321 seems to be an improved version of the 5121, mainly with different
+antenna geometrics for better communications reliability.
+
+2.2 OpenPCD (http://www.openpcd.org/)
+
+The OpenPCD reader is completely free. You get the full schematics, the PCB
+design, and the source code to the device firmware (written in C, to be
+compiled with the free GNU toolchain). Also, all required development tools
+are available under Free Software licenses!
+
+In addition, it has various headers for access to the intermediate signal
+processing steps.
+
This makes it the ideal device to learn and play with RFID, since you don't
have any (proprietary) software interfere and puts you in full control of
everything.
+This is now the primary development target for librfid. However, this doesn't
+mean that we don't want to support as many readers as possible.
+
+Another interesting new option is to cross-compile librfid to fit it _inside_
+the OpenPCD firmware, enabling a fully autonomous RFID stack (and RFID
+applications) on the reader, without any requirement for a host PC!
+
+2.3 Philips Pegoda
+
+This reader is not yet supported. Some initial experiments have shown that
+adding support for it is feasible.
+
+2.4 spidev RC632
+
+This is not actually a specific reader, but a generic implementation of a
+CL RC632 based redaer attached to a SPI bus supported by the standard Linux
+SPI kernel driver architecture and it's spidev userspace interface.
+
+If you want to build this reader driver, use the '--enable-spidev' option
+to the './configure' command.
+
+2.x Further Readers
+
Support for more devices shouldn't be too difficult to add, provided the
devices are stupid enough. More sophisticated readers like Integrated
Engineering or Philips Pegoda do much of the protocol handling in firmware on a
-Microcontroller. This makes them (at least till now) faster, but also of
+microcontroller. This makes them (at least till now) faster, but also of
limited use, especially in education and research.
So if you happen to run into any other dumb RFID readers, especially those
-based on Philips CL RC531 and RC632, adding support should be very
-straightforward. If you want to contract me for implementing a driver backend,
-don't hesitate to contact me.
+based on Philips CL RC622, RC531 and RC632, adding support should be very
+straightforward. If you want to contract me for implementing a driver
+backend, don't hesitate to contact me.
-3. Installation
-In order to run librfid, you need a reader transport backend that provides a
-PC_to_RDR_Escape function. The current version of this library offers two backends
+3. Building / Installing
+
+In the default configuration, librfid only includes the driver for the OpenPCD
+dumbreader firmware.
+
+If you want support for Omnikey Cardman 5121/5321, you have to choose the
+backend you want to use, either:
3.1 (new) native CCID backend
-If you add the '--with-ccid' option to the './configure' command, then the new
+If you add the '--enable-ccid' option to the './configure' command, then the new
native CCID driver (courtesy of Werner Koch) will be linked into the library.
This requires a working libusb with development headers.
-In order to use the reader, you will need to set the permissions of the respective
-/proc/bus/usb or /sys/bus/usb files (or run the application as root, if you
-trust my code, which you shouldn't).
+In order to use the reader, you will need to set the permissions of the
+respective /proc/bus/usb or /sys/bus/usb files (or run the application as
+root, if you trust my code, which you shouldn't).
If you run udev, just use the 'etc/udev/librfid.rules' udev rulefile, which should
change the group of the usb device to 'users'.
3.2 (old) OpenCT backend
This backend has the advantage that it will allow you to use the contact-based
-part and the contactless part of the CM5121 simultaneously. However, it requires
-a patched version of OpenCT.
-
-A patch against openct-0.6.7 is available as openct-0.6.7-librfid.patch.
+part and the contactless part of the CM5121 simultaneously.
Please note that while librfid in this configuration _uses_ OpenCT as a
lower-layer transport interface, it doesn't actually provide a virtual reader
interface to it, i.e. you can't use CT-API/OpenCT/PCSC API's to access RFID
transponders.
+In order to use this backend, you need to use the
+'--enable-openct' option and - if it is not installed in a default
+location like /usr or /usr/local - set the environment variables
+PATH, LD_LIBRARY_PATH and PKG_CONFIG_PATH so all files are found.
+
+
4. Testing
In the 'utils' directory, you will get a 'librfid-tool' binary. It is very
-minimalistic, and mainly an example on how to use the librfid api. For an ICAO
-compliant passport, you may try "--protocol tcl". For a mifare ultralight transponder,
-"--protocol mifare-ultralight" will give you a full dump of the transponder.
+minimalist, and mainly an example on how to use the librfid API. For an ICAO
+compliant passport, you may try "--layer2 iso14443a --protocol tcl". For a
+mifare ultralight transponder, "--layer2 iso14443a --protocol
+mifare-ultralight" will give you a full dump of the transponder.
+
+The most basic command to get started is "librfid-tool --scan" to make it
+auto-detect the first available (and supported) transponder
+
+
+5. Help and Support
+
+If you run into any problems using librfid, the primary contact address is the
+mailinglist of librfid developers at librfid-devel@lists.gnumonks.org. Please
+note that while the development community is trying to provide the best level
+of support, response times might vary.
+
+You can subscribe to this list at
+ https://lists.gnumonks.org/mailman/listinfo/librfid-devel
+
+If you are interested in commercial grade support of librfid, feel free to
+contact me privately to discuss your requirements and provide you with a quote.
+
+6. Licensing
+
+Pleas read the file LICENSING.
-- Harald Welte <laforge@gnumonks.org>
projects / librfid / blobdiff