git.rot13.org Git - librfid/blob - README

   1 librfid - low-level RFID access library
   2 (C) 2005-2007 by Harald Welte <laforge@gnumonks.org>
   3 ======================================================================
   4
   5 This library intends to provide a reader- and (as much as possible)
   6 PICC / tag independent API for RFID applications.
   7
   8 1. Supported Protocols:
   9
  10 At this early stage of implementation, it offers only ISO 14443-2, ISO 14443-3
  11 A and B as well as ISO 14443-4 (T=CL) support.  Other protocols, both open
  12 (such as ISO 15693) and proprietary are to be added as soon as I find some
  13 more time.
  14
  15 2. Supported Readers:
  16
  17 At this time, the Omnikey Cardman 5121/5321 and the OpenPCD readers are supported.
  18
  19 2.1 Omnikey Cardman 5121/5321 RFID (http://www.omnikey.de/)
  20
  21 The cm5121 is a relatively stupid piece of hardware.  Basically a contact-based
  22 cm3121 that was enhanced by putting a Philips CL RC632 reader ASIC next to it.
  23 There is no RFID protocol implementation on the cm5121, everything is done on
  24 the host (PC) software.  Four primitives (read/write byte/fifo) are provided
  25 via simple PC_to_RDR_Escape CCID messages.
  26
  27 The cm5321 seems to be an improved version of the 5121, mainly with different
  28 antenna geometrics for better communications reliability.
  29
  30 2.2 OpenPCD (http://www.openpcd.org/)
  31
  32 The OpenPCD reader is completely free.  You get the full schematics, the PCB
  33 design, and the source code to the device firmware (written in C, to be
  34 compiled with the free GNU toolchain).  Also, all required development tools
  35 are available under Free Software licenses!
  36
  37 In addition, it has various headers for access to the intermediate signal
  38 processing steps.
  39
  40 This makes it the ideal device to learn and play with RFID, since you don't
  41 have any (proprietary) software interfere and puts you in full control of
  42 everything.
  43
  44 This is now the primary development target for librfid.  However, this doesn't
  45 mean that we don't want to support as many readers as possible.
  46
  47 Another interesting new option is to cross-compile librfid to fit it _inside_
  48 the OpenPCD firmware, enabling a fully autonomous RFID stack (and RFID
  49 applications) on the reader, without any requirement for a host PC!
  50
  51 2.3 Philips Pegoda
  52
  53 This reader is not yet supported.  Some initial experiments have shown that
  54 adding support for it is
  55
  56 2.x Further Readers
  57
  58 Support for more devices shouldn't be too difficult to add, provided the
  59 devices are stupid enough.  More sophisticated readers like Integrated
  60 Engineering or Philips Pegoda do much of the protocol handling in firmware on a
  61 microcontroller.  This makes them (at least till now) faster, but also of
  62 limited use, especially in education and research.
  63
  64 So if you happen to run into any other dumb RFID readers, especially those
  65 based on Philips CL RC622, RC531 and RC632, adding support should be very
  66 straightforward.  If you want to contract me for implementing a driver
  67 backend, don't hesitate to contact me.
  68
  69
  70 3. Building / Installing
  71
  72 In the default configuration, librfid only includes the driver for the OpenPCD
  73 dumbreader firmware.
  74
  75 If you want support for Omnikey Cardman 5121/5321, you have to add
  76 '--enable-reader-cm5x21' to the './configure' command, _and_ choose the backend
  77 you want to use, either:
  78
  79 3.1 (new) native CCID backend
  80
  81 If you add the '--enable-ccid' option to the './configure' command, then the new
  82 native CCID driver (courtesy of Werner Koch) will be linked into the library.
  83 This requires a working libusb with development headers.
  84
  85 In order to use the reader, you will need to set the permissions of the
  86 respective /proc/bus/usb or /sys/bus/usb files (or run the application as
  87 root, if you trust my code, which you shouldn't).
  88
  89 If you run udev, just use the 'etc/udev/librfid.rules' udev rulefile, which should
  90 change the group of the usb device to 'users'.
  91
  92 3.2 (old) OpenCT backend
  93
  94 This backend has the advantage that it will allow you to use the contact-based
  95 part and the contactless part of the CM5121 simultaneously.  However, it requires
  96 a patched version of OpenCT.
  97
  98 A patch against openct-0.6.7 is available as openct-0.6.7-librfid.patch.
  99
 100 Please note that while librfid in this configuration _uses_ OpenCT as a
 101 lower-layer transport interface, it doesn't actually provide a virtual reader
 102 interface to it, i.e. you can't use CT-API/OpenCT/PCSC API's to access RFID
 103 transponders.
 104
 105 In order to use this backend, you need to use the
 106 '--enable-openct' option and - if it is not installed in a default
 107 location like /usr or /usr/local - set the environment variables
 108 PATH, LD_LIBRARY_PATH and PKG_CONFIG_PATH so all files are found.
 109
 110
 111 4. Testing
 112
 113 In the 'utils' directory, you will get a 'librfid-tool' binary.  It is very
 114 minimalist, and mainly an example on how to use the librfid API. For an ICAO
 115 compliant passport, you may try "--layer2 iso14443a --protocol tcl".  For a
 116 mifare ultralight transponder, "--layer2 iso14443a --protocol
 117 mifare-ultralight" will give you a full dump of the transponder.
 118
 119 The most basic command to get started is "librfid-tool --scan" to make it
 120 auto-detect the first available (and supported) transponder
 121
 122
 123 5. Help and Support
 124
 125 If you run into any problems using librfid, the primary contact address is the
 126 mailinglist of librfid developers at librfid-devel@lists.gnumonks.org.  Please
 127 note that while the development community is trying to provide the best level
 128 of support, response times might vary.
 129
 130 You can subscribe to this list at
 131         https://lists.gnumonks.org/mailman/listinfo/librfid-devel
 132
 133 If you are interested in commercial grade support of librfid, feel free to
 134 contact me privately to discuss your requirements and provide you with a quote.
 135
 136 6. Licensing
 137
 138 Pleas read the file LICENSING.
 139
 140 -- Harald Welte <laforge@gnumonks.org>
 141