Examples: misc fixed & enhancements in the doc

examples/nfc-anticol.1

@@ -1,6 +1,6 @@
 .TH NFC-ANTICOL 1 "June 26, 2009"
 .SH NAME
-nfc-anticol \- Demonstration NFC anti-collison command line tool based on libnfc
+nfc-anticol \- Demonstration of NFC anti-collision command line tool based on libnfc
 .SH SYNOPSIS
 .B nfc-anticol
 .SH DESCRIPTION
@@ -14,6 +14,9 @@ software and should hope it does not contain vulnerabilities during the
 anti-collision phase.  Performing the anti-collision using custom frames could
 protect against a malicious tag that, for example, violates the standard by
 sending frames with unsupported lengths.
+Note that this is only a demonstration tool, which can not handle multiple tags
+as real life anti-collisions with multiple tags generate "messy" bits which
+are neither 0 nor 1.
 
 .SH BUGS
 Please report any bugs on the

examples/nfc-anticol.c

@@ -19,7 +19,7 @@
 
 /** 
  * @file nfc-anticol.c
- * @brief Generate one ISO14443-A anticollision process "by-hand"
+ * @brief Generate one ISO14443-A anti-collision process "by-hand"
  */
 
 #ifdef HAVE_CONFIG_H

examples/nfc-emulate-forum-tag4.1

@@ -5,17 +5,17 @@ nfc-emulate-forum-tag4 \- NFC Forum tag type 4 emulation command line demonstrat
 .B nfc-emulate-forum-tag4
 .SH DESCRIPTION
 .B nfc-emulate-forum-tag4
-is an demonstration tool that emulate a NFC Forum tag type 4 with NDEF content.
+is a demonstration tool that emulates a NFC Forum tag type 4 with NDEF content.
 
 Currently, this tool only works with a Nokia 6212 Classic phone as initiator
-and a PN532 equipped NFC device as target.
+and a PN532-equipped NFC device as target.
 
-This example use the hardware capability of PN532 to handle ISO/IEC 14443-4
+This example uses the hardware capability of PN532 to handle ISO/IEC 14443-4
 low-level frames like RATS/ATS, WTX, etc.
 
 At the moment, only the Nokia 6212 Classic can be used with this example
-because its based on a pre-established communication plan: example send the
+because it's based on a pre-established communication plan and the tool sends
-expected replies to the initiator without interprete queries.
+blindly the expected replies to the initiator without having interpreted the queries.
 
 .SH BUGS
 Please report any bugs on the

examples/nfc-emulate-tag.1

@@ -5,26 +5,28 @@ nfc-emulate-tag \- Simple tag emulation command line demonstration tool
 .B nfc-emulate-tag
 .SH DESCRIPTION
 .B nfc-emulate-tag
-is an simple tag emulation tool that demonstrate how emulation can be done
+is a simple tag emulation tool that demonstrates how emulation can be done
 using libnfc.
 
-Currently, this tool partialy emulates a Mifare Mini: its shown as Mifare Mini
+Currently, this tool partially emulates a Mifare Mini: it is detected as
-but internal MIFARE proprietary commands are not yet implemented.
+Mifare Mini but internal MIFARE proprietary commands are not yet implemented.
 
 To be able to emulate a target, there are two main parts:
  - communication: handle modulation, anticollision, etc.
  - computation: process commands (input) and produce results (output).
 
-This demonstration tool purpose a logical structure to handle communication and
+This demonstration tool proposes a logical structure to handle communication and
 a simple function to deal with computation.
 
 To improve the target capabilities, we can now implement more allowed commands
 in a single function: target_io()
 
-Please note that, due to timing issues is quiet impossible to implement a
+Please note that, due to timing issues, it is very difficult to implement an
-ISO14443-4 tag this way: RATS request expect a quick ATS answer. By the way,
+ISO14443-4 tag this way: RATS request expects a quick ATS answer. By the way,
-even you implements another kind of tag, timing issues are often the source of
+even if you implement another kind of tag, timing issues are often the source of
 problems like CRC or parity errors.
+The OmniKey CardMan 5321 is known to be very large on timings and is a good
+choice if you want to experiment with this emulator with a tolerant reader.
 
 .SH BUGS
 Please report any bugs on the

examples/nfc-emulate-tag.c

@@ -22,7 +22,7 @@
  * @brief Emulate a simple tag
  */
 
-// Note that depending on the device (initiator) you'll use against this
+// Note that depending on the device (initiator) you'll use against, this
 // emulator it might work or not. Some readers are very strict on responses
 // timings, e.g. a Nokia NFC and will drop communication too soon for us.
 

examples/nfc-emulate-uid.1

@@ -7,21 +7,38 @@ nfc-emulate-uid \- NFC target emulation command line tool based on libnfc
 .RI [ UID ]
 .SH DESCRIPTION
 .B nfc-emulate-uid
-is an tag emulation tool that allow to choose tag UID. Tag emulation is one of
+is a tag emulation tool that allows to choose any tag UID. Tag emulation is one
-the main added features in NFC. To avoid abuse of existing systems,
+of the main added features in NFC. But to avoid abuse of existing systems,
 manufacturers of the NFC controller intentionally did not support emulation of
