From 282d02bfcce22ace38452539f94f047a33f090d6 Mon Sep 17 00:00:00 2001 From: Google Code Exporter Date: Fri, 3 Apr 2015 04:20:05 -0400 Subject: [PATCH] Migrating wiki contents from Google Code --- ProjectHome.md | 43 ++++++++++++++++++++ ReleasingProcess.md | 47 ++++++++++++++++++++++ Roadmap.md | 98 +++++++++++++++++++++++++++++++++++++++++++++ UnitTests.md | 25 ++++++++++++ Versionning.md | 29 ++++++++++++++ 5 files changed, 242 insertions(+) create mode 100644 ProjectHome.md create mode 100644 ReleasingProcess.md create mode 100644 Roadmap.md create mode 100644 UnitTests.md create mode 100644 Versionning.md diff --git a/ProjectHome.md b/ProjectHome.md new file mode 100644 index 0000000..ac33829 --- /dev/null +++ b/ProjectHome.md @@ -0,0 +1,43 @@ +# libnfc # +This is development site of libnfc, the **Free/Libre Near Field Communication (NFC) Library**. + +Important: due to googlecode restrictions, libnfc's download section is now hosted at https://bintray.com/nfc-tools/sources/libnfc + +If you are new to libnfc, you should browse its dedicated wiki page[¹] to collect useful information and have a look to our forum[²]. + +What can you do with libnfc? + +There are plenty of projects based on libnfc. +A few of them originate from the same development team, you can find more info on them on the nfc-tools wiki[³] and nfc-tools project[⁴] + +## Installation ## +Installation steps are different depending on version you are willing to install. + +### Stable version ### +Please follow instructions present in our main website. +http://www.libnfc.org/documentation/installation + +### Development version ### +Fetch current version using Git as described in this page: http://code.google.com/p/libnfc/source/checkout + +You can compile development version using: +#### Under MacOSX, GNU/Linux, `*`BSD and probably a lot of POSIX systems #### +Note: If you want all libnfc hardware drivers, you will need to have libusb (library and headers) plus on `*`BSD and GNU/Linux systems, libpcsclite (library and headers). + +``` +autoreconf -vis +./configure --enable-doc +make +sudo make install +``` + +If you want to (re)generate documentation: +``` +make doc +``` + +## Links ## + * `[1]` **Dedicated wiki page**: http://nfc-tools.org/index.php?title=Libnfc + * `[2]` **Forum**: http://www.libnfc.org/community + * `[3]` **Official wiki**: http://nfc-tools.org/ + * `[4]` **nfc-tools project**: http://nfc-tools.googlecode.com \ No newline at end of file diff --git a/ReleasingProcess.md b/ReleasingProcess.md new file mode 100644 index 0000000..aea5152 --- /dev/null +++ b/ReleasingProcess.md @@ -0,0 +1,47 @@ +http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html + * Finalise human-readable changelog! (ChangeLog) + * Report any important code changes (NEWS) + * Commit all these files +``` +export LIBNFC_RELEASE=1.7.1 +git add NEWS ChangeLog configure.ac CMakeFiles.txt +git commit -m"Prepare $LIBNFC_RELEASE version" +git push +``` + * Check tarball distribution: +``` +cd /tmp +git clone https://code.google.com/p/libnfc/ +cd libnfc +autoreconf -is +./configure +make distcheck +cd .. +rm -rf libnfc/ +``` + * Add a git tag +``` +git tag -s libnfc-$LIBNFC_RELEASE -m"libnfc $LIBNFC_RELEASE" +git push origin libnfc-$LIBNFC_RELEASE +``` + * Build tarball archive +``` +cd /tmp +git clone https://code.google.com/p/libnfc/ +cd libnfc +sh make_release.sh +``` + * Backup archives +``` +scp libnfc-*$LIBNFC_RELEASE* libnfc:~/libnfc/ +``` + + * Upload archives to https://bintray.com/nfc-tools/sources/libnfc/ + + * Update API at http://www.libnfc.org/api/ +``` +ssh libnfc +update-api.sh libnfc/libnfc-doc-$LIBNFC_RELEASE.zip +``` + + * Announce on forum http://www.libnfc.org/community/forum/1/news-announcements/ \ No newline at end of file diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..62b9b83 --- /dev/null +++ b/Roadmap.md @@ -0,0 +1,98 @@ +# libnfc-1.4 # + +The aim of this release is to stabilise the current libnfc infrastructure. The library has grown quite hard recently but a few things are prone to long-term issues. In order to avoid posteponing an update of the libnfc, we focus on polishing the code and implementing better error management before releasing a 1.4 stable release. + +## Error reporting ## + +The following graphs represent the communication involved when sending a command to a NFC device (here a device with a PN532 connected via USB), and the dotted arows represent possible communication chanels not use in that context. As you can see, the current architecture is a bit simple (less arrows for communication) but really confusing because some function calls cannot be done directly at the chip driver level and so the code mix direct call to device driver with indirect calss through the chip driver. + +### Previous call path ### +
+
  1. pn53x_transceive()
    +
  2. pn53x_usb_transceive()
    +
  3. usb_bulk_write() The command is send to the device
    +
  4. usb_bulk_read() The device sends an ACK / NACK
    +
  5. Depending on the status
    +
    1. usb_bulk_read() if the command was send successfuly to read the command result
      +
    2. return an error otherwise (5.2.1, 5.2.2) (function terminates)
      +
  6. return the command result
    +
  7. usb_bulk_write() Send an ACK to the device (not done currently)
    +
  8. return the command result
    +
