README 4.95 KB
Newer Older
1
*-
2 3 4 5 6 7 8 9 10 11
* Free/Libre Near Field Communication (NFC) library
* 
* Libnfc historical contributors:
* Copyright (C) 2009      Roel Verdult
* Copyright (C) 2009-2013 Romuald Conty
* Copyright (C) 2010-2012 Romain Tartière
* Copyright (C) 2010-2013 Philippe Teuwen
* Copyright (C) 2012-2013 Ludovic Rousseau
* Additional contributors:
* See AUTHORS file
12 13 14 15 16 17 18 19
-*

General Information
===================

libnfc is a library which allows userspace application access to NFC devices.

The official web site is:
Philippe Teuwen's avatar
Philippe Teuwen committed
20
  http://www.nfc-tools.org/
21 22 23 24 25 26 27

The official forum site is:
  http://www.libnfc.org/community/

The official development site is:
  http://libnfc.googlecode.com/

28 29
Important note: this file covers POSIX systems, for Windows please read README-Windows.txt

Romain Tartiere's avatar
Romain Tartiere committed
30 31 32
Requirements
============

Philippe Teuwen's avatar
Philippe Teuwen committed
33
Some NFC drivers depend on third party software:
Romain Tartiere's avatar
Romain Tartiere committed
34

35
* pn53x_usb & acr122_usb:
Romain Tartiere's avatar
Romain Tartiere committed
36 37 38

   - libusb-0.1 http://libusb.sf.net

39
* acr122_pcsc:
Romain Tartiere's avatar
Romain Tartiere committed
40 41 42

   - pcsc-lite http://pcsclite.alioth.debian.org/

Philippe Teuwen's avatar
Philippe Teuwen committed
43
The regression test suite depends on the cutter framework:
Romain Tartiere's avatar
Romain Tartiere committed
44 45
http://cutter.sf.net

46 47 48
Installation
============

49 50 51 52 53 54 55 56
See the file 'INSTALL' for configure, build and install details.

Additionnally, you may need to grant permissions to your user to drive your device.
Under GNU/Linux systems, if you use udev, you could use the provided udev rules.
  e.g. under Debian, Ubuntu, etc.
    sudo cp contrib/udev/42-pn53x.rules /lib/udev/rules.d/

Under FreeBSD, if you use devd, there is also a rules file: contrib/devd/pn53x.conf.
57 58 59 60 61 62 63 64 65

How to report bugs
==================

To report a bug, visit http://code.google.com/p/libnfc/issues/list and fill
out a bug report form.

If you have questions, remarks, we encourage you to post this in the developers
community: 
66 67
http://www.libnfc.org/community

68 69 70 71 72 73 74 75 76 77 78
Please make sure to include:

* The version of libnfc

* Information about your system. For instance:

   - What operating system and version
   - For Linux, what version of the C library

  And anything else you think is relevant.

Philippe Teuwen's avatar
Philippe Teuwen committed
79 80 81 82 83 84 85 86
* A trace with debug activated.

  Reproduce the bug with debug, e.g. if it was:
  $ nfc-list -v
  run it as:
  $ LIBNFC_LOG_LEVEL=3 nfc-list -v

* How to reproduce the bug.
87 88 89 90 91 92 93 94 95 96 97 98 99 100

  Please include a short test program that exhibits the behavior. 
  As a last resort, you can also provide a pointer to a larger piece 
  of software that can be downloaded.

* If the bug was a crash, the exact text that was printed out
  when the crash occured.

* Further information such as stack traces may be useful, but
  is not necessary.

Patches
=======

Philippe Teuwen's avatar
Philippe Teuwen committed
101
Patches can be posted to http://code.google.com/p/libnfc/issues/list or
Philippe Teuwen's avatar
Philippe Teuwen committed
102 103
can be sent directly to libnfc's developers:
http://nfc-tools.org/index.php?title=Contact
104 105 106 107 108 109 110 111 112 113 114 115 116 117 118

If the patch fixes a bug, it is usually a good idea to include
all the information described in "How to Report Bugs".

Building
========

It should be as simple as running these two commands:

./configure
make

Troubleshooting
===============

119 120
Touchatag/ACR122:
-----------------
121 122 123
If your Touchatag or ACR122 device fails being detected by libnfc, make sure
that PCSC-lite daemon (pcscd) is installed and is running.

124 125
If your Touchatag or ACR122 device fails being detected by PCSC-lite daemon
(pcsc_scan doesn't see anything) then try removing the bogus firmware detection
126 127 128 129
of libccid: edit libccid_Info.plist configuration file (usually
/etc/libccid_Info.plist) and locate "<key>ifdDriverOptions</key>", turn
"<string>0x0000</string>" value into 0x0004 to allow bogus devices and restart
pcscd daemon.
130 131 132 133

ACR122:
-------
Using an ACR122 device with libnfc and without tag (e.g. to use NFCIP modes or
134 135 136
card emulation) needs yet another PCSC-lite tweak: You need to allow usage of
CCID Exchange command.  To do this, edit libccid_Info.plist configuration file
(usually /etc/libccid_Info.plist) and locate "<key>ifdDriverOptions</key>",
137
turn "<string>0x0000</string>" value into 0x0001 to allow CCID exchange or
138 139 140
0x0005 to allow CCID exchange and bogus devices (cf previous remark) and
restart pcscd daemon.

141 142 143
Warning: if you use ACS CCID drivers (acsccid), configuration file is located
in something like: /usr/lib/pcsc/drivers/ifd-acsccid.bundle/Contents/Info.plist

144 145 146 147 148 149
SCL3711:
--------
Libnfc cannot be used concurrently with the PCSC proprietary driver of SCL3711.
Two possible solutions:
* Either you don't install SCL3711 driver at all
* Or you stop the PCSC daemon when you want to use libnfc-based tools
150

151 152 153 154 155 156 157 158
PN533 USB device on Linux >= 3.1:
---------------------------------
Since Linux kernel version 3.1, two kernel-modules must not be loaded in order
to use libnfc : "nfc" and "pn533".
To prevent kernel from loading automatically these modules, you can blacklist
them in a modprobe conf file. This file is provided within libnfc archive:
  sudo cp contrib/linux/blacklist-libnfc.conf /etc/modprobe.d/blacklist-libnfc.conf

159 160
Proprietary Notes
=================
161

162 163 164 165
FeliCa is s registered trademark of the Sony Corporation.
MIFARE is a trademark of NXP Semiconductors.
Jewel Topaz is a trademark of Innovision Research & Technology.
All other trademarks are the property of their respective owners.
166