-fully customized UID. The nfc-emulate-uid tool demonstrates that this can still
+fully customized UID but only of "random" UIDs, which always start with 0x08.
-be done using transmission of raw-frames, and the desired UID can be optionally
+The nfc-emulate-uid tool demonstrates that this can still be done using
-specified.
+transmission of raw frames, and the desired UID can be optionally specified.
-
-Fast communication is necessary to respond in time during the anti-collision
-protocol. Using the ACR122 device gives many timing issues, "PN53x only" USB
-devices also give some timing issues but an embedded microprocessor could be
-fast enough to emulate a tag with any UID.
 
 This makes it a serious thread for security systems that rely only on the
 uniqueness of the UID.
 
+Unfortunately, this example can't directly start in fully customisable
+target mode. Just after launching this example, you will have to go through
+the hardcoded initial anti-collision with the 0x08-prefixed UID.
+To achieve it, you can e.g. send a RATS (Request for Answer To Select) command
+by using a second NFC device (placed in target's field) and launching nfc-list 
+or nfc-anticol. After this first step, you now have a NFC device (configured
+as target) that really emulates a custom UID.
+You could view it using the second NFC device with nfc-list.
+
+Timing control is very important for a successful anti-collision sequence:
+
+- The emulator must be very fast to react:
+Using the ACR122 device gives many timing issues, "PN53x only" USB
+devices also give some timing issues but an embedded microprocessor
+would probably improve greatly the situation.
+
+- The reader should not be too strict on timing (the standard is very
+strict). The OmniKey CardMan 5321 is known to be very large on
+timings and is a good choice if you want to experiment with this
+emulator with a tolerant reader.
+Nokia NFC 6212 and Pegoda readers are much too strict and won't be fooled.
+
 .SH OPTIONS
 .IR UID
 8 hex digits format that represents desired UID (default is DEADBEAF).

examples/nfc-emulate-uid.c

@@ -21,19 +21,11 @@
  * @file nfc-emulate-uid.c
  * @brief This example can be used to emulate a tag which which have a "really" custom UID
  * 
- * NFC devices are able to emulate passive tags but manufacters restricts the
+ * NFC devices are able to emulate passive tags but manufacturers restrict the
- * customization of UID. With PN53x, UID is only 4 bytes long and the first
+ * customization of UID. With PN53x, UID is only 4-byte long and the first
- * byte of emulated UID is hardwarely set to 0x08.  This example show how to
+ * byte of emulated UID is hard-wired to 0x08 which is the standard way to say
- * emulate a full customized UID by "manually" replying to anticollision
+ * this is a random UID.  This example shows how to emulate a fully customized
- * process sent by the initiator.
+ * UID by "manually" replying to anti-collision process sent by the initiator.
- *
- * @note Unfortunately, this example can't directly start in fully customisable
- * target mode. Just after launching this example, you will have to unlock an
- * hardware situation by sending a RATS (Request for Answer To Select) command.
- * To do this, you can use a second NFC device (placed in target's field) and
- * launch nfc-list or nfc-anticol. After this first step, you now have a NFC
- * device (configured as target) that really emulate custom UID. You could view
- * it using the second NFC device with nfc-list.
  */
 
 #ifdef HAVE_CONFIG_H

examples/nfc-list.1

@@ -7,6 +7,9 @@ nfc-list \- List NFC targets
 .B nfc-list
 is a utility for listing any available targets like ISO14443-A, FeliCa, Jewel
 or ISO14443-B (according to the device capabilities).
+It may detect several tags at once thanks to a mechanism called anti-collision
+but all types of tags don't support anti-collision and there is some physical
+limitation of the number of tags the reader can discover.
 
 This tool displays all available information at selection time.
 

examples/nfc-mfclassic.1

@@ -12,15 +12,15 @@ nfc-mfclassic \- MIFARE Classic command line tool
 .B nfc-mfclassic
 is a MIFARE Classic tool that allow to read or write
 .IR DUMP
-file using Mifare keys provide in 
+file using Mifare keys provided in 
 .IR KEYS
 file.
 
 MIFARE Classic tag is one of the most widely used RFID tags.
 
 The firmware in the NFC controller supports authenticating, reading and writing
-to/from Mifare Classic tags. This tool demonstrate the speed of this library
+to/from Mifare Classic tags. This tool demonstrates the speed of this library
-and its easy-of-use. It possible to read and write the complete content of a
+and its ease-of-use. It's possible to read and write the complete content of a
 Mifare Classic 4KB tag within 1 second. It uses a binary Mifare Dump file (MFD)
 to store the keys and data for all sectors.
 
@@ -39,7 +39,7 @@ Use A or B Mifare keys.
 MiFare Dump (MFD) used to write (card to MFD) or (MFD to card)
 .TP
 .IR KEYS
-MiFare Dump (MFD) that contain the keys (optional)
+MiFare Dump (MFD) that contains the keys (optional). Data part of the dump is ignored.
 
 
 .SH BUGS