+ + +### New call path ### +
+
  1. pn53x_transceive()
    +
  2. pn53x_usb_transceive()
    +
  3. usb_bulk_write() The command is send to the device
    +
  4. usb_bulk_read() The device sends an ACK / NACK
    +
  5. The reply is returned to the PN53x management code
    +
  6. Depending on the result
    +
    1. If the device ACKed the command, execution continues was sent successfuly
      +
    2. An error is returned bach to the USB interface and propagates to the library (6.2.1, 6.2.2, 6.2.3) (function terminates)
      +
  7. usb_bulk_read() The device sends the response
    +
  8. The response is returned to the PN53x management code
    +
  9. A request for ACK is sent to the USB interface
    +
  10. usb_bulk_write() Send an ACK to the device
    +
  11. return the command result
    +
+ +In the old implementation (libnfc-1.3 and before), each device driver did it's own error detection (if any) and a lot of code was redundant (if not forgotten). The new implementation is slightly more complex but it's only a transition to what we would like to have in libnfc-1.6. + +ETA: september 2010 + +--- + +# libnfc-1.6 # + +The focus for 1.6 is a better abstraction of NFC devices. As of 1.3.x, we already have concepts of drivers and chips, but the overall architecture is pn53x-centric, and while there is no plan to support any other chip at the time of writing, this could became a major issue when we will decide to do so. It has so been decided to rework the way NFC devices are handled and provide a device agnostic and consistent API for NFC targets manipulation + + +## Better abstraction ## + +### Expected call path ### +
+
  1. pn53x_transceive()
    +
  2. pn53x_usb_transceive()
    +
  3. usb_bulk_write() The command is send to the device
    +
  4. usb_bulk_read() The device sends an ACK / NACK
    +
  5. The reply is returned to the PN53x management code
    +
  6. Depending on the result
    +
    1. A request to read the response is send to the USB interface if the command was sent successfuly
      +
    2. An error is returned if the command was not sent correctly (function terminates)
      +
  7. usb_bulk_read() The device sends the response
    +
  8. The response is returned to the PN53x management code
    +
  9. A request for ACK is sent to the USB interface
    +
  10. usb_bulk_write() Send an ACK to the device
    +
  11. return the command result
    +
+ +The goal is to provide consistent and reusable interfaces (API) that could be as follows: + +### Drivers API ### + * driver\_init + * driver\_list\_devices + * driver\_connect + * driver\_transceive + * driver\_disconnect + * driver\_free + +### Interfaces API ### + * interface\_init + * interface\_list\_device + * interface\_open + * interface\_read + * interface\_write + * interface\_close + * interface\_free + +ETA: TBD + +--- + +# libnfc-1.8 # + +Nothing discussed yet. I guess there is a log of nfc-ip stuff here. + +ETA: TBD \ No newline at end of file diff --git a/UnitTests.md b/UnitTests.md new file mode 100644 index 0000000..0d596b0 --- /dev/null +++ b/UnitTests.md @@ -0,0 +1,25 @@ +# Introduction # + +Add your content here. + +# Tests # + +## D.E.P. ## + +### Passive Mode ### +| _Target_ \ **Initiator** | **SCL3711** | **StickID** | **ACR122** | **LoGO** | **Adafruit PN532** | +|:-------------------------|:------------|:------------|:-----------|:---------|:-------------------| +| _SCL3711_ | 106/212/424 | 106/212/424 | --- | --- | 106/212/424 | +| _StickID_ | 106/212/424 | --- | 106/212/424 | 106/~~212~~ | --- | +| _ACR122_ | --- | 106/212/424 | --- | 106/~~212~~ | --- | +| _LoGO_ | --- | ~~106~~ | ~~106~~ | --- | --- | +| Adafruit PN532 | 106/212/424 | 106/212/424| --- | --- | --- | + +### Active Mode ### +| _Target_ \ **Initiator** | **SCL3711** | **StickID** | **ACR122** | **LoGO** | **Adafruit PN532** | +|:-------------------------|:------------|:------------|:-----------|:---------|:-------------------| +| _SCL3711_ | --- | 106/~~212~~ | --- | --- | 106/~~212~~ | +| _StickID_ | ~~106~~ | 106/~~212~~ | ~~106~~/212/424 | 106/~~212~~ | 106/~~212~~ | +| _ACR122_ | --- | 106/212/424 | --- | 106/~~212~~ | --- | +| _LoGO_ | --- | ~~106~~ | ~~106~~ | --- | --- | +| Adafruit PN532 | 106/~~212~~ | 106/~~212~~ | --- | --- | --- | \ No newline at end of file diff --git a/Versionning.md b/Versionning.md new file mode 100644 index 0000000..f5cfd8c --- /dev/null +++ b/Versionning.md @@ -0,0 +1,29 @@ +# Product version # +Since 1.2.x, we use a this numbering schemes: +The libnfc's version is composed as "A.B.C", where the number A denotes the libnfc version, the number B denotes the major revision of the libnfc, and the number C indicates the minor revision of the libnfc. +The major revision is used according to the traditional even-odd system version numbering system. The minor revision is changed whenever security patches, bug fixes, new features or drivers are implemented in the libnfc. + +# Library version (libtool) # +The library number is determined following: +http://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html + +# Debian version # +## Releases ## +The debian version follow the standard: +The libnfc debian package version is composed as "A.B.C-D, where "A.B.C" comes from libnfc's version and D denotes the debian package version. + +## Upstream version ## +In this case, the libnfc debian package version is composed as "A.B.CpreN.D-0", where "A.B.C" is the last released libnfc version, "N" is the next minor libnfc version and "D" denotes the debian package pre-version. + + +e.g. Starting from 1.5.0pre1.2-0... + +That is, 1.5.0pre1 is the upstream version ("1.5.1 in preparation") +and .2 is the upstream revision number of the debian subdirectory. +``` +Event New version number in debian/changelog +------------------------------ -------------------------------------- +Make another change in debian/ 1.5.0pre1.3-0 +Release 1.5.1-0 +Start new branch after release 1.5.1pre2.0-0 +``` \ No newline at end of file