├── datasheets
    ├── NXP PN7150
    │   ├── PN7150 Datasheet.pdf
    │   └── PN7150 User Manual - Host Interface - UM10936.pdf
    └── NFC Forum
    │   └── NFC Controller Interface Specification V1.0.pdf
├── src
    ├── PN7150.h
    ├── Tag.h
    ├── Tag.cpp
    ├── PN7150Interface.h
    ├── PN7150Interface.cpp
    ├── NCI.h
    └── NCI.cpp
├── Creative Commons — Attribution-NonCommercial-ShareAlike 4.0 International — CC BY-NC-SA 4.pdf
├── .editorconfig
├── library.properties
├── LICENSE.txt
├── .github
    └── workflows
    │   └── arduino-lint.yml
├── README.md
├── .gitignore
├── .clang-format
├── LICENSE-CC-BY-NC-SA-40.txt
└── LICENSE-GPL-30.txt


/datasheets/NXP PN7150/PN7150 Datasheet.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Strooom/PN7150/HEAD/datasheets/NXP PN7150/PN7150 Datasheet.pdf


--------------------------------------------------------------------------------
/datasheets/NFC Forum/NFC Controller Interface Specification V1.0.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Strooom/PN7150/HEAD/datasheets/NFC Forum/NFC Controller Interface Specification V1.0.pdf


--------------------------------------------------------------------------------
/datasheets/NXP PN7150/PN7150 User Manual - Host Interface - UM10936.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Strooom/PN7150/HEAD/datasheets/NXP PN7150/PN7150 User Manual - Host Interface - UM10936.pdf


--------------------------------------------------------------------------------
/src/PN7150.h:
--------------------------------------------------------------------------------
1 | // This file is here because the Arduino Library Checks likes to have a file with <libraryName>.h
2 | // As this library consists of 3 separate parts, each with their own .h file, this one can be empty


--------------------------------------------------------------------------------
/Creative Commons — Attribution-NonCommercial-ShareAlike 4.0 International — CC BY-NC-SA 4.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Strooom/PN7150/HEAD/Creative Commons — Attribution-NonCommercial-ShareAlike 4.0 International — CC BY-NC-SA 4.pdf


--------------------------------------------------------------------------------
/.editorconfig:
--------------------------------------------------------------------------------
 1 | [*.h]
 2 | indent_style = tab
 3 | indent_size = 4
 4 | trim_trailing_whitespace = true
 5 | 
 6 | [*.cpp]
 7 | indent_style = tab
 8 | indent_size = 4
 9 | trim_trailing_whitespace = true
10 | 
11 | [*.md]
12 | trim_trailing_whitespace = false


--------------------------------------------------------------------------------
/library.properties:
--------------------------------------------------------------------------------
 1 | name=PN7150
 2 | version=1.1.0
 3 | author=Strooom <pascal.roobrouck@gmail.com>
 4 | maintainer=Strooom <pascal.roobrouck@gmail.com>
 5 | sentence=Library for driving the PN7150, an NFC controller.
 6 | paragraph=Implements the NCI and part of the Reader/Writer application
 7 | category=Other
 8 | url=https://github.com/Strooom/PN7150
 9 | architectures=*
10 | 


--------------------------------------------------------------------------------
/LICENSE.txt:
--------------------------------------------------------------------------------
1 | SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
2 | 
3 | This library is dual-licensed under the GNU General Public License v3.0 (or later)
4 | OR Creative Commons Attribution Non Commercial Share Alike 4.0 International.
5 | You may choose either license at your option.
6 | 
7 | See LICENSE-CC-BY-NC-SA-40.txt and LICENSE-GPL-30.txt for the full license texts.
8 | 


--------------------------------------------------------------------------------
/.github/workflows/arduino-lint.yml:
--------------------------------------------------------------------------------
 1 | name: Arduino Library Checks
 2 | on: 
 3 |   push:
 4 |   pull_request:
 5 |     branches: [ main ]
 6 |     paths-ignore:
 7 |     - 'README.md'
 8 | jobs:
 9 |   ArduinoLintjob:
10 |     name: Run Arduino Lint
11 |     env:
12 |       compliance: strict
13 |     runs-on: ubuntu-latest
14 |     steps:
15 |       - uses: actions/checkout@v2
16 |       - uses: arduino/arduino-lint-action@v1
17 | 
18 | 
19 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # PN7150
 2 | Library/Driver for NXP PN7150 NFC device
 3 | 
 4 | All documentation is in the Repository Wiki : https://github.com/Strooom/PN7150/wiki
 5 | 
 6 | I need help : the NFC-Forum specifications are only free of charge for members. In order to improve and extend this driver, I need more and more recent specs. Please contact me if you are willing to share a copy with me. Thanks!
 7 | 
 8 | 
 9 | ## License
10 | 
11 | This library is dual-licensed under the GNU General Public License v3.0 (or later)
12 | OR Creative Commons Attribution Non Commercial Share Alike 4.0 International.
13 | You may choose either license at your option.
14 | 
15 | See `LICENSE-CC-BY-NC-SA-40.txt` and `LICENSE-GPL-30.txt` for the full license texts.
16 | 
17 | SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
18 | 


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | 
 2 | .pio
 3 | .vscode/.browse.c_cpp.db*
 4 | .vscode/c_cpp_properties.json
 5 | .vscode/launch.json
 6 | .vscode/ipch
 7 | 
 8 | idedata.json
 9 | project.checksum
10 | partitions.bin
11 | firmware.elf
12 | 
13 | 
14 | # #############################
15 | # ### Visual Studio Code    ###
16 | # #############################
17 | 
18 | .vscode/*
19 | !.vscode/settings.json
20 | !.vscode/tasks.json
21 | .vscode/launch.json
22 | .vscode/extensions.json
23 | !.vscode/*.code-snippets
24 | 
25 | # Local History for Visual Studio Code
26 | .history/
27 | 
28 | # Built Visual Studio Code Extensions
29 | *.vsix
30 | 
31 | # #############################
32 | # ### Platformio            ###
33 | # #############################
34 | 
35 | *.code-workspace
36 | .pioenvs
37 | .piolibdeps
38 | .clang_complete
39 | .gcc-flags.json
40 | .pio
41 | 
42 | # #############################
43 | # ### C++                   ###
44 | # #############################
45 | 
46 | # Compiled Object files
47 | *.slo
48 | *.lo
49 | *.o
50 | 
51 | # Compiled Dynamic libraries
52 | *.so
53 | *.dylib
54 | 
55 | # Compiled Static libraries
56 | *.lai
57 | *.la
58 | *.a
59 | 
60 | 


--------------------------------------------------------------------------------
/src/Tag.h:
--------------------------------------------------------------------------------
 1 | #pragma once
 2 | 
 3 | // SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
 4 | // #############################################################################
 5 | // ###                                                                       ###
 6 | // ### NXP PN7150 Driver                                                     ###
 7 | // ###                                                                       ###
 8 | // ### https://github.com/Strooom/PN7150                                     ###
 9 | // ### Author(s) : Pascal Roobrouck - @strooom                               ###
10 | // ### License : CC-BY-NC-SA-4.0 OR GPL-3.0-or-later                         ###
11 | // ###                                                                       ###
12 | // ### Credits : Thomas Buhot, for his PN7120 library, the predecessor of    ###
13 | // ### the PN7150. Due to the NFC Specs not being available for free, I used ###
14 | // ### his library to reverse-engineer some of the missing information links ###
15 | // ###                                                                       ###
16 | // #############################################################################
17 | 
18 | #include <stdint.h>        // Gives us access to uint8_t types etc
19 | 
20 | // Todo : upgrade everything to uint32 io uint8 as this is faster on 32-bit MCUs
21 | 
22 | class Tag {
23 |   public:
24 |     static constexpr uint32_t maxUniqueIdLength{10U};        //
25 |     uint8_t uniqueIdLength{0};                               // How long is the NFCID1 of the tag. Can be 4, 7 or 10 bytes. Typically 4 or 7.
26 |     uint8_t uniqueId[maxUniqueIdLength]{0};                  // array to store the NFCID1. Maximum length is 10 bytes at this time..
27 |     unsigned long detectionTimestamp;                        // remembers the time at which the tag was detected
28 | 
29 |   public:
30 |     // void print() const;                        // prints all properties of the tag to Serial
31 |     uint8_t getLength() const;                 // returns the length of the UID
32 |     uint8_t getID(uint8_t index) const;        // get the UID value at a certain index
33 |     void clear();                              // resets the datafields to their defaults
34 |     bool isSame(Tag *otherTag) const;          // compares this tag to another tag to see if they are identical
35 |     //v void dump() const;                         // send tag data to logging
36 | };
37 | 


--------------------------------------------------------------------------------
/src/Tag.cpp:
--------------------------------------------------------------------------------
 1 | // SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
 2 | // #############################################################################
 3 | // ###                                                                       ###
 4 | // ### NXP PN7150 Driver                                                     ###
 5 | // ###                                                                       ###
 6 | // ### https://github.com/Strooom/PN7150                                     ###
 7 | // ### Author(s) : Pascal Roobrouck - @strooom                               ###
 8 | // ### License : CC-BY-NC-SA-4.0 OR GPL-3.0-or-later                         ###
 9 | // ###                                                                       ###
10 | // #############################################################################
11 | 
12 | #include "tag.h"
13 | 
14 | 
15 | // void Tag::print() const {
16 | //     Serial.print("UniqueID = ");
17 | //     for (uint8_t index = 0; index < uniqueIdLength; index++) {
18 | //         uint8_t theValue = uniqueId[index];
19 | //         if (theValue < 16) {
20 | //             Serial.print("0x0");
21 | //         } else {
22 | //             Serial.print("0x");
23 | //         }
24 | //         Serial.print(theValue, HEX);
25 | //         Serial.print(" ");
26 | //     }
27 | // }
28 | 
29 | uint8_t Tag::getLength() const {
30 |     uint8_t length = uniqueIdLength;
31 |     return length;
32 | }
33 | 
34 | uint8_t Tag::getID(uint8_t index) const {
35 |     uint8_t value = uniqueId[index];
36 |     return value;
37 | }
38 | 
39 | void Tag::clear() {
40 |     uniqueIdLength = 0;
41 |     for (int i = 0; i < maxUniqueIdLength; i++) {
42 |         uniqueId[i] = 0;
43 |     }
44 | }
45 | 
46 | bool Tag::isSame(Tag *otherTag) const {
47 |     // First compare the length of both UIDs to see if they are the same length
48 |     if (uniqueIdLength == otherTag->uniqueIdLength) {
49 |         // Now check byte per byte if they are the same
50 |         for (uint8_t i = 0; i < uniqueIdLength; i++) {
51 |             if (uniqueId[i] != otherTag->uniqueId[i]) {
52 |                 return false;
53 |             }
54 |         }
55 |         return true;
56 |     } else {
57 |         return false;
58 |     }
59 | }
60 | 
61 | // void Tag::dump() const {
62 | //     char textLine[69] = "uniqueID =";
63 | //     char textPart[8];
64 | //     for (int i = 0; i < uniqueIdLength; i++) {
65 | //         snprintf(textPart, 8, " 0x%02X", uniqueId[i]);
66 | //         strcat(textLine, textPart);
67 | //     }
68 | // }


--------------------------------------------------------------------------------
/.clang-format:
--------------------------------------------------------------------------------
  1 | ---
  2 | Language:        Cpp
  3 | # BasedOnStyle:  Google
  4 | AccessModifierOffset: -2
  5 | AlignAfterOpenBracket: Align
  6 | AlignConsecutiveAssignments: true
  7 | AlignConsecutiveDeclarations: false
  8 | AlignEscapedNewlines: Left
  9 | AlignOperands:   true
 10 | AlignTrailingComments: true
 11 | AllowAllParametersOfDeclarationOnNextLine: true
 12 | AllowShortBlocksOnASingleLine: false
 13 | AllowShortCaseLabelsOnASingleLine: false
 14 | AllowShortFunctionsOnASingleLine: All
 15 | AllowShortIfStatementsOnASingleLine: true
 16 | AllowShortLoopsOnASingleLine: true
 17 | AlwaysBreakAfterDefinitionReturnType: None
 18 | AlwaysBreakAfterReturnType: None
 19 | AlwaysBreakBeforeMultilineStrings: true
 20 | AlwaysBreakTemplateDeclarations: true
 21 | BinPackArguments: true
 22 | BinPackParameters: true
 23 | BraceWrapping:   
 24 |   AfterClass:      false
 25 |   AfterControlStatement: false
 26 |   AfterEnum:       false
 27 |   AfterFunction:   false
 28 |   AfterNamespace:  false
 29 |   AfterObjCDeclaration: false
 30 |   AfterStruct:     false
 31 |   AfterUnion:      false
 32 |   AfterExternBlock: false
 33 |   BeforeCatch:     false
 34 |   BeforeElse:      false
 35 |   IndentBraces:    false
 36 |   SplitEmptyFunction: true
 37 |   SplitEmptyRecord: true
 38 |   SplitEmptyNamespace: true
 39 | BreakBeforeBinaryOperators: None
 40 | BreakBeforeBraces: Attach
 41 | BreakBeforeInheritanceComma: false
 42 | BreakBeforeTernaryOperators: true
 43 | BreakConstructorInitializersBeforeComma: false
 44 | BreakConstructorInitializers: BeforeColon
 45 | BreakAfterJavaFieldAnnotations: false
 46 | BreakStringLiterals: true
 47 | ColumnLimit:     0
 48 | CommentPragmas:  '^ IWYU pragma:'
 49 | CompactNamespaces: false
 50 | ConstructorInitializerAllOnOneLineOrOnePerLine: true
 51 | ConstructorInitializerIndentWidth: 4
 52 | ContinuationIndentWidth: 4
 53 | Cpp11BracedListStyle: true
 54 | DerivePointerAlignment: true
 55 | DisableFormat:   false
 56 | ExperimentalAutoDetectBinPacking: false
 57 | FixNamespaceComments: true
 58 | ForEachMacros:   
 59 |   - foreach
 60 |   - Q_FOREACH
 61 |   - BOOST_FOREACH
 62 | IncludeBlocks:   Preserve
 63 | IncludeCategories: 
 64 |   - Regex:           '^<ext/.*\.h>'
 65 |     Priority:        2
 66 |   - Regex:           '^<.*\.h>'
 67 |     Priority:        1
 68 |   - Regex:           '^<.*'
 69 |     Priority:        2
 70 |   - Regex:           '.*'
 71 |     Priority:        3
 72 | IncludeIsMainRegex: '([-_](test|unittest))?$'
 73 | IndentCaseLabels: true
 74 | IndentPPDirectives: None
 75 | IndentWidth:     4
 76 | IndentWrappedFunctionNames: false
 77 | JavaScriptQuotes: Leave
 78 | JavaScriptWrapImports: true
 79 | KeepEmptyLinesAtTheStartOfBlocks: false
 80 | MacroBlockBegin: ''
 81 | MacroBlockEnd:   ''
 82 | MaxEmptyLinesToKeep: 1
 83 | NamespaceIndentation: None
 84 | ObjCBlockIndentWidth: 2
 85 | ObjCSpaceAfterProperty: false
 86 | ObjCSpaceBeforeProtocolList: false
 87 | PenaltyBreakAssignment: 2
 88 | PenaltyBreakBeforeFirstCallParameter: 1
 89 | PenaltyBreakComment: 300
 90 | PenaltyBreakFirstLessLess: 120
 91 | PenaltyBreakString: 1000
 92 | PenaltyExcessCharacter: 1000000
 93 | PenaltyReturnTypeOnItsOwnLine: 200
 94 | PointerAlignment: Left
 95 | ReflowComments:  true
 96 | SortIncludes:    false
 97 | SortUsingDeclarations: true
 98 | SpaceAfterCStyleCast: false
 99 | SpaceAfterTemplateKeyword: true
100 | SpaceBeforeAssignmentOperators: true
101 | SpaceBeforeParens: ControlStatements
102 | SpaceInEmptyParentheses: false
103 | SpacesBeforeTrailingComments: 8
104 | SpacesInAngles:  false
105 | SpacesInContainerLiterals: true
106 | SpacesInCStyleCastParentheses: false
107 | SpacesInParentheses: false
108 | SpacesInSquareBrackets: false
109 | Standard:        Auto
110 | TabWidth:        4
111 | UseTab:          Never
112 | 
113 | 


--------------------------------------------------------------------------------
/src/PN7150Interface.h:
--------------------------------------------------------------------------------
 1 | #pragma once
 2 | 
 3 | // SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
 4 | // #############################################################################
 5 | // ###                                                                       ###
 6 | // ### NXP PN7150 Driver                                                     ###
 7 | // ###                                                                       ###
 8 | // ### https://github.com/Strooom/PN7150                                     ###
 9 | // ### Author(s) : Pascal Roobrouck - @strooom                               ###
10 | // ### License : CC-BY-NC-SA-4.0 OR GPL-3.0-or-later                         ###
11 | // ###                                                                       ###
12 | // #############################################################################
13 | 
14 | // Summary :
15 | //   This library implements the hardware interface for the NXP PN7150 NFC device.
16 | //   The PN7150 uses I2C plus 2 additional data signals : IRQ and VEN
17 | //     IRQ : output of the PN7150, input for the MCU. Through this signal the PN7150 signals it has data to be read by the MCU
18 | //     VEN : input of the PN7150, output for the MCU. Through this signal the MCU can RESET the PN7150
19 | //
20 | //   The library provides :
21 | //   * init() : Initialization of the interface
22 | //   * read() : Read message from PN7150 over I2C
23 | //   * write() : Write message to PN7150 over I2C
24 | //   * hasMessage() : Check if PN7150 has message waiting for MCU
25 | 
26 | #include <stdint.h>                                  // Gives us access to uint8_t types etc.
27 |                                                      // The HW interface between The PN7150 and the DeviceHost is I2C, so we need the I2C library.library
28 | #if defined(TEENSYDUINO) && defined(KINETISK)        // Teensy 3.0, 3.1, 3.2, 3.5, 3.6 :  Special, more optimized I2C library for Teensy boards
29 | #include <i2c_t3.h>                                  // Credits Brian "nox771" : see https://forum.pjrc.com/threads/21680-New-I2C-library-for-Teensy3
30 | #else
31 | #include <Wire.h>        // Otherwise, just use the more standard Wire.h - For ESP32 this will link in a version dedicated for this MCU
32 |                          // TODO :	i2c_t3.h ensures a maximum I2C message of 259, which is sufficient. Other I2C implementations have shorter buffers (32 bytes)
33 |                          //			See : https://github.com/Strooom/PN7150/issues/7
34 | #endif
35 | 
36 | class PN7150Interface {
37 |   public:
38 |     PN7150Interface(uint8_t IRQ, uint8_t VEN);                            // Constructor with default I2C address
39 |     PN7150Interface(uint8_t IRQ, uint8_t VEN, uint8_t I2Caddress);        // Constructor with custom I2C address
40 |     void initialize(void);                                                // Initialize the HW interface at the Device Host
41 |     uint8_t write(uint8_t data[], uint32_t dataLength) const;             // write data from DeviceHost to PN7150. Returns success (0) or Fail (> 0)
42 |     uint32_t read(uint8_t data[]) const;                                  // read data from PN7150, returns the amount of bytes read
43 |     bool hasMessage() const;                                              // does the PN7150 indicate it has data for the DeviceHost to be read
44 | 
45 |   private:
46 |     uint8_t IRQ;               // MCU pin to which IRQ is connected
47 |     uint8_t VEN;               // MCU pin to which VEN is connected
48 |     uint8_t I2Caddress;        // I2C Address at which the PN7150 is found. Default is 0x28, but can be adjusted by setting to pins at the device
49 | 
50 |     // public:
51 |     //     void test001();											// testing VEN output on the HW
52 |     //     void test002();											// testing IRQ input on the HW
53 |     //     void test003();											// testing the sending of an I2C message
54 |     //     void test004();											// testing the notification of data from the PN7150 by rising IRQ
55 |     //     void test005();											// sending CORE_RESET_CMD and checking if the PN7150 responds with CORE_RESET_RSP
56 | };
57 | 


--------------------------------------------------------------------------------
/src/PN7150Interface.cpp:
--------------------------------------------------------------------------------
  1 | // SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
  2 | // #############################################################################
  3 | // ###                                                                       ###
  4 | // ### NXP PN7150 Driver                                                     ###
  5 | // ###                                                                       ###
  6 | // ### https://github.com/Strooom/PN7150                                     ###
  7 | // ### Author(s) : Pascal Roobrouck - @strooom                               ###
  8 | // ### License : CC-BY-NC-SA-4.0 OR GPL-3.0-or-later                         ###
  9 | // ###                                                                       ###
 10 | // #############################################################################
 11 | 
 12 | #include "PN7150Interface.h"									// NCI protocol runs over a hardware interface, in this case an I2C with 2 extra handshaking signals
 13 | 
 14 | 
 15 | PN7150Interface::PN7150Interface(uint8_t IRQ, uint8_t VEN) : IRQ(IRQ), VEN(VEN), I2Caddress(0x28)
 16 |     {
 17 |     // Constructor, initializing IRQ and VEN and setting I2Caddress to a default value of 0x28
 18 |     }
 19 | 
 20 | PN7150Interface::PN7150Interface(uint8_t IRQ, uint8_t VEN, uint8_t I2Caddress) : IRQ(IRQ), VEN(VEN), I2Caddress(I2Caddress)
 21 |     {
 22 |     // Constructor, initializing IRQ and VEN and initializing I2Caddress to a custom value
 23 |     }
 24 | 
 25 | void PN7150Interface::initialize(void)
 26 |     {
 27 |     pinMode(IRQ, INPUT);												// IRQ goes from PN7150 to DeviceHost, so is an input
 28 |     pinMode(VEN, OUTPUT);											// VEN controls the PN7150's mode, so is an output
 29 | 
 30 |     // PN7150 Reset procedure : see PN7150 datasheet 12.6.1, 12.6.2.2, Fig 18 and 16.2.2
 31 |     digitalWrite(VEN, LOW);											// drive VEN LOW...
 32 |     delay(1);															// ...for at least 10us
 33 |     digitalWrite(VEN, HIGH);											// then VEN HIGH again, and wait for 2.5 ms for the device to boot and allow communication
 34 |     delay(3);
 35 | 
 36 |     Wire.begin();														// Start I2C interface
 37 |     }
 38 | 
 39 | bool PN7150Interface::hasMessage() const
 40 |     {
 41 |     return (HIGH == digitalRead(IRQ));								// PN7150 indicates it has data by driving IRQ signal HIGH
 42 |     }
 43 | 
 44 | uint8_t PN7150Interface::write(uint8_t txBuffer[], uint32_t txBufferLevel) const
 45 |     {
 46 |     Wire.beginTransmission(I2Caddress);									// Setup I2C to transmit
 47 |     uint32_t nmbrBytesWritten = 0;
 48 |     nmbrBytesWritten = Wire.write(txBuffer, txBufferLevel);				// Copy the data into the I2C transmit buffer
 49 |     if (nmbrBytesWritten == txBufferLevel)								// If this worked..
 50 |         {
 51 |         uint8_t resultCode;
 52 |         resultCode = Wire.endTransmission();							// .. transmit the buffer, while checking for any errors
 53 |         return resultCode;
 54 |         }
 55 |     else
 56 |         {
 57 |         return 4;														// Could not properly copy data ti I2C buffer, so treat as other error, see i2c_t3
 58 |         }
 59 |     }
 60 | 
 61 | uint32_t PN7150Interface::read(uint8_t rxBuffer[]) const
 62 |     {
 63 |     uint32_t bytesReceived;												// keeps track of how many bytes we actually received
 64 |     if (hasMessage())													// only try to read something if the PN7150 indicates it has something
 65 |         {
 66 |         // using 'Split mode' I2C read. See UM10936 section 3.5
 67 |         bytesReceived = Wire.requestFrom((int)I2Caddress, 3);			// first reading the header, as this contains how long the payload will be
 68 | 
 69 |         rxBuffer[0] = Wire.read();
 70 |         rxBuffer[1] = Wire.read();
 71 |         rxBuffer[2] = Wire.read();
 72 |         uint8_t payloadLength = rxBuffer[2];
 73 |         if (payloadLength > 0)
 74 |             {
 75 |             bytesReceived += Wire.requestFrom(I2Caddress, payloadLength);		// then reading the payload, if any
 76 |             uint32_t index = 3;
 77 |             while (index < bytesReceived)
 78 |                 {
 79 |                 rxBuffer[index] = Wire.read();
 80 |                 index++;
 81 |                 }
 82 |             }
 83 |         }
 84 |     else
 85 |         {
 86 |         bytesReceived = 0;
 87 |         }
 88 |     return bytesReceived;
 89 |     }
 90 | 
 91 | // void PN7150Interface::test001()
 92 | // // is the VEN signal being properly controlled ? Measure with a multimeter and verify the 2 second high + second low square wave
 93 | //     {
 94 | //     Serial.println("Test 001 Cycle ---- Start");
 95 | //     Serial.println("Driving VEN HIGH");
 96 | //     digitalWrite(VEN, HIGH);
 97 | //     delay(2000);
 98 | //     Serial.println("Driving VEN LOW");
 99 | //     digitalWrite(VEN, LOW);
100 | //     delay(2000);
101 | //     Serial.println("Test 001 Cycle ---- End");
102 | //     }
103 | 
104 | // void PN7150Interface::test002()
105 | // // is the IRQ signal being properly read ? Remove the NFC module and put a resistor between IRQ and VEN to serve as a loopback observe result in Serial monitor
106 | //     {
107 | //     Serial.println("Test 002 Cycle ---- Start");
108 | //     Serial.println("Driving VEN HIGH");
109 | //     digitalWrite(VEN, HIGH);
110 | //     delay(10);
111 | //     if (hasMessage())
112 | //         {
113 | //         Serial.println("reading IRQ HIGH - ok");
114 | //         }
115 | //     else
116 | //         {
117 | //         Serial.println("reading IRQ LOW - error");
118 | //         }
119 | //     delay(500);
120 | //     Serial.println("Driving VEN LOW");
121 | //     digitalWrite(VEN, LOW);
122 | //     delay(10);
123 | //     if (hasMessage())
124 | //         {
125 | //         Serial.println("reading IRQ HIGH - error");
126 | //         }
127 | //     else
128 | //         {
129 | //         Serial.println("reading IRQ LOW - ok");
130 | //         }
131 | //     delay(500);
132 | //     Serial.println("Test 002 Cycle ---- End");
133 | //     }
134 | 
135 | // void PN7150Interface::test003()
136 | //     {
137 | //     // This will write data to the I2C. Monitor with a scope the I2C signals on the bus...
138 | //     Serial.println("Test 003 Cycle ---- Start");
139 | //     uint8_t tmpBuffer[] = { 0x00, 0xFF, 0xAA, 0x55 };
140 | //     uint8_t resultCode;
141 | //     resultCode = write(tmpBuffer, 4);
142 | //     switch (resultCode)
143 | //         {
144 | //         case 0:
145 | //             Serial.println("I2C Write succesfull");
146 | //             break;
147 | 
148 | //         case 1:
149 | //             Serial.println("I2C Write fail : data too long");
150 | //             break;
151 | 
152 | //         case 2:
153 | //             Serial.println("I2C Write fail : address NACK");
154 | //             break;
155 | 
156 | //         case 3:
157 | //             Serial.println("I2C Write fail : data NACK");
158 | //             break;
159 | 
160 | //         default:
161 | //             Serial.println("I2C Other Error");
162 | //         }
163 | 
164 | //     Serial.println("Test 003 Cycle ---- End");
165 | //     delay(500);
166 | //     }
167 | 
168 | // void PN7150Interface::test004()
169 | //     {
170 | // 	// This will write data to the I2C, and then Check if the PN7150 indicates it wants to answer..
171 | // 	Serial.println("Test 004 Cycle ---- Start");
172 | 
173 | // 	// Reset the PN7150, otherwise you can only run this test once..
174 | // 	digitalWrite(VEN, LOW);									// drive VEN LOW for at least 0.5 ms after power came up : datasheet table 16.2.3
175 | // 	delay(100);
176 | // 	digitalWrite(VEN, HIGH);									// then VEN HIGH again, and wait for 2.5 ms for the device to boot and allow communication
177 | // 	delay(50);
178 | 
179 | //     if (hasMessage())
180 | //         {
181 | //         Serial.println("IRQ was already HIGH before sending - error");
182 | //         }
183 | //     else
184 | //         {
185 | //         Serial.println("IRQ LOW before sending - ok");
186 | //         }
187 | //     uint8_t tmpBuffer[] = { 0x20, 0x00, 0x01, 0x01 };
188 | //     write(tmpBuffer, 4);
189 | 
190 | //     delay(5); // How much delay do you need to check if there is an answer from the Device ? I checked this with a scope and the device responded 2.3ms after the end of the message
191 | 
192 | //     if (hasMessage())
193 | //         {
194 | //         Serial.println("IRQ HIGH after sending - ok");
195 | //         }
196 | //     else
197 | //         {
198 | //         Serial.println("IRQ still LOW after sending - error");
199 | //         }
200 | 
201 | //     Serial.println("Test 004 Cycle ---- End");
202 | //     }
203 | 
204 | // void PN7150Interface::test005()
205 | //     {
206 | //     // This will write CORE_REST_CMD to the PN7150, and then Check if we receive CORE_RESET_RSP back.. See NCI specification V1.0 section 4.1
207 | //     // I am using the reset behaviour of the NCI to test send and response here, as it is otherwise difficult to trigger a read
208 | //     Serial.println("Test 005 Cycle ---- Start");
209 | // 	// Reset the PN7150, otherwise you can only run this test once..
210 | // 	digitalWrite(VEN, LOW);									// drive VEN LOW for at least 0.5 ms after power came up : datasheet table 16.2.3
211 | // 	delay(100);
212 | // 	digitalWrite(VEN, HIGH);									// then VEN HIGH again, and wait for 2.5 ms for the device to boot and allow communication
213 | // 	delay(50);
214 | 
215 | // 	uint8_t tmpBuffer[] = { 0x20, 0x00, 0x01, 0x01 };
216 | //     write(tmpBuffer, 4);
217 | 
218 | //     delay(5); // How much delay do you need to check if there is an answer from the Device ?
219 | 
220 | //     uint8_t tmpRxBuffer[260];
221 | //     uint32_t nmbrBytesReceived;
222 | 
223 | //     nmbrBytesReceived = read(tmpRxBuffer);
224 | 
225 | //     if (6 == nmbrBytesReceived)
226 | //         {
227 | //         Serial.print(nmbrBytesReceived);
228 | //         Serial.println(" bytes received, 6 bytes expected - ok");
229 | //         if (0x40 == tmpRxBuffer[0])
230 | //             {
231 | //             Serial.println("byte[0] = 0x40 : MT = Control Packet Response, PBF = 0, GID = Core = 0 - ok");
232 | //             }
233 | //         else
234 | //             {
235 | //             Serial.print("byte[0] = ");
236 | //             Serial.print(tmpRxBuffer[0]);
237 | //             Serial.println(" - error");
238 | //             }
239 | 
240 | //         if (0x00 == tmpRxBuffer[1])
241 | //             {
242 | //             Serial.println("byte[1] = 0x00 : OID = CORE_RESET_RSP - ok");
243 | //             }
244 | //         else
245 | //             {
246 | //             Serial.print("byte[1] = ");
247 | //             Serial.print(tmpRxBuffer[1]);
248 | //             Serial.println(" - error");
249 | //             }
250 | 
251 | //         if (0x03 == tmpRxBuffer[2])
252 | //             {
253 | //             Serial.println("byte[2] = 0x03 : payload length = 3 bytes - ok");
254 | //             }
255 | //         else
256 | //             {
257 | //             Serial.print("byte[2] = ");
258 | //             Serial.print(tmpRxBuffer[2]);
259 | //             Serial.println(" - error");
260 | //             }
261 | 
262 | //         Serial.print("byte[3] = Status = ");							// See NCI V1.0 Specification Table 94. 0x00 = Status_OK
263 | //         Serial.print(tmpRxBuffer[3]);
264 | //         Serial.println("");
265 | 
266 | //         Serial.print("byte[4] = NCI Version = ");						// See NCI V1.0 Specification Table 6. 0x17 = V1.7 ?? Not sure about this as I don't have official specs from NCI as they are quite expensive
267 | //         Serial.print(tmpRxBuffer[4]);
268 | //         Serial.println("");
269 | 
270 | //         Serial.print("byte[5] = Configuration Status = ");				// See NCI V1.0 Specification Table 7. 0x01 = NCI RF Configuration has been reset
271 | //         Serial.print(tmpRxBuffer[5]);
272 | //         Serial.println("");
273 | //         }
274 | //     else
275 | //         {
276 | //         Serial.print(nmbrBytesReceived);
277 | //         Serial.println(" bytes received, 6 bytes expected - error");
278 | //         }
279 | 
280 | //     Serial.println("Test 005 Cycle ---- End");
281 | //     delay(1000);
282 | //     }


--------------------------------------------------------------------------------
/src/NCI.h:
--------------------------------------------------------------------------------
  1 | #pragma once
  2 | 
  3 | // SPDX-License-Identifier: CC-BY-NC-SA-4.0 OR GPL-3.0-or-later
  4 | // #############################################################################
  5 | // ###                                                                       ###
  6 | // ### NXP PN7150 Driver                                                     ###
  7 | // ###                                                                       ###
  8 | // ### https://github.com/Strooom/PN7150                                     ###
  9 | // ### Author(s) : Pascal Roobrouck - @strooom                               ###
 10 | // ### License : CC-BY-NC-SA-4.0 OR GPL-3.0-or-later                         ###
 11 | // ###                                                                       ###
 12 | // ### Credits : Thomas Buhot, for his PN7120 library, the predecessor of    ###
 13 | // ### the PN7150. Due to the NFC Specs not being available for free, I used ###
 14 | // ### his library to reverse-engineer some of the missing information links ###
 15 | // ###                                                                       ###
 16 | // #############################################################################
 17 | //
 18 | // Summary :
 19 | //   This library implements the NFC Controller Interface (NCI), which is a communication protocol between NFC hardware and a controlling Device Host
 20 | //   It was written as part of a NXP PN7150 driver
 21 | //
 22 | //   Initially I want to simply read NFC cards Unique IDs, using the PN7150, so the NCI implementation will only support a subset needed for this purpose
 23 | //   Upon request, the library may be extended to support more advanced use of the PN7150
 24 | //
 25 | 
 26 | #include <stdint.h>                 // Gives us access to uint8_t types etc
 27 | #include "tag.h"                    //
 28 | #include "PN7150Interface.h"        // NCI protocol runs over a hardware interface.
 29 | 
 30 | // ---------------------------------------------------------------------
 31 | // NCI Packet Header Definitions. NCI Specification V1.0 - section 3.4.1
 32 | // ---------------------------------------------------------------------
 33 | 
 34 | #define MaxPayloadSize 255        // See NCI specification V1.0, section 3.1
 35 | #define MsgHeaderSize 3
 36 | 
 37 | #define MsgTypeData 0x00
 38 | #define MsgTypeCommand 0x20
 39 | #define MsgTypeResponse 0x40
 40 | #define MsgTypeNotification 0x60
 41 | 
 42 | // Packet Boundary Flag
 43 | #define PacketBoundaryFlagLastSegment 0x00
 44 | #define PacketBoundaryFlagNotLastSegment 0x10
 45 | 
 46 | // ---------------------------------------------------------------
 47 | // NCI GID and OID Definitions. NCI Specification V1.0 - Table 102
 48 | // ---------------------------------------------------------------
 49 | // Group Identifier (GID)
 50 | #define GroupIdCore 0x00
 51 | #define GroupIdRfManagement 0x01
 52 | #define GroupIdNfceeManagement 0x02
 53 | #define GroupIdProprietary 0x0F
 54 | 
 55 | // OpCode Identifier (OID)
 56 | #define CORE_RESET_CMD 0x00
 57 | #define CORE_RESET_RSP 0x00
 58 | #define CORE_RESET_NTF 0x00
 59 | 
 60 | #define CORE_INIT_CMD 0x01
 61 | #define CORE_INIT_RSP 0x01
 62 | 
 63 | #define CORE_SET_CONFIG_CMD 0x02
 64 | #define CORE_SET_CONFIG_RSP 0x02
 65 | 
 66 | #define CORE_GET_CONFIG_CMD 0x03
 67 | #define CORE_GET_CONFIG_RSP 0x03
 68 | 
 69 | #define CORE_CONN_CREATE_CMD 0x04
 70 | #define CORE_CONN_CREATE_RSP 0x04
 71 | 
 72 | #define CORE_CONN_CLOSE_CMD 0x05
 73 | #define CORE_CONN_CLOSE_RSP 0x05
 74 | 
 75 | #define CORE_CONN_CREDITS_NTF 0x06
 76 | #define CORE_GENERIC_ERROR_NTF 0x07
 77 | #define CORE_INTERFACE_ERROR_NTF 0x08
 78 | 
 79 | // 1001b -1111b RFU
 80 | 
 81 | #define RF_DISCOVER_MAP_CMD 0x00
 82 | #define RF_DISCOVER_MAP_RSP 0x00
 83 | 
 84 | #define RF_SET_LISTEN_MODE_ROUTING_CMD 0x01
 85 | #define RF_SET_LISTEN_MODE_ROUTING_RSP 0x01
 86 | 
 87 | #define RF_GET_LISTEN_MODE_ROUTING_CMD 0x02
 88 | #define RF_GET_LISTEN_MODE_ROUTING_RSP 0x02
 89 | #define RF_GET_LISTEN_MODE_ROUTING_NTF 0x02
 90 | 
 91 | #define RF_DISCOVER_CMD 0x03
 92 | #define RF_DISCOVER_RSP 0x03
 93 | #define RF_DISCOVER_NTF 0x03
 94 | 
 95 | #define RF_DISCOVER_SELECT_CMD 0x04
 96 | #define RF_DISCOVER_SELECT_RSP 0x04
 97 | 
 98 | #define RF_INTF_ACTIVATED_NTF 0x05
 99 | 
100 | #define RF_DEACTIVATE_CMD 0x06
101 | #define RF_DEACTIVATE_RSP 0x06
102 | #define RF_DEACTIVATE_NTF 0x06
103 | 
104 | #define RF_FIELD_INFO_NTF 0x07
105 | 
106 | #define RF_T3T_POLLING_CMD 0x08
107 | #define RF_T3T_POLLING_RSP 0x08
108 | #define RF_T3T_POLLING_NTF 0x08
109 | #define RF_NFCEE_ACTION_NTF 0x09
110 | #define RF_NFCEE_DISCOVERY_REQ_NTF 0x0A
111 | #define RF_PARAMETER_UPDATE_CMD 0x0B
112 | #define RF_PARAMETER_UPDATE_RSP 0x0B
113 | // 1100b -  1111b RFU
114 | 
115 | #define NFCEE_DISCOVER_CMD 0x00
116 | #define NFCEE_DISCOVER_RSP 0x00
117 | #define NFCEE_DISCOVER_NTF 0x00
118 | #define NFCEE_MODE_SET_CMD 0x01
119 | #define NFCEE_MODE_SET_RSP 0x01
120 | // 0010b - 1111b RFU
121 | 
122 | #define NCI_PROPRIETARY_ACT_CMD 0x02        // See PN7150 Datasheet, section 5.4
123 | #define NCI_PROPRIETARY_ACT_RSP 0x02        // See PN7150 Datasheet, section 5.4, Table 23 and 24
124 | 
125 | #define ResetKeepConfig 0x00
126 | #define ResetClearConfig 0x01
127 | 
128 | // ---------------------------------------------------
129 | // NCI Status Codes. NCI Specification V1.0 - Table 94
130 | // ---------------------------------------------------
131 | 
132 | // Generic Status Codes
133 | #define STATUS_OK 0x00
134 | #define STATUS_REJECTED 0x01
135 | #define STATUS_RF_FRAME_CORRUPTED 0x02
136 | #define STATUS_FAILED 0x03
137 | #define STATUS_NOT_INITIALIZED 0x04
138 | #define STATUS_SYNTAX_ERROR 0x05
139 | #define STATUS_SEMANTIC_ERROR 0x06
140 | // 0x07 � 0x08 RFU
141 | #define STATUS_INVALID_PARAM 0x09
142 | #define STATUS_MESSAGE_SIZE_EXCEEDED 0x0A
143 | // 0x0B - 0x9F RFU
144 | 
145 | // RF Discovery Specific Status Codes
146 | #define DISCOVERY_ALREADY_STARTED 0xA0
147 | #define DISCOVERY_TARGET_ACTIVATION_FAILED 0xA1
148 | #define DISCOVERY_TEAR_DOWN 0xA2
149 | // 0xA3 - 0xAF RFU
150 | 
151 | // RF Interface Specific Status Codes
152 | #define RF_TRANSMISSION_ERROR 0xB0
153 | #define RF_PROTOCOL_ERROR 0xB1
154 | #define RF_TIMEOUT_ERROR 0xB2
155 | // 0xB3 - 0xBF RFU
156 | 
157 | // NFCEE Interface Specific Status Codes
158 | #define NFCEE_INTERFACE_ACTIVATION_FAILED 0xC0
159 | #define NFCEE_TRANSMISSION_ERROR 0xC1
160 | #define NFCEE_PROTOCOL_ERROR 0xC2
161 | #define NFCEE_TIMEOUT_ERROR 0xC3
162 | // 0xC4 - 0xDF RFU
163 | 
164 | // Proprietary Status Codes : 0xE0 - 0xFF
165 | 
166 | // ------------------------------------------------------
167 | // NCI RF Technologies. NCI Specification V1.0 - Table 95
168 | // ------------------------------------------------------
169 | 
170 | #define NFC_RF_TECHNOLOGY_A 0x00
171 | #define NFC_RF_TECHNOLOGY_B 0x01
172 | #define NFC_RF_TECHNOLOGY_F 0x02
173 | #define NFC_RF_TECHNOLOGY_15693 0x03
174 | // 0x04 � 0x7F RFU
175 | // 0x80 - 0xFE For proprietary use
176 | // 0xFF RFU
177 | 
178 | // -------------------------------------------------------------
179 | // NCI RF Technology and Mode. NCI Specification V1.0 - Table 96
180 | // -------------------------------------------------------------
181 | 
182 | #define NFC_A_PASSIVE_POLL_MODE 0x00
183 | #define NFC_B_PASSIVE_POLL_MODE 0x01
184 | #define NFC_F_PASSIVE_POLL_MODE 0x02
185 | #define NFC_A_ACTIVE_POLL_MODE 0x03
186 | // RFU	0x04
187 | #define NFC_F_ACTIVE_POLL_MODE 0x05
188 | #define NFC_15693_PASSIVE_POLL_MODE 0x06
189 | // 0x07 � 0x6F RFU
190 | // 0x70 � 0x7F Reserved for Proprietary Technologies in Poll Mode
191 | #define NFC_A_PASSIVE_LISTEN_MODE 0x80
192 | #define NFC_B_PASSIVE_LISTEN_MODE 0x81
193 | #define NFC_F_PASSIVE_LISTEN_MODE 0x82
194 | #define NFC_A_ACTIVE_LISTEN_MODE 0x83
195 | // RFU	0x84
196 | #define NFC_F_ACTIVE_LISTEN_MODE 0x85
197 | #define NFC_15693_PASSIVE_LISTEN_MODE 0x86
198 | // 0x87 � 0xEF RFU
199 | // 0xF0 � 0xFF Reserved for Proprietary Technologies in Listen Mode
200 | 
201 | // ---------------------------------------------------
202 | // NCI RF Protocols. NCI Specification V1.0 - Table 98
203 | // ---------------------------------------------------
204 | 
205 | #define PROTOCOL_UNDETERMINED 0x00
206 | #define PROTOCOL_T1T 0x01
207 | #define PROTOCOL_T2T 0x02
208 | #define PROTOCOL_T3T 0x03
209 | #define PROTOCOL_ISO_DEP 0x04
210 | #define PROTOCOL_NFC_DEP 0x05
211 | // 0x06 � 0x7F RFU
212 | // 0x80-0xFE For proprietary use
213 | // 0xFF RFU
214 | 
215 | // -----------------------------------------------------
216 | // NCI RF Interfacess. NCI Specification V1.0 - Table 99
217 | // -----------------------------------------------------
218 | 
219 | #define NFCEE_Direct_RF_Interface 0x00
220 | #define Frame_RF_interface 0x01
221 | #define ISO_DEP_RF_interface 0x02
222 | #define NFC_DEP_RF_interface 0x03
223 | // 0x04 � 0x7F RFU
224 | // 0x80 - 0xFE For proprietary use
225 | // 0xFF RFU
226 | 
227 | // ---------------------------------------------------------------
228 | // NFCEE Protocol / Interfaces. NCI Specification V1.0 - Table 100
229 | // ---------------------------------------------------------------
230 | 
231 | #define APDU 0x00
232 | #define HCI Access 0x01
233 | #define Type 3 Tag Command Set 0x02
234 | #define Transparent 0x03
235 | // 0x04 - 0x7F RFU
236 | // 0x80 - 0xFE For proprietary use
237 | // 0xFF RFU
238 | 
239 | // --------------------------------------------
240 | // Bit Rates. NCI Specification V1.0 - Table 97
241 | // --------------------------------------------
242 | 
243 | #define NFC_BIT_RATE_106 0x00
244 | #define NFC_BIT_RATE_212 0x01
245 | #define NFC_BIT_RATE_424 0x02
246 | #define NFC_BIT_RATE_848 0x03
247 | #define NFC_BIT_RATE_1695 0x04
248 | #define NFC_BIT_RATE_3390 0x05
249 | #define NFC_BIT_RATE_6780 0x06
250 | // 0x07 � 0x7F RFU
251 | // 0x80 - 0xFE For proprietary use
252 | // 0xFF RFU
253 | 
254 | // ----------------------------------------------------------------------
255 | // Dectivation Types for RF_DEACTIVATE_ NCI Specification V1.0 - Table 63
256 | // ----------------------------------------------------------------------
257 | 
258 | enum class NciRfDeAcivationMode : uint8_t {
259 |     IdleMode     = 0x00,
260 |     SleepMode    = 0x01,
261 |     Sleep_AFMode = 0x02,
262 |     Discovery    = 0x03
263 |     // 0x04 � 0xFF RFU
264 | };
265 | 
266 | // ----------------------------------------------------------------------
267 | // Dectivation Reason RF_DEACTIVATE_NTF NCI Specification V1.0 - Table 64
268 | // ----------------------------------------------------------------------
269 | 
270 | #define DH_Request 0x00
271 | #define Endpoint_Request 0x01
272 | #define RF_Link_Loss 0x02
273 | #define NFC_B_Bad_AFI 0x03
274 | // 0x04 � 0xFF RFU
275 | 
276 | /* Discovery Types/Detected Technology and Mode */
277 | #define NCI_DISCOVERY_TYPE_POLL_A 0x00
278 | #define NCI_DISCOVERY_TYPE_POLL_B 0x01
279 | #define NCI_DISCOVERY_TYPE_POLL_F 0x02
280 | #define NCI_DISCOVERY_TYPE_POLL_A_ACTIVE 0x03
281 | #define NCI_DISCOVERY_TYPE_POLL_F_ACTIVE 0x05
282 | #define NCI_DISCOVERY_TYPE_POLL_ISO15693 0x06
283 | 
284 | enum class notificationType : uint8_t {
285 |     lastNotification          = 0x00,
286 |     lastNotificationNfccLimit = 0x01,
287 |     moreNotification          = 0x02
288 |     // 	3 - 255 RFU
289 | };
290 | 
291 | // ------------------------------------------------------------------------------------------
292 | // NFC Defines 3 types of applications. The NP7150 can operate them all in parallel if needed
293 | // ------------------------------------------------------------------------------------------
294 | 
295 | // enum class NciApplicationMode : uint8_t
296 | //     {
297 | //     None = 0x00,
298 | //     CardReadWrite = 0x01,			// Using the PN7150 to simply read NFC or RFID cards
299 | //     CardEmulate = 0x02,				// For Future Use, not yet implemented
300 | //     PeerToPeer = 0x04				// For Future Use, not yet implemented
301 | //     };
302 | 
303 | // enum class CardType : uint8_t
304 | //     {
305 | //     T1T,
306 | //     T2T,
307 | //     T3T,
308 | //     ISO_DEP,
309 | //     NFC_DEP
310 | //     };
311 | 
312 | // ------------------------------------------------------------------------------------------
313 | // NFC Requires the device to behave according to a certain State Machine.
314 | // Furthermore the NCI protocol consists of Commands, to be followed by Responses
315 | // All this behaviour is implemented with a Finite State Machine, with following states
316 | // ------------------------------------------------------------------------------------------
317 | 
318 | enum class NciState : uint8_t
319 | // Note :	Rfc means "Ready For Command" : a state where you would (typically) send an NCI command from the DH to the NFC
320 | //			Wfr means "Waiting For Response" : a state where you would wait for a response from the NFC to the DH
321 | //			Wfn means "Waiting For Notification" : a state where you would wait for a notification from the NFC to the DH
322 | {
323 |     HwResetRfc,                     // you start in this state after a hardware reset of the PN7150, then you send the CORE_RESET_CMD
324 |     HwResetWfr,                     // waiting for CORE_RESET_RSP
325 |     SwResetRfc,                     // send CORE_INIT_CMD
326 |     SwResetWfr,                     // waiting for CORE_INIT_RSP
327 |     EnableCustomCommandsRfc,        // Enabling PN7150-extensions
328 |     EnableCustomCommandsWfr,        // waiting for response/confirmation
329 |     RfIdleCmd,                      // Core initialized, now waiting for RF configuration commands
330 |     RfIdleWfr,
331 |     RfGoToDiscoveryWfr,
332 |     RfDiscovery,                    // polling / detecting cards/tags
333 |     RfWaitForAllDiscoveries,        // busy enumerating multiple cards/tags being detected
334 |     RfWaitForHostSelect,            // done detecting multiple cards/tags, waiting for the DH to select one
335 |     RfPollActive,                   // detected 1 card/tag, and activated it for reading/writing
336 | 
337 |     RfDeActivate1Wfr,        // waiting for deactivation response, no notification will come (dactivation in RfWaitForHostSelect)
338 |     RfDeActivate2Wfr,        // waiting for deactivation response, additionally a notification will come (deactivation in RfPollActive)
339 |     RfDeActivate2Wfn,        // waiting for deactivation notifiation
340 |     Error,
341 |     End
342 | };
343 | 
344 | enum class NciError : uint8_t {
345 |     responseNOK,            // we received a response with somethin wrong in it, eg Status_NOK
346 |     responseTimeout,        // we did not receive a response in time
347 |     none
348 | };
349 | 
350 | enum class TagsPresentStatus : uint8_t {
351 |     unknown,
352 |     noTagsPresent,
353 |     newTagPresent,
354 |     oldTagPresent,
355 |     multipleTagsPresent
356 | };
357 | 
358 | class NCI {
359 |   public:
360 |     NCI(PN7150Interface &theHardwareInterface);            // Constructor, with mode default set to CardReadwrite
361 |     void initialize();                                     // See NCI specification V1.0, section 4.1 & 4.2
362 |     void run();                                            // runs the NCI stateMachine
363 |     void activate();                                       // moves the StateMachine from Idle to Discover and starts the polling
364 |     void deActivate(NciRfDeAcivationMode theMode);         // moves the StateMachine from PollActive or WaitingForHostSelect back into Idle
365 |     NciState getState() const;                             // find out in which state the NCI stateMachine is
366 |     TagsPresentStatus getTagsPresentStatus() const;        // read-only get function for the (private) property
367 |     uint8_t getNmbrOfTags() const;
368 |     bool newTagPresent() const;
369 |     Tag *getTag(uint8_t index);        // TODO : improve this with 'const' so the Tag properties are read-only
370 | 
371 |   private:
372 |     PN7150Interface &theHardwareInterface;        // reference to the object handling the hardware interface
373 | 
374 |     NciState theState;                      // keeps track of the state of the NCI stateMachine - FSM
375 |     TagsPresentStatus theTagsStatus;        // how many Tag/Cards are currently present
376 | 
377 |     unsigned long timeOut;                 // keeps track of time-outs when waiting for responses from the NFC device
378 |     unsigned long timeOutStartTime;        // keeps track of time-outs when waiting for responses from the NFC device
379 | 
380 |     uint8_t rxBuffer[MaxPayloadSize + MsgHeaderSize];        // buffer where we store bytes received until they form a complete message
381 |     uint32_t rxMessageLength;                                // length of the last message received. As these are not 0x00 terminated, we need to remember the length
382 |     uint8_t txBuffer[MaxPayloadSize + MsgHeaderSize];        // buffer where we store the message to be transmitted
383 | 
384 |     void sendMessage(uint8_t messageType, uint8_t groupId, uint8_t opcodeId, uint8_t payloadData[], uint8_t payloadLength);
385 |     void sendMessage(uint8_t messageType, uint8_t groupId, uint8_t opcodeId);                // Variant for msg with no payload
386 |     void getMessage();                                                                       // read message from I2C into rxBuffer
387 |     bool isMessageType(uint8_t messageType, uint8_t groupId, uint8_t opcodeId) const;        // Is the msg in the rxBuffer of this type ?
388 |     void setTimeOut(unsigned long);                                                          // set a timeOut for an expected next event, eg reception of Response after sending a Command
389 |     bool isTimeOut() const;                                                                  // Chech if we have exceeded the timeOut
390 | 
391 |     static constexpr unsigned long scanPeriod = 1000;        // lenght of a scan for tags cycle, in milliseconds. Note : setting this to very short times, eg. < 100 ms will not work, because the NFC discovery loop has a certain minumum constrained by the HW protocols
392 |     static constexpr uint8_t maxNmbrTags      = 3;           // maximum number of (simultaneously present) tags we can keep track of. PN7150 is limited to 3
393 |     Tag theTags[maxNmbrTags];                                // array to store the data of a number of currently present tags. When uniqueIdLenght == 0 it means invalid data in this position of the array
394 |     uint8_t nmbrOfTags = 0;                                  // how many tags are actually in the array
395 |     void saveTag(uint8_t msgType);
396 | };
397 | 
398 | 


--------------------------------------------------------------------------------
/src/NCI.cpp:
--------------------------------------------------------------------------------
  1 | #include "nci.h"
  2 | 
  3 | NCI::NCI(PN7150Interface& aHardwareInterface) : theHardwareInterface(aHardwareInterface), theState(NciState::HwResetRfc), theTagsStatus(TagsPresentStatus::unknown) {
  4 | }
  5 | 
  6 | void NCI::initialize() {
  7 |     theHardwareInterface.initialize();
  8 |     theState      = NciState::HwResetRfc;        // re-initializing the state, so we can re-initialize at anytime
  9 |     theTagsStatus = TagsPresentStatus::unknown;
 10 |     nmbrOfTags    = 0;
 11 | }
 12 | 
 13 | void NCI::run() {
 14 |     switch (theState) {
 15 |         case NciState::HwResetRfc:        // after Hardware reset / powerOn
 16 |         {
 17 |             uint8_t payloadData[] = {ResetKeepConfig};                                       // CORE_RESET-CMD with Keep Configuration
 18 |             sendMessage(MsgTypeCommand, GroupIdCore, CORE_RESET_CMD, payloadData, 1);        //
 19 |             setTimeOut(20);                                                                  // we should get a RESPONSE within 20 ms (it typically takes 2.3ms)
 20 |             theState = NciState::HwResetWfr;                                                 // move to next state, waiting for the matching Response
 21 |         } break;
 22 | 
 23 |         case NciState::HwResetWfr:
 24 |             if (theHardwareInterface.hasMessage()) {
 25 |                 getMessage();
 26 |                 bool isOk = (6 == rxMessageLength);                                                     // Does the received Msg have the correct lenght ?
 27 |                 isOk      = isOk && isMessageType(MsgTypeResponse, GroupIdCore, CORE_RESET_RSP);        // Is the received Msg the correct type ?
 28 |                 isOk      = isOk && (STATUS_OK == rxBuffer[3]);                                         // Is the received Status code Status_OK ?
 29 | 
 30 |                 if (isOk) {
 31 |                     theState = NciState::SwResetRfc;        // ..move to the next state
 32 |                 } else                                      // if not..
 33 |                 {
 34 |                     theState = NciState::Error;        // goto error state
 35 |                 }
 36 |             } else if (isTimeOut()) {
 37 |                 theState = NciState::Error;        // time out waiting for response..
 38 |             }
 39 |             break;
 40 | 
 41 |         case NciState::SwResetRfc: {
 42 |             sendMessage(MsgTypeCommand, GroupIdCore, CORE_INIT_CMD);        // CORE_INIT-CMD
 43 |             setTimeOut(20);                                                 // we should get a RESPONSE within 20 ms, typically it takes 0.5ms
 44 |             theState = NciState::SwResetWfr;                                // move to next state, waiting for response
 45 |         } break;
 46 | 
 47 |         case NciState::SwResetWfr:
 48 |             if (theHardwareInterface.hasMessage()) {
 49 |                 getMessage();
 50 |                 bool isOk = isMessageType(MsgTypeResponse, GroupIdCore, CORE_INIT_RSP);        // Is the received Msg the correct type ?
 51 | 
 52 |                 if (isOk) {
 53 |                     theState = NciState::EnableCustomCommandsRfc;        // ...move to the next state
 54 |                 } else                                                   // if not..
 55 |                 {
 56 |                     theState = NciState::Error;        // .. goto error state
 57 |                 }
 58 |             } else if (isTimeOut()) {
 59 |                 theState = NciState::Error;        // time out waiting for response..
 60 |             }
 61 |             break;
 62 | 
 63 |         case NciState::EnableCustomCommandsRfc:
 64 |             sendMessage(MsgTypeCommand, GroupIdProprietary, NCI_PROPRIETARY_ACT_CMD);        // Send NCI_PROPRIETARY_ACT_CMD to activate extra PN7150-NCI features
 65 |             setTimeOut(10);                                                                  // we should get a RESPONSE within 10 ms, typically it takes 0.5ms
 66 |             theState = NciState::EnableCustomCommandsWfr;                                    // move to next state, waiting for response
 67 |             break;
 68 | 
 69 |         case NciState::EnableCustomCommandsWfr:
 70 |             if (theHardwareInterface.hasMessage()) {
 71 |                 getMessage();
 72 |                 bool isOk = isMessageType(MsgTypeResponse, GroupIdProprietary, NCI_PROPRIETARY_ACT_RSP);        // Is the received Msg the correct type ?
 73 |                 isOk      = isOk && (STATUS_OK == rxBuffer[3]);                                                 // Is the received Status code Status_OK ?
 74 | 
 75 |                 if (isOk) {                                // if everything is OK...
 76 |                     theState = NciState::RfIdleCmd;        // ...move to the next state
 77 |                 } else {                                   // if not..
 78 |                     theState = NciState::Error;        // .. goto error state
 79 |                 }
 80 |             } else if (isTimeOut()) {
 81 |                 theState = NciState::Error;        // time out waiting for response..
 82 |             }
 83 |             break;
 84 | 
 85 |         case NciState::RfIdleCmd: {
 86 |             // After configuring, we are ready to go into Discovery, but we wait for the readerWriter application to give us this trigger
 87 |             // Or we can proceed into polling right away
 88 |             activate();
 89 |             // uint8_t payloadData[] = {4, NFC_A_PASSIVE_POLL_MODE, 0x01, NFC_B_PASSIVE_POLL_MODE, 0x01, NFC_F_PASSIVE_POLL_MODE, 0x01, NFC_15693_PASSIVE_POLL_MODE, 0x01};
 90 |             // sendMessage(MsgTypeCommand, GroupIdRfManagement, RF_DISCOVER_CMD, payloadData, 9);        //
 91 |             // setTimeOut(10);                                                                           // we should get a RESPONSE within 10 ms
 92 |             // theState = NciState::RfIdleWfr;                                                           // move to next state, waiting for Response
 93 |         } break;
 94 | 
 95 |         case NciState::RfIdleWfr:
 96 |             if (theHardwareInterface.hasMessage()) {
 97 |                 getMessage();
 98 |                 bool isOk = (4 == rxMessageLength);                                                              // Does the received Msg have the correct lenght ?
 99 |                 isOk      = isOk && isMessageType(MsgTypeResponse, GroupIdRfManagement, RF_DISCOVER_RSP);        // Is the received Msg the correct type ?
100 |                 isOk      = isOk && (STATUS_OK == rxBuffer[3]);                                                  // Is the received Status code Status_OK ?
101 |                 if (isOk)                                                                                        // if everything is OK...
102 |                 {
103 |                     theState = NciState::RfDiscovery;        // ...move to the next state
104 |                     setTimeOut(500);                         // set a timeout of 1 second. If it times out, it means no cards are present..
105 |                 } else                                       // if not..
106 |                 {
107 |                     theState = NciState::Error;        // .. goto error state
108 |                 }
109 |             } else if (isTimeOut()) {
110 |                 theState = NciState::Error;        // time out waiting for response..
111 |             }
112 |             break;
113 | 
114 |         case NciState::RfDiscovery:
115 |             // TODO : if we have no NTF here, it means no cards are present and we can delete them from the list...
116 |             // Here we don't check timeouts.. we can wait forever for a TAG/CARD to be presented..
117 |             if (theHardwareInterface.hasMessage()) {
118 |                 getMessage();
119 |                 if (isMessageType(MsgTypeNotification, GroupIdRfManagement, RF_INTF_ACTIVATED_NTF)) {
120 |                     // When a single tag/card is detected, the PN7150 will immediately activate it and send you this type of notification
121 |                     saveTag(RF_INTF_ACTIVATED_NTF);        // save properties of this Tag in the Tags array
122 |                     if (TagsPresentStatus::noTagsPresent == theTagsStatus) {
123 |                         theTagsStatus = TagsPresentStatus::newTagPresent;
124 |                     }
125 |                     theState = NciState::RfPollActive;        // move to PollActive, and wait there for further commands..
126 |                 } else if (isMessageType(MsgTypeNotification, GroupIdRfManagement, RF_DISCOVER_NTF)) {
127 |                     // When multiple tags/cards are detected, the PN7150 will notify them all and wait for the DH to select one
128 |                     // The first card will have NotificationType == 2 and move the stateMachine to WaitForAllDiscoveries.
129 |                     // More notifications will come in that state
130 |                     saveTag(RF_DISCOVER_NTF);        // save properties of this Tag in the Tags array
131 |                     setTimeOut(25);                  // we should get more Notifications ubt set a timeout so we don't wait forever
132 |                     theTagsStatus = TagsPresentStatus::multipleTagsPresent;
133 |                     theState      = NciState::RfWaitForAllDiscoveries;
134 |                 }
135 |             } else if (isTimeOut()) {
136 |                 theTagsStatus = TagsPresentStatus::noTagsPresent;        // this means no card has been detected for xxx millisecond, so we can conclude that no cards are present
137 |             }
138 | 
139 |             break;
140 | 
141 |         case NciState::RfWaitForAllDiscoveries:
142 |             if (theHardwareInterface.hasMessage()) {
143 |                 getMessage();
144 |                 if (isMessageType(MsgTypeNotification, GroupIdRfManagement, RF_DISCOVER_NTF)) {
145 |                     notificationType theNotificationType = (notificationType)rxBuffer[rxBuffer[6] + 7];        // notificationType comes in rxBuffer at the end, = 7 bytes + length of RF Technology Specific parameters which are in rxBuffer[6]
146 |                     switch (theNotificationType) {
147 |                         case notificationType::lastNotification:
148 |                         case notificationType::lastNotificationNfccLimit:
149 |                             saveTag(RF_DISCOVER_NTF);        // save properties of this Tag in the Tags array
150 |                             theState = NciState::RfWaitForHostSelect;
151 |                             break;
152 | 
153 |                         case notificationType::moreNotification:
154 |                             setTimeOut(25);                  // we should get more Notifications, so set a timeout so we don't wait forever
155 |                             saveTag(RF_DISCOVER_NTF);        // save properties of this Tag in the Tags array
156 |                             break;
157 | 
158 |                         default:
159 |                             break;
160 |                     }
161 |                 }
162 |             } else if (isTimeOut()) {
163 |                 theState = NciState::Error;        // We need a timeout here, in case the final RF_DISCOVER_NTF with Notification Type == 0 or 1 never comes...
164 |             }
165 |             break;
166 | 
167 |         case NciState::RfWaitForHostSelect:
168 |             // Multiple cards are present. We could select one and move into RfPollActive
169 |             deActivate(NciRfDeAcivationMode::IdleMode);        //
170 |             break;
171 | 
172 |         case NciState::RfPollActive:
173 |             // A card is present, so we can read/write data to it. We could also receive a notification that the card has been removed..
174 |             deActivate(NciRfDeAcivationMode::IdleMode);        //
175 |             break;
176 | 
177 |         case NciState::RfDeActivate1Wfr:
178 |             if (theHardwareInterface.hasMessage()) {
179 |                 getMessage();
180 |                 if (isMessageType(MsgTypeResponse, GroupIdRfManagement, RF_DEACTIVATE_RSP)) {
181 |                     theState = NciState::RfIdleCmd;
182 |                 } else {
183 |                 }
184 |             } else if (isTimeOut()) {
185 |                 theState = NciState::Error;        // We need a timeout here, in case the RF_DEACTIVATE_RSP never comes...
186 |             }
187 |             break;
188 | 
189 |         case NciState::RfDeActivate2Wfr:
190 |             if (theHardwareInterface.hasMessage()) {
191 |                 getMessage();
192 |                 if (isMessageType(MsgTypeResponse, GroupIdRfManagement, RF_DEACTIVATE_RSP)) {
193 |                     setTimeOut(10);
194 |                     theState = NciState::RfDeActivate2Wfn;
195 |                 } else {
196 |                 }
197 |             } else if (isTimeOut()) {
198 |                 theState = NciState::Error;        // We need a timeout here, in case the RF_DEACTIVATE_RSP never comes...
199 |             }
200 |             break;
201 | 
202 |         case NciState::RfDeActivate2Wfn:
203 |             if (theHardwareInterface.hasMessage()) {
204 |                 getMessage();
205 |                 if (isMessageType(MsgTypeNotification, GroupIdRfManagement, RF_DEACTIVATE_NTF)) {
206 |                     theState = NciState::RfIdleCmd;
207 |                 } else {
208 |                 }
209 |             } else if (isTimeOut()) {
210 |                 theState = NciState::Error;        // We need a timeout here, in case the RF_DEACTIVATE_RSP never comes...
211 |             }
212 |             break;
213 | 
214 |         case NciState::Error:
215 |             // Something went wrong, and we made an emergency landing by moving to this state...
216 |             // To get out of it, the parent application can call initialize(), or we could decide to do that ourselves, maybe after some time-out
217 |             initialize();
218 |             break;
219 | 
220 |         default:
221 |             break;
222 |     }
223 | }
224 | 
225 | void NCI::activate() {
226 |     NciState tmpState = getState();
227 |     if (tmpState == NciState::RfIdleCmd) {
228 |         uint8_t payloadData[] = {4, NFC_A_PASSIVE_POLL_MODE, 0x01, NFC_B_PASSIVE_POLL_MODE, 0x01, NFC_F_PASSIVE_POLL_MODE, 0x01, NFC_15693_PASSIVE_POLL_MODE, 0x01};
229 |         // TODO : instead of setting a fixed scanning for these 4 types, we should pass the to be scanned for types as parameters from the ReaderWriter... https://github.com/Strooom/PN7150/issues/1
230 |         sendMessage(MsgTypeCommand, GroupIdRfManagement, RF_DISCOVER_CMD, payloadData, 9);        //
231 |         setTimeOut(10);                                                                           // we should get a RESPONSE within 10 ms
232 |         theState = NciState::RfIdleWfr;                                                           // move to next state, waiting for Response
233 |     } else {
234 |         // Error : we can only activate polling when in Idle...
235 |     }
236 | }
237 | 
238 | void NCI::deActivate(NciRfDeAcivationMode theMode) {
239 |     nmbrOfTags        = 0;
240 |     NciState tmpState = getState();
241 |     switch (tmpState) {
242 |         case NciState::RfWaitForHostSelect: {
243 |             uint8_t payloadData[] = {(uint8_t)NciRfDeAcivationMode::IdleMode};                          // in RfWaitForHostSelect, the deactivation type is ignored by the NFCC
244 |             sendMessage(MsgTypeCommand, GroupIdRfManagement, RF_DEACTIVATE_CMD, payloadData, 1);        //
245 |             setTimeOut(10);                                                                             // we should get a RESPONSE within 10 ms
246 |             theState = NciState::RfDeActivate1Wfr;                                                      // move to next state, waiting for response
247 |         } break;
248 | 
249 |         case NciState::RfPollActive: {
250 |             uint8_t payloadData[] = {(uint8_t)theMode};
251 |             sendMessage(MsgTypeCommand, GroupIdRfManagement, RF_DEACTIVATE_CMD, payloadData, 1);        //
252 |             setTimeOut(10);                                                                             // we should get a RESPONSE within 10 ms
253 |             theState = NciState::RfDeActivate2Wfr;                                                      // move to next state, waiting for response
254 |         } break;
255 | 
256 |         default:
257 |             break;
258 |     }
259 | }
260 | 
261 | NciState NCI::getState() const {
262 |     return theState;
263 | }
264 | 
265 | TagsPresentStatus NCI::getTagsPresentStatus() const {
266 |     return theTagsStatus;
267 | }
268 | 
269 | uint8_t NCI::getNmbrOfTags() const {
270 |     return nmbrOfTags;
271 | }
272 | 
273 | Tag* NCI::getTag(uint8_t index) {
274 |     theTagsStatus = TagsPresentStatus::oldTagPresent;        // after reading the Tag data, we consider it no longer a new tag
275 |     return &theTags[index];
276 | }
277 | 
278 | void NCI::sendMessage(uint8_t messageType, uint8_t groupId, uint8_t opcodeId) {
279 |     txBuffer[0] = (messageType | groupId) & 0xEF;         // put messageType and groupId in first byte, Packet Boundary Flag is always 0
280 |     txBuffer[1] = opcodeId & 0x3F;                        // put opcodeId in second byte, clear Reserved for Future Use (RFU) bits
281 |     txBuffer[2] = 0x00;                                   // payloadLength goes in third byte
282 |     (void)theHardwareInterface.write(txBuffer, 3);        // TODO :  could make this more robust by checking the return value and go into error is write did not succees
283 | }
284 | 
285 | void NCI::sendMessage(uint8_t messageType, uint8_t groupId, uint8_t opcodeId, uint8_t payloadData[], uint8_t payloadLength) {
286 |     txBuffer[0] = (messageType | groupId) & 0xEF;                   // put messageType and groupId in first byte, Packet Boundary Flag is always 0
287 |     txBuffer[1] = opcodeId & 0x3F;                                  // put opcodeId in second byte, clear Reserved for Future Use (RFU) bits
288 |     txBuffer[2] = payloadLength;                                    // payloadLength goes in third byte
289 |     for (uint32_t index = 0; index < payloadLength; index++)        // copy the payload
290 |     {
291 |         txBuffer[index + 3] = payloadData[index];
292 |     }
293 |     (void)theHardwareInterface.write(txBuffer, 3 + payloadLength);        // TODO :  could make this more robust by checking the return value and go into error is write did not succees
294 | }
295 | 
296 | void NCI::getMessage() {
297 |     rxMessageLength = theHardwareInterface.read(rxBuffer);
298 | }
299 | 
300 | bool NCI::isMessageType(uint8_t messageType, uint8_t groupId, uint8_t opcodeId) const {
301 |     return (((messageType | groupId) & 0xEF) == rxBuffer[0]) && ((opcodeId & 0x3F) == rxBuffer[1]);
302 | }
303 | 
304 | bool NCI::isTimeOut() const {
305 |     return ((millis() - timeOutStartTime) >= timeOut);
306 | }
307 | 
308 | void NCI::setTimeOut(unsigned long theTimeOut) {
309 |     timeOutStartTime = millis();
310 |     timeOut          = theTimeOut;
311 | }
312 | 
313 | void NCI::saveTag(uint8_t msgType) {
314 |     // Store the properties of detected TAGs in the Tag array.
315 |     // Tag info can come in two different NCI messages : RF_DISCOVER_NTF and RF_INTF_ACTIVATED_NTF and the Tag properties are in slightly different location inside these messages
316 | 
317 |     if (nmbrOfTags < maxNmbrTags) {
318 |         uint8_t offSet;        // Offset in the NCI message where we can find the UniqueID
319 |         switch (msgType) {
320 |             case RF_INTF_ACTIVATED_NTF:
321 |                 offSet = 12;
322 |                 break;
323 | 
324 |             case RF_DISCOVER_NTF:
325 |                 offSet = 9;
326 |                 break;
327 | 
328 |             default:
329 |                 return;        // unknown type of msg sent here ?? we just ignore it..
330 |                 break;
331 |         }
332 | 
333 |         uint8_t NfcId1Length = rxBuffer[offSet];
334 |         if (NfcId1Length > 10) {
335 |             NfcId1Length = 10;        // limit the length to 10, so in case of whatever error we don't write beyond the boundaries of the array
336 |         }
337 |         uint8_t newTagIndex = nmbrOfTags;        // index to the array item where we will store the info
338 | 
339 |         theTags[newTagIndex].uniqueIdLength = NfcId1Length;           // copy the length of the unique ID, is 4, 7 or 10
340 |         for (uint8_t index = 0; index < NfcId1Length; index++)        // copy all bytes of the unique ID
341 |         {
342 |             theTags[newTagIndex].uniqueId[index] = rxBuffer[offSet + 1 + index];
343 |         }
344 |         theTags[newTagIndex].detectionTimestamp = millis();
345 | 
346 |         nmbrOfTags++;        // one more tag in the array now
347 |     }
348 | }
349 | 
350 | bool NCI::newTagPresent() const {        // returns true only if a new tag is present
351 |     return (TagsPresentStatus::newTagPresent == theTagsStatus);
352 | }


--------------------------------------------------------------------------------
/LICENSE-CC-BY-NC-SA-40.txt:
--------------------------------------------------------------------------------
  1 | Attribution-NonCommercial-ShareAlike 4.0 International
  2 | 
  3 | =======================================================================
  4 | 
  5 | Creative Commons Corporation ("Creative Commons") is not a law firm and
  6 | does not provide legal services or legal advice. Distribution of
  7 | Creative Commons public licenses does not create a lawyer-client or
  8 | other relationship. Creative Commons makes its licenses and related
  9 | information available on an "as-is" basis. Creative Commons gives no
 10 | warranties regarding its licenses, any material licensed under their
 11 | terms and conditions, or any related information. Creative Commons
 12 | disclaims all liability for damages resulting from their use to the
 13 | fullest extent possible.
 14 | 
 15 | Using Creative Commons Public Licenses
 16 | 
 17 | Creative Commons public licenses provide a standard set of terms and
 18 | conditions that creators and other rights holders may use to share
 19 | original works of authorship and other material subject to copyright
 20 | and certain other rights specified in the public license below. The
 21 | following considerations are for informational purposes only, are not
 22 | exhaustive, and do not form part of our licenses.
 23 | 
 24 |      Considerations for licensors: Our public licenses are
 25 |      intended for use by those authorized to give the public
 26 |      permission to use material in ways otherwise restricted by
 27 |      copyright and certain other rights. Our licenses are
 28 |      irrevocable. Licensors should read and understand the terms
 29 |      and conditions of the license they choose before applying it.
 30 |      Licensors should also secure all rights necessary before
 31 |      applying our licenses so that the public can reuse the
 32 |      material as expected. Licensors should clearly mark any
 33 |      material not subject to the license. This includes other CC-
 34 |      licensed material, or material used under an exception or
 35 |      limitation to copyright. More considerations for licensors:
 36 |     wiki.creativecommons.org/Considerations_for_licensors
 37 | 
 38 |      Considerations for the public: By using one of our public
 39 |      licenses, a licensor grants the public permission to use the
 40 |      licensed material under specified terms and conditions. If
 41 |      the licensor's permission is not necessary for any reason--for
 42 |      example, because of any applicable exception or limitation to
 43 |      copyright--then that use is not regulated by the license. Our
 44 |      licenses grant only permissions under copyright and certain
 45 |      other rights that a licensor has authority to grant. Use of
 46 |      the licensed material may still be restricted for other
 47 |      reasons, including because others have copyright or other
 48 |      rights in the material. A licensor may make special requests,
 49 |      such as asking that all changes be marked or described.
 50 |      Although not required by our licenses, you are encouraged to
 51 |      respect those requests where reasonable. More considerations
 52 |      for the public:
 53 |     wiki.creativecommons.org/Considerations_for_licensees
 54 | 
 55 | =======================================================================
 56 | 
 57 | Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
 58 | Public License
 59 | 
 60 | By exercising the Licensed Rights (defined below), You accept and agree
 61 | to be bound by the terms and conditions of this Creative Commons
 62 | Attribution-NonCommercial-ShareAlike 4.0 International Public License
 63 | ("Public License"). To the extent this Public License may be
 64 | interpreted as a contract, You are granted the Licensed Rights in
 65 | consideration of Your acceptance of these terms and conditions, and the
 66 | Licensor grants You such rights in consideration of benefits the
 67 | Licensor receives from making the Licensed Material available under
 68 | these terms and conditions.
 69 | 
 70 | 
 71 | Section 1 -- Definitions.
 72 | 
 73 |   a. Adapted Material means material subject to Copyright and Similar
 74 |      Rights that is derived from or based upon the Licensed Material
 75 |      and in which the Licensed Material is translated, altered,
 76 |      arranged, transformed, or otherwise modified in a manner requiring
 77 |      permission under the Copyright and Similar Rights held by the
 78 |      Licensor. For purposes of this Public License, where the Licensed
 79 |      Material is a musical work, performance, or sound recording,
 80 |      Adapted Material is always produced where the Licensed Material is
 81 |      synched in timed relation with a moving image.
 82 | 
 83 |   b. Adapter's License means the license You apply to Your Copyright
 84 |      and Similar Rights in Your contributions to Adapted Material in
 85 |      accordance with the terms and conditions of this Public License.
 86 | 
 87 |   c. BY-NC-SA Compatible License means a license listed at
 88 |      creativecommons.org/compatiblelicenses, approved by Creative
 89 |      Commons as essentially the equivalent of this Public License.
 90 | 
 91 |   d. Copyright and Similar Rights means copyright and/or similar rights
 92 |      closely related to copyright including, without limitation,
 93 |      performance, broadcast, sound recording, and Sui Generis Database
 94 |      Rights, without regard to how the rights are labeled or
 95 |      categorized. For purposes of this Public License, the rights
 96 |      specified in Section 2(b)(1)-(2) are not Copyright and Similar
 97 |      Rights.
 98 | 
 99 |   e. Effective Technological Measures means those measures that, in the
100 |      absence of proper authority, may not be circumvented under laws
101 |      fulfilling obligations under Article 11 of the WIPO Copyright
102 |      Treaty adopted on December 20, 1996, and/or similar international
103 |      agreements.
104 | 
105 |   f. Exceptions and Limitations means fair use, fair dealing, and/or
106 |      any other exception or limitation to Copyright and Similar Rights
107 |      that applies to Your use of the Licensed Material.
108 | 
109 |   g. License Elements means the license attributes listed in the name
110 |      of a Creative Commons Public License. The License Elements of this
111 |      Public License are Attribution, NonCommercial, and ShareAlike.
112 | 
113 |   h. Licensed Material means the artistic or literary work, database,
114 |      or other material to which the Licensor applied this Public
115 |      License.
116 | 
117 |   i. Licensed Rights means the rights granted to You subject to the
118 |      terms and conditions of this Public License, which are limited to
119 |      all Copyright and Similar Rights that apply to Your use of the
120 |      Licensed Material and that the Licensor has authority to license.
121 | 
122 |   j. Licensor means the individual(s) or entity(ies) granting rights
123 |      under this Public License.
124 | 
125 |   k. NonCommercial means not primarily intended for or directed towards
126 |      commercial advantage or monetary compensation. For purposes of
127 |      this Public License, the exchange of the Licensed Material for
128 |      other material subject to Copyright and Similar Rights by digital
129 |      file-sharing or similar means is NonCommercial provided there is
130 |      no payment of monetary compensation in connection with the
131 |      exchange.
132 | 
133 |   l. Share means to provide material to the public by any means or
134 |      process that requires permission under the Licensed Rights, such
135 |      as reproduction, public display, public performance, distribution,
136 |      dissemination, communication, or importation, and to make material
137 |      available to the public including in ways that members of the
138 |      public may access the material from a place and at a time
139 |      individually chosen by them.
140 | 
141 |   m. Sui Generis Database Rights means rights other than copyright
142 |      resulting from Directive 96/9/EC of the European Parliament and of
143 |      the Council of 11 March 1996 on the legal protection of databases,
144 |      as amended and/or succeeded, as well as other essentially
145 |      equivalent rights anywhere in the world.
146 | 
147 |   n. You means the individual or entity exercising the Licensed Rights
148 |      under this Public License. Your has a corresponding meaning.
149 | 
150 | 
151 | Section 2 -- Scope.
152 | 
153 |   a. License grant.
154 | 
155 |        1. Subject to the terms and conditions of this Public License,
156 |           the Licensor hereby grants You a worldwide, royalty-free,
157 |           non-sublicensable, non-exclusive, irrevocable license to
158 |           exercise the Licensed Rights in the Licensed Material to:
159 | 
160 |             a. reproduce and Share the Licensed Material, in whole or
161 |                in part, for NonCommercial purposes only; and
162 | 
163 |             b. produce, reproduce, and Share Adapted Material for
164 |                NonCommercial purposes only.
165 | 
166 |        2. Exceptions and Limitations. For the avoidance of doubt, where
167 |           Exceptions and Limitations apply to Your use, this Public
168 |           License does not apply, and You do not need to comply with
169 |           its terms and conditions.
170 | 
171 |        3. Term. The term of this Public License is specified in Section
172 |           6(a).
173 | 
174 |        4. Media and formats; technical modifications allowed. The
175 |           Licensor authorizes You to exercise the Licensed Rights in
176 |           all media and formats whether now known or hereafter created,
177 |           and to make technical modifications necessary to do so. The
178 |           Licensor waives and/or agrees not to assert any right or
179 |           authority to forbid You from making technical modifications
180 |           necessary to exercise the Licensed Rights, including
181 |           technical modifications necessary to circumvent Effective
182 |           Technological Measures. For purposes of this Public License,
183 |           simply making modifications authorized by this Section 2(a)
184 |           (4) never produces Adapted Material.
185 | 
186 |        5. Downstream recipients.
187 | 
188 |             a. Offer from the Licensor -- Licensed Material. Every
189 |                recipient of the Licensed Material automatically
190 |                receives an offer from the Licensor to exercise the
191 |                Licensed Rights under the terms and conditions of this
192 |                Public License.
193 | 
194 |             b. Additional offer from the Licensor -- Adapted Material.
195 |                Every recipient of Adapted Material from You
196 |                automatically receives an offer from the Licensor to
197 |                exercise the Licensed Rights in the Adapted Material
198 |                under the conditions of the Adapter's License You apply.
199 | 
200 |             c. No downstream restrictions. You may not offer or impose
201 |                any additional or different terms or conditions on, or
202 |                apply any Effective Technological Measures to, the
203 |                Licensed Material if doing so restricts exercise of the
204 |                Licensed Rights by any recipient of the Licensed
205 |                Material.
206 | 
207 |        6. No endorsement. Nothing in this Public License constitutes or
208 |           may be construed as permission to assert or imply that You
209 |           are, or that Your use of the Licensed Material is, connected
210 |           with, or sponsored, endorsed, or granted official status by,
211 |           the Licensor or others designated to receive attribution as
212 |           provided in Section 3(a)(1)(A)(i).
213 | 
214 |   b. Other rights.
215 | 
216 |        1. Moral rights, such as the right of integrity, are not
217 |           licensed under this Public License, nor are publicity,
218 |           privacy, and/or other similar personality rights; however, to
219 |           the extent possible, the Licensor waives and/or agrees not to
220 |           assert any such rights held by the Licensor to the limited
221 |           extent necessary to allow You to exercise the Licensed
222 |           Rights, but not otherwise.
223 | 
224 |        2. Patent and trademark rights are not licensed under this
225 |           Public License.
226 | 
227 |        3. To the extent possible, the Licensor waives any right to
228 |           collect royalties from You for the exercise of the Licensed
229 |           Rights, whether directly or through a collecting society
230 |           under any voluntary or waivable statutory or compulsory
231 |           licensing scheme. In all other cases the Licensor expressly
232 |           reserves any right to collect such royalties, including when
233 |           the Licensed Material is used other than for NonCommercial
234 |           purposes.
235 | 
236 | 
237 | Section 3 -- License Conditions.
238 | 
239 | Your exercise of the Licensed Rights is expressly made subject to the
240 | following conditions.
241 | 
242 |   a. Attribution.
243 | 
244 |        1. If You Share the Licensed Material (including in modified
245 |           form), You must:
246 | 
247 |             a. retain the following if it is supplied by the Licensor
248 |                with the Licensed Material:
249 | 
250 |                  i. identification of the creator(s) of the Licensed
251 |                     Material and any others designated to receive
252 |                     attribution, in any reasonable manner requested by
253 |                     the Licensor (including by pseudonym if
254 |                     designated);
255 | 
256 |                 ii. a copyright notice;
257 | 
258 |                iii. a notice that refers to this Public License;
259 | 
260 |                 iv. a notice that refers to the disclaimer of
261 |                     warranties;
262 | 
263 |                  v. a URI or hyperlink to the Licensed Material to the
264 |                     extent reasonably practicable;
265 | 
266 |             b. indicate if You modified the Licensed Material and
267 |                retain an indication of any previous modifications; and
268 | 
269 |             c. indicate the Licensed Material is licensed under this
270 |                Public License, and include the text of, or the URI or
271 |                hyperlink to, this Public License.
272 | 
273 |        2. You may satisfy the conditions in Section 3(a)(1) in any
274 |           reasonable manner based on the medium, means, and context in
275 |           which You Share the Licensed Material. For example, it may be
276 |           reasonable to satisfy the conditions by providing a URI or
277 |           hyperlink to a resource that includes the required
278 |           information.
279 |        3. If requested by the Licensor, You must remove any of the
280 |           information required by Section 3(a)(1)(A) to the extent
281 |           reasonably practicable.
282 | 
283 |   b. ShareAlike.
284 | 
285 |      In addition to the conditions in Section 3(a), if You Share
286 |      Adapted Material You produce, the following conditions also apply.
287 | 
288 |        1. The Adapter's License You apply must be a Creative Commons
289 |           license with the same License Elements, this version or
290 |           later, or a BY-NC-SA Compatible License.
291 | 
292 |        2. You must include the text of, or the URI or hyperlink to, the
293 |           Adapter's License You apply. You may satisfy this condition
294 |           in any reasonable manner based on the medium, means, and
295 |           context in which You Share Adapted Material.
296 | 
297 |        3. You may not offer or impose any additional or different terms
298 |           or conditions on, or apply any Effective Technological
299 |           Measures to, Adapted Material that restrict exercise of the
300 |           rights granted under the Adapter's License You apply.
301 | 
302 | 
303 | Section 4 -- Sui Generis Database Rights.
304 | 
305 | Where the Licensed Rights include Sui Generis Database Rights that
306 | apply to Your use of the Licensed Material:
307 | 
308 |   a. for the avoidance of doubt, Section 2(a)(1) grants You the right
309 |      to extract, reuse, reproduce, and Share all or a substantial
310 |      portion of the contents of the database for NonCommercial purposes
311 |      only;
312 | 
313 |   b. if You include all or a substantial portion of the database
314 |      contents in a database in which You have Sui Generis Database
315 |      Rights, then the database in which You have Sui Generis Database
316 |      Rights (but not its individual contents) is Adapted Material,
317 |      including for purposes of Section 3(b); and
318 | 
319 |   c. You must comply with the conditions in Section 3(a) if You Share
320 |      all or a substantial portion of the contents of the database.
321 | 
322 | For the avoidance of doubt, this Section 4 supplements and does not
323 | replace Your obligations under this Public License where the Licensed
324 | Rights include other Copyright and Similar Rights.
325 | 
326 | 
327 | Section 5 -- Disclaimer of Warranties and Limitation of Liability.
328 | 
329 |   a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
330 |      EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
331 |      AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
332 |      ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
333 |      IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
334 |      WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
335 |      PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
336 |      ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
337 |      KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
338 |      ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
339 | 
340 |   b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
341 |      TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
342 |      NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
343 |      INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
344 |      COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
345 |      USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
346 |      ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
347 |      DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
348 |      IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
349 | 
350 |   c. The disclaimer of warranties and limitation of liability provided
351 |      above shall be interpreted in a manner that, to the extent
352 |      possible, most closely approximates an absolute disclaimer and
353 |      waiver of all liability.
354 | 
355 | 
356 | Section 6 -- Term and Termination.
357 | 
358 |   a. This Public License applies for the term of the Copyright and
359 |      Similar Rights licensed here. However, if You fail to comply with
360 |      this Public License, then Your rights under this Public License
361 |      terminate automatically.
362 | 
363 |   b. Where Your right to use the Licensed Material has terminated under
364 |      Section 6(a), it reinstates:
365 | 
366 |        1. automatically as of the date the violation is cured, provided
367 |           it is cured within 30 days of Your discovery of the
368 |           violation; or
369 | 
370 |        2. upon express reinstatement by the Licensor.
371 | 
372 |      For the avoidance of doubt, this Section 6(b) does not affect any
373 |      right the Licensor may have to seek remedies for Your violations
374 |      of this Public License.
375 | 
376 |   c. For the avoidance of doubt, the Licensor may also offer the
377 |      Licensed Material under separate terms or conditions or stop
378 |      distributing the Licensed Material at any time; however, doing so
379 |      will not terminate this Public License.
380 | 
381 |   d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
382 |      License.
383 | 
384 | 
385 | Section 7 -- Other Terms and Conditions.
386 | 
387 |   a. The Licensor shall not be bound by any additional or different
388 |      terms or conditions communicated by You unless expressly agreed.
389 | 
390 |   b. Any arrangements, understandings, or agreements regarding the
391 |      Licensed Material not stated herein are separate from and
392 |      independent of the terms and conditions of this Public License.
393 | 
394 | 
395 | Section 8 -- Interpretation.
396 | 
397 |   a. For the avoidance of doubt, this Public License does not, and
398 |      shall not be interpreted to, reduce, limit, restrict, or impose
399 |      conditions on any use of the Licensed Material that could lawfully
400 |      be made without permission under this Public License.
401 | 
402 |   b. To the extent possible, if any provision of this Public License is
403 |      deemed unenforceable, it shall be automatically reformed to the
404 |      minimum extent necessary to make it enforceable. If the provision
405 |      cannot be reformed, it shall be severed from this Public License
406 |      without affecting the enforceability of the remaining terms and
407 |      conditions.
408 | 
409 |   c. No term or condition of this Public License will be waived and no
410 |      failure to comply consented to unless expressly agreed to by the
411 |      Licensor.
412 | 
413 |   d. Nothing in this Public License constitutes or may be interpreted
414 |      as a limitation upon, or waiver of, any privileges and immunities
415 |      that apply to the Licensor or You, including from the legal
416 |      processes of any jurisdiction or authority.
417 | 
418 | =======================================================================
419 | 
420 | Creative Commons is not a party to its public
421 | licenses. Notwithstanding, Creative Commons may elect to apply one of
422 | its public licenses to material it publishes and in those instances
423 | will be considered the “Licensor.” The text of the Creative Commons
424 | public licenses is dedicated to the public domain under the CC0 Public
425 | Domain Dedication. Except for the limited purpose of indicating that
426 | material is shared under a Creative Commons public license or as
427 | otherwise permitted by the Creative Commons policies published at
428 | creativecommons.org/policies, Creative Commons does not authorize the
429 | use of the trademark "Creative Commons" or any other trademark or logo
430 | of Creative Commons without its prior written consent including,
431 | without limitation, in connection with any unauthorized modifications
432 | to any of its public licenses or any other arrangements,
433 | understandings, or agreements concerning use of licensed material. For
434 | the avoidance of doubt, this paragraph does not form part of the
435 | public licenses.
436 | 
437 | Creative Commons may be contacted at creativecommons.org.
438 | 
439 | 


--------------------------------------------------------------------------------
/LICENSE-GPL-30.txt:
--------------------------------------------------------------------------------
  1 |                     GNU GENERAL PUBLIC LICENSE
  2 |                        Version 3, 29 June 2007
  3 | 
  4 |  Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
  5 |  Everyone is permitted to copy and distribute verbatim copies
  6 |  of this license document, but changing it is not allowed.
  7 | 
  8 |                             Preamble
  9 | 
 10 |   The GNU General Public License is a free, copyleft license for
 11 | software and other kinds of works.
 12 | 
 13 |   The licenses for most software and other practical works are designed
 14 | to take away your freedom to share and change the works.  By contrast,
 15 | the GNU General Public License is intended to guarantee your freedom to
 16 | share and change all versions of a program--to make sure it remains free
 17 | software for all its users.  We, the Free Software Foundation, use the
 18 | GNU General Public License for most of our software; it applies also to
 19 | any other work released this way by its authors.  You can apply it to
 20 | your programs, too.
 21 | 
 22 |   When we speak of free software, we are referring to freedom, not
 23 | price.  Our General Public Licenses are designed to make sure that you
 24 | have the freedom to distribute copies of free software (and charge for
 25 | them if you wish), that you receive source code or can get it if you
 26 | want it, that you can change the software or use pieces of it in new
 27 | free programs, and that you know you can do these things.
 28 | 
 29 |   To protect your rights, we need to prevent others from denying you
 30 | these rights or asking you to surrender the rights.  Therefore, you have
 31 | certain responsibilities if you distribute copies of the software, or if
 32 | you modify it: responsibilities to respect the freedom of others.
 33 | 
 34 |   For example, if you distribute copies of such a program, whether
 35 | gratis or for a fee, you must pass on to the recipients the same
 36 | freedoms that you received.  You must make sure that they, too, receive
 37 | or can get the source code.  And you must show them these terms so they
 38 | know their rights.
 39 | 
 40 |   Developers that use the GNU GPL protect your rights with two steps:
 41 | (1) assert copyright on the software, and (2) offer you this License
 42 | giving you legal permission to copy, distribute and/or modify it.
 43 | 
 44 |   For the developers' and authors' protection, the GPL clearly explains
 45 | that there is no warranty for this free software.  For both users' and
 46 | authors' sake, the GPL requires that modified versions be marked as
 47 | changed, so that their problems will not be attributed erroneously to
 48 | authors of previous versions.
 49 | 
 50 |   Some devices are designed to deny users access to install or run
 51 | modified versions of the software inside them, although the manufacturer
 52 | can do so.  This is fundamentally incompatible with the aim of
 53 | protecting users' freedom to change the software.  The systematic
 54 | pattern of such abuse occurs in the area of products for individuals to
 55 | use, which is precisely where it is most unacceptable.  Therefore, we
 56 | have designed this version of the GPL to prohibit the practice for those
 57 | products.  If such problems arise substantially in other domains, we
 58 | stand ready to extend this provision to those domains in future versions
 59 | of the GPL, as needed to protect the freedom of users.
 60 | 
 61 |   Finally, every program is threatened constantly by software patents.
 62 | States should not allow patents to restrict development and use of
 63 | software on general-purpose computers, but in those that do, we wish to
 64 | avoid the special danger that patents applied to a free program could
 65 | make it effectively proprietary.  To prevent this, the GPL assures that
 66 | patents cannot be used to render the program non-free.
 67 | 
 68 |   The precise terms and conditions for copying, distribution and
 69 | modification follow.
 70 | 
 71 |                        TERMS AND CONDITIONS
 72 | 
 73 |   0. Definitions.
 74 | 
 75 |   "This License" refers to version 3 of the GNU General Public License.
 76 | 
 77 |   "Copyright" also means copyright-like laws that apply to other kinds of
 78 | works, such as semiconductor masks.
 79 | 
 80 |   "The Program" refers to any copyrightable work licensed under this
 81 | License.  Each licensee is addressed as "you".  "Licensees" and
 82 | "recipients" may be individuals or organizations.
 83 | 
 84 |   To "modify" a work means to copy from or adapt all or part of the work
 85 | in a fashion requiring copyright permission, other than the making of an
 86 | exact copy.  The resulting work is called a "modified version" of the
 87 | earlier work or a work "based on" the earlier work.
 88 | 
 89 |   A "covered work" means either the unmodified Program or a work based
 90 | on the Program.
 91 | 
 92 |   To "propagate" a work means to do anything with it that, without
 93 | permission, would make you directly or secondarily liable for
 94 | infringement under applicable copyright law, except executing it on a
 95 | computer or modifying a private copy.  Propagation includes copying,
 96 | distribution (with or without modification), making available to the
 97 | public, and in some countries other activities as well.
 98 | 
 99 |   To "convey" a work means any kind of propagation that enables other
100 | parties to make or receive copies.  Mere interaction with a user through
101 | a computer network, with no transfer of a copy, is not conveying.
102 | 
103 |   An interactive user interface displays "Appropriate Legal Notices"
104 | to the extent that it includes a convenient and prominently visible
105 | feature that (1) displays an appropriate copyright notice, and (2)
106 | tells the user that there is no warranty for the work (except to the
107 | extent that warranties are provided), that licensees may convey the
108 | work under this License, and how to view a copy of this License.  If
109 | the interface presents a list of user commands or options, such as a
110 | menu, a prominent item in the list meets this criterion.
111 | 
112 |   1. Source Code.
113 | 
114 |   The "source code" for a work means the preferred form of the work
115 | for making modifications to it.  "Object code" means any non-source
116 | form of a work.
117 | 
118 |   A "Standard Interface" means an interface that either is an official
119 | standard defined by a recognized standards body, or, in the case of
120 | interfaces specified for a particular programming language, one that
121 | is widely used among developers working in that language.
122 | 
123 |   The "System Libraries" of an executable work include anything, other
124 | than the work as a whole, that (a) is included in the normal form of
125 | packaging a Major Component, but which is not part of that Major
126 | Component, and (b) serves only to enable use of the work with that
127 | Major Component, or to implement a Standard Interface for which an
128 | implementation is available to the public in source code form.  A
129 | "Major Component", in this context, means a major essential component
130 | (kernel, window system, and so on) of the specific operating system
131 | (if any) on which the executable work runs, or a compiler used to
132 | produce the work, or an object code interpreter used to run it.
133 | 
134 |   The "Corresponding Source" for a work in object code form means all
135 | the source code needed to generate, install, and (for an executable
136 | work) run the object code and to modify the work, including scripts to
137 | control those activities.  However, it does not include the work's
138 | System Libraries, or general-purpose tools or generally available free
139 | programs which are used unmodified in performing those activities but
140 | which are not part of the work.  For example, Corresponding Source
141 | includes interface definition files associated with source files for
142 | the work, and the source code for shared libraries and dynamically
143 | linked subprograms that the work is specifically designed to require,
144 | such as by intimate data communication or control flow between those
145 | subprograms and other parts of the work.
146 | 
147 |   The Corresponding Source need not include anything that users
148 | can regenerate automatically from other parts of the Corresponding
149 | Source.
150 | 
151 |   The Corresponding Source for a work in source code form is that
152 | same work.
153 | 
154 |   2. Basic Permissions.
155 | 
156 |   All rights granted under this License are granted for the term of
157 | copyright on the Program, and are irrevocable provided the stated
158 | conditions are met.  This License explicitly affirms your unlimited
159 | permission to run the unmodified Program.  The output from running a
160 | covered work is covered by this License only if the output, given its
161 | content, constitutes a covered work.  This License acknowledges your
162 | rights of fair use or other equivalent, as provided by copyright law.
163 | 
164 |   You may make, run and propagate covered works that you do not
165 | convey, without conditions so long as your license otherwise remains
166 | in force.  You may convey covered works to others for the sole purpose
167 | of having them make modifications exclusively for you, or provide you
168 | with facilities for running those works, provided that you comply with
169 | the terms of this License in conveying all material for which you do
170 | not control copyright.  Those thus making or running the covered works
171 | for you must do so exclusively on your behalf, under your direction
172 | and control, on terms that prohibit them from making any copies of
173 | your copyrighted material outside their relationship with you.
174 | 
175 |   Conveying under any other circumstances is permitted solely under
176 | the conditions stated below.  Sublicensing is not allowed; section 10
177 | makes it unnecessary.
178 | 
179 |   3. Protecting Users' Legal Rights From Anti-Circumvention Law.
180 | 
181 |   No covered work shall be deemed part of an effective technological
182 | measure under any applicable law fulfilling obligations under article
183 | 11 of the WIPO copyright treaty adopted on 20 December 1996, or
184 | similar laws prohibiting or restricting circumvention of such
185 | measures.
186 | 
187 |   When you convey a covered work, you waive any legal power to forbid
188 | circumvention of technological measures to the extent such circumvention
189 | is effected by exercising rights under this License with respect to
190 | the covered work, and you disclaim any intention to limit operation or
191 | modification of the work as a means of enforcing, against the work's
192 | users, your or third parties' legal rights to forbid circumvention of
193 | technological measures.
194 | 
195 |   4. Conveying Verbatim Copies.
196 | 
197 |   You may convey verbatim copies of the Program's source code as you
198 | receive it, in any medium, provided that you conspicuously and
199 | appropriately publish on each copy an appropriate copyright notice;
200 | keep intact all notices stating that this License and any
201 | non-permissive terms added in accord with section 7 apply to the code;
202 | keep intact all notices of the absence of any warranty; and give all
203 | recipients a copy of this License along with the Program.
204 | 
205 |   You may charge any price or no price for each copy that you convey,
206 | and you may offer support or warranty protection for a fee.
207 | 
208 |   5. Conveying Modified Source Versions.
209 | 
210 |   You may convey a work based on the Program, or the modifications to
211 | produce it from the Program, in the form of source code under the
212 | terms of section 4, provided that you also meet all of these conditions:
213 | 
214 |     a) The work must carry prominent notices stating that you modified
215 |     it, and giving a relevant date.
216 | 
217 |     b) The work must carry prominent notices stating that it is
218 |     released under this License and any conditions added under section
219 |     7.  This requirement modifies the requirement in section 4 to
220 |     "keep intact all notices".
221 | 
222 |     c) You must license the entire work, as a whole, under this
223 |     License to anyone who comes into possession of a copy.  This
224 |     License will therefore apply, along with any applicable section 7
225 |     additional terms, to the whole of the work, and all its parts,
226 |     regardless of how they are packaged.  This License gives no
227 |     permission to license the work in any other way, but it does not
228 |     invalidate such permission if you have separately received it.
229 | 
230 |     d) If the work has interactive user interfaces, each must display
231 |     Appropriate Legal Notices; however, if the Program has interactive
232 |     interfaces that do not display Appropriate Legal Notices, your
233 |     work need not make them do so.
234 | 
235 |   A compilation of a covered work with other separate and independent
236 | works, which are not by their nature extensions of the covered work,
237 | and which are not combined with it such as to form a larger program,
238 | in or on a volume of a storage or distribution medium, is called an
239 | "aggregate" if the compilation and its resulting copyright are not
240 | used to limit the access or legal rights of the compilation's users
241 | beyond what the individual works permit.  Inclusion of a covered work
242 | in an aggregate does not cause this License to apply to the other
243 | parts of the aggregate.
244 | 
245 |   6. Conveying Non-Source Forms.
246 | 
247 |   You may convey a covered work in object code form under the terms
248 | of sections 4 and 5, provided that you also convey the
249 | machine-readable Corresponding Source under the terms of this License,
250 | in one of these ways:
251 | 
252 |     a) Convey the object code in, or embodied in, a physical product
253 |     (including a physical distribution medium), accompanied by the
254 |     Corresponding Source fixed on a durable physical medium
255 |     customarily used for software interchange.
256 | 
257 |     b) Convey the object code in, or embodied in, a physical product
258 |     (including a physical distribution medium), accompanied by a
259 |     written offer, valid for at least three years and valid for as
260 |     long as you offer spare parts or customer support for that product
261 |     model, to give anyone who possesses the object code either (1) a
262 |     copy of the Corresponding Source for all the software in the
263 |     product that is covered by this License, on a durable physical
264 |     medium customarily used for software interchange, for a price no
265 |     more than your reasonable cost of physically performing this
266 |     conveying of source, or (2) access to copy the
267 |     Corresponding Source from a network server at no charge.
268 | 
269 |     c) Convey individual copies of the object code with a copy of the
270 |     written offer to provide the Corresponding Source.  This
271 |     alternative is allowed only occasionally and noncommercially, and
272 |     only if you received the object code with such an offer, in accord
273 |     with subsection 6b.
274 | 
275 |     d) Convey the object code by offering access from a designated
276 |     place (gratis or for a charge), and offer equivalent access to the
277 |     Corresponding Source in the same way through the same place at no
278 |     further charge.  You need not require recipients to copy the
279 |     Corresponding Source along with the object code.  If the place to
280 |     copy the object code is a network server, the Corresponding Source
281 |     may be on a different server (operated by you or a third party)
282 |     that supports equivalent copying facilities, provided you maintain
283 |     clear directions next to the object code saying where to find the
284 |     Corresponding Source.  Regardless of what server hosts the
285 |     Corresponding Source, you remain obligated to ensure that it is
286 |     available for as long as needed to satisfy these requirements.
287 | 
288 |     e) Convey the object code using peer-to-peer transmission, provided
289 |     you inform other peers where the object code and Corresponding
290 |     Source of the work are being offered to the general public at no
291 |     charge under subsection 6d.
292 | 
293 |   A separable portion of the object code, whose source code is excluded
294 | from the Corresponding Source as a System Library, need not be
295 | included in conveying the object code work.
296 | 
297 |   A "User Product" is either (1) a "consumer product", which means any
298 | tangible personal property which is normally used for personal, family,
299 | or household purposes, or (2) anything designed or sold for incorporation
300 | into a dwelling.  In determining whether a product is a consumer product,
301 | doubtful cases shall be resolved in favor of coverage.  For a particular
302 | product received by a particular user, "normally used" refers to a
303 | typical or common use of that class of product, regardless of the status
304 | of the particular user or of the way in which the particular user
305 | actually uses, or expects or is expected to use, the product.  A product
306 | is a consumer product regardless of whether the product has substantial
307 | commercial, industrial or non-consumer uses, unless such uses represent
308 | the only significant mode of use of the product.
309 | 
310 |   "Installation Information" for a User Product means any methods,
311 | procedures, authorization keys, or other information required to install
312 | and execute modified versions of a covered work in that User Product from
313 | a modified version of its Corresponding Source.  The information must
314 | suffice to ensure that the continued functioning of the modified object
315 | code is in no case prevented or interfered with solely because
316 | modification has been made.
317 | 
318 |   If you convey an object code work under this section in, or with, or
319 | specifically for use in, a User Product, and the conveying occurs as
320 | part of a transaction in which the right of possession and use of the
321 | User Product is transferred to the recipient in perpetuity or for a
322 | fixed term (regardless of how the transaction is characterized), the
323 | Corresponding Source conveyed under this section must be accompanied
324 | by the Installation Information.  But this requirement does not apply
325 | if neither you nor any third party retains the ability to install
326 | modified object code on the User Product (for example, the work has
327 | been installed in ROM).
328 | 
329 |   The requirement to provide Installation Information does not include a
330 | requirement to continue to provide support service, warranty, or updates
331 | for a work that has been modified or installed by the recipient, or for
332 | the User Product in which it has been modified or installed.  Access to a
333 | network may be denied when the modification itself materially and
334 | adversely affects the operation of the network or violates the rules and
335 | protocols for communication across the network.
336 | 
337 |   Corresponding Source conveyed, and Installation Information provided,
338 | in accord with this section must be in a format that is publicly
339 | documented (and with an implementation available to the public in
340 | source code form), and must require no special password or key for
341 | unpacking, reading or copying.
342 | 
343 |   7. Additional Terms.
344 | 
345 |   "Additional permissions" are terms that supplement the terms of this
346 | License by making exceptions from one or more of its conditions.
347 | Additional permissions that are applicable to the entire Program shall
348 | be treated as though they were included in this License, to the extent
349 | that they are valid under applicable law.  If additional permissions
350 | apply only to part of the Program, that part may be used separately
351 | under those permissions, but the entire Program remains governed by
352 | this License without regard to the additional permissions.
353 | 
354 |   When you convey a copy of a covered work, you may at your option
355 | remove any additional permissions from that copy, or from any part of
356 | it.  (Additional permissions may be written to require their own
357 | removal in certain cases when you modify the work.)  You may place
358 | additional permissions on material, added by you to a covered work,
359 | for which you have or can give appropriate copyright permission.
360 | 
361 |   Notwithstanding any other provision of this License, for material you
362 | add to a covered work, you may (if authorized by the copyright holders of
363 | that material) supplement the terms of this License with terms:
364 | 
365 |     a) Disclaiming warranty or limiting liability differently from the
366 |     terms of sections 15 and 16 of this License; or
367 | 
368 |     b) Requiring preservation of specified reasonable legal notices or
369 |     author attributions in that material or in the Appropriate Legal
370 |     Notices displayed by works containing it; or
371 | 
372 |     c) Prohibiting misrepresentation of the origin of that material, or
373 |     requiring that modified versions of such material be marked in
374 |     reasonable ways as different from the original version; or
375 | 
376 |     d) Limiting the use for publicity purposes of names of licensors or
377 |     authors of the material; or
378 | 
379 |     e) Declining to grant rights under trademark law for use of some
380 |     trade names, trademarks, or service marks; or
381 | 
382 |     f) Requiring indemnification of licensors and authors of that
383 |     material by anyone who conveys the material (or modified versions of
384 |     it) with contractual assumptions of liability to the recipient, for
385 |     any liability that these contractual assumptions directly impose on
386 |     those licensors and authors.
387 | 
388 |   All other non-permissive additional terms are considered "further
389 | restrictions" within the meaning of section 10.  If the Program as you
390 | received it, or any part of it, contains a notice stating that it is
391 | governed by this License along with a term that is a further
392 | restriction, you may remove that term.  If a license document contains
393 | a further restriction but permits relicensing or conveying under this
394 | License, you may add to a covered work material governed by the terms
395 | of that license document, provided that the further restriction does
396 | not survive such relicensing or conveying.
397 | 
398 |   If you add terms to a covered work in accord with this section, you
399 | must place, in the relevant source files, a statement of the
400 | additional terms that apply to those files, or a notice indicating
401 | where to find the applicable terms.
402 | 
403 |   Additional terms, permissive or non-permissive, may be stated in the
404 | form of a separately written license, or stated as exceptions;
405 | the above requirements apply either way.
406 | 
407 |   8. Termination.
408 | 
409 |   You may not propagate or modify a covered work except as expressly
410 | provided under this License.  Any attempt otherwise to propagate or
411 | modify it is void, and will automatically terminate your rights under
412 | this License (including any patent licenses granted under the third
413 | paragraph of section 11).
414 | 
415 |   However, if you cease all violation of this License, then your
416 | license from a particular copyright holder is reinstated (a)
417 | provisionally, unless and until the copyright holder explicitly and
418 | finally terminates your license, and (b) permanently, if the copyright
419 | holder fails to notify you of the violation by some reasonable means
420 | prior to 60 days after the cessation.
421 | 
422 |   Moreover, your license from a particular copyright holder is
423 | reinstated permanently if the copyright holder notifies you of the
424 | violation by some reasonable means, this is the first time you have
425 | received notice of violation of this License (for any work) from that
426 | copyright holder, and you cure the violation prior to 30 days after
427 | your receipt of the notice.
428 | 
429 |   Termination of your rights under this section does not terminate the
430 | licenses of parties who have received copies or rights from you under
431 | this License.  If your rights have been terminated and not permanently
432 | reinstated, you do not qualify to receive new licenses for the same
433 | material under section 10.
434 | 
435 |   9. Acceptance Not Required for Having Copies.
436 | 
437 |   You are not required to accept this License in order to receive or
438 | run a copy of the Program.  Ancillary propagation of a covered work
439 | occurring solely as a consequence of using peer-to-peer transmission
440 | to receive a copy likewise does not require acceptance.  However,
441 | nothing other than this License grants you permission to propagate or
442 | modify any covered work.  These actions infringe copyright if you do
443 | not accept this License.  Therefore, by modifying or propagating a
444 | covered work, you indicate your acceptance of this License to do so.
445 | 
446 |   10. Automatic Licensing of Downstream Recipients.
447 | 
448 |   Each time you convey a covered work, the recipient automatically
449 | receives a license from the original licensors, to run, modify and
450 | propagate that work, subject to this License.  You are not responsible
451 | for enforcing compliance by third parties with this License.
452 | 
453 |   An "entity transaction" is a transaction transferring control of an
454 | organization, or substantially all assets of one, or subdividing an
455 | organization, or merging organizations.  If propagation of a covered
456 | work results from an entity transaction, each party to that
457 | transaction who receives a copy of the work also receives whatever
458 | licenses to the work the party's predecessor in interest had or could
459 | give under the previous paragraph, plus a right to possession of the
460 | Corresponding Source of the work from the predecessor in interest, if
461 | the predecessor has it or can get it with reasonable efforts.
462 | 
463 |   You may not impose any further restrictions on the exercise of the
464 | rights granted or affirmed under this License.  For example, you may
465 | not impose a license fee, royalty, or other charge for exercise of
466 | rights granted under this License, and you may not initiate litigation
467 | (including a cross-claim or counterclaim in a lawsuit) alleging that
468 | any patent claim is infringed by making, using, selling, offering for
469 | sale, or importing the Program or any portion of it.
470 | 
471 |   11. Patents.
472 | 
473 |   A "contributor" is a copyright holder who authorizes use under this
474 | License of the Program or a work on which the Program is based.  The
475 | work thus licensed is called the contributor's "contributor version".
476 | 
477 |   A contributor's "essential patent claims" are all patent claims
478 | owned or controlled by the contributor, whether already acquired or
479 | hereafter acquired, that would be infringed by some manner, permitted
480 | by this License, of making, using, or selling its contributor version,
481 | but do not include claims that would be infringed only as a
482 | consequence of further modification of the contributor version.  For
483 | purposes of this definition, "control" includes the right to grant
484 | patent sublicenses in a manner consistent with the requirements of
485 | this License.
486 | 
487 |   Each contributor grants you a non-exclusive, worldwide, royalty-free
488 | patent license under the contributor's essential patent claims, to
489 | make, use, sell, offer for sale, import and otherwise run, modify and
490 | propagate the contents of its contributor version.
491 | 
492 |   In the following three paragraphs, a "patent license" is any express
493 | agreement or commitment, however denominated, not to enforce a patent
494 | (such as an express permission to practice a patent or covenant not to
495 | sue for patent infringement).  To "grant" such a patent license to a
496 | party means to make such an agreement or commitment not to enforce a
497 | patent against the party.
498 | 
499 |   If you convey a covered work, knowingly relying on a patent license,
500 | and the Corresponding Source of the work is not available for anyone
501 | to copy, free of charge and under the terms of this License, through a
502 | publicly available network server or other readily accessible means,
503 | then you must either (1) cause the Corresponding Source to be so
504 | available, or (2) arrange to deprive yourself of the benefit of the
505 | patent license for this particular work, or (3) arrange, in a manner
506 | consistent with the requirements of this License, to extend the patent
507 | license to downstream recipients.  "Knowingly relying" means you have
508 | actual knowledge that, but for the patent license, your conveying the
509 | covered work in a country, or your recipient's use of the covered work
510 | in a country, would infringe one or more identifiable patents in that
511 | country that you have reason to believe are valid.
512 | 
513 |   If, pursuant to or in connection with a single transaction or
514 | arrangement, you convey, or propagate by procuring conveyance of, a
515 | covered work, and grant a patent license to some of the parties
516 | receiving the covered work authorizing them to use, propagate, modify
517 | or convey a specific copy of the covered work, then the patent license
518 | you grant is automatically extended to all recipients of the covered
519 | work and works based on it.
520 | 
521 |   A patent license is "discriminatory" if it does not include within
522 | the scope of its coverage, prohibits the exercise of, or is
523 | conditioned on the non-exercise of one or more of the rights that are
524 | specifically granted under this License.  You may not convey a covered
525 | work if you are a party to an arrangement with a third party that is
526 | in the business of distributing software, under which you make payment
527 | to the third party based on the extent of your activity of conveying
528 | the work, and under which the third party grants, to any of the
529 | parties who would receive the covered work from you, a discriminatory
530 | patent license (a) in connection with copies of the covered work
531 | conveyed by you (or copies made from those copies), or (b) primarily
532 | for and in connection with specific products or compilations that
533 | contain the covered work, unless you entered into that arrangement,
534 | or that patent license was granted, prior to 28 March 2007.
535 | 
536 |   Nothing in this License shall be construed as excluding or limiting
537 | any implied license or other defenses to infringement that may
538 | otherwise be available to you under applicable patent law.
539 | 
540 |   12. No Surrender of Others' Freedom.
541 | 
542 |   If conditions are imposed on you (whether by court order, agreement or
543 | otherwise) that contradict the conditions of this License, they do not
544 | excuse you from the conditions of this License.  If you cannot convey a
545 | covered work so as to satisfy simultaneously your obligations under this
546 | License and any other pertinent obligations, then as a consequence you may
547 | not convey it at all.  For example, if you agree to terms that obligate you
548 | to collect a royalty for further conveying from those to whom you convey
549 | the Program, the only way you could satisfy both those terms and this
550 | License would be to refrain entirely from conveying the Program.
551 | 
552 |   13. Use with the GNU Affero General Public License.
553 | 
554 |   Notwithstanding any other provision of this License, you have
555 | permission to link or combine any covered work with a work licensed
556 | under version 3 of the GNU Affero General Public License into a single
557 | combined work, and to convey the resulting work.  The terms of this
558 | License will continue to apply to the part which is the covered work,
559 | but the special requirements of the GNU Affero General Public License,
560 | section 13, concerning interaction through a network will apply to the
561 | combination as such.
562 | 
563 |   14. Revised Versions of this License.
564 | 
565 |   The Free Software Foundation may publish revised and/or new versions of
566 | the GNU General Public License from time to time.  Such new versions will
567 | be similar in spirit to the present version, but may differ in detail to
568 | address new problems or concerns.
569 | 
570 |   Each version is given a distinguishing version number.  If the
571 | Program specifies that a certain numbered version of the GNU General
572 | Public License "or any later version" applies to it, you have the
573 | option of following the terms and conditions either of that numbered
574 | version or of any later version published by the Free Software
575 | Foundation.  If the Program does not specify a version number of the
576 | GNU General Public License, you may choose any version ever published
577 | by the Free Software Foundation.
578 | 
579 |   If the Program specifies that a proxy can decide which future
580 | versions of the GNU General Public License can be used, that proxy's
581 | public statement of acceptance of a version permanently authorizes you
582 | to choose that version for the Program.
583 | 
584 |   Later license versions may give you additional or different
585 | permissions.  However, no additional obligations are imposed on any
586 | author or copyright holder as a result of your choosing to follow a
587 | later version.
588 | 
589 |   15. Disclaimer of Warranty.
590 | 
591 |   THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
592 | APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
593 | HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
594 | OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
595 | THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
596 | PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
597 | IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
598 | ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
599 | 
600 |   16. Limitation of Liability.
601 | 
602 |   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
603 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
604 | THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
605 | GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
606 | USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
607 | DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
608 | PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
609 | EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
610 | SUCH DAMAGES.
611 | 
612 |   17. Interpretation of Sections 15 and 16.
613 | 
614 |   If the disclaimer of warranty and limitation of liability provided
615 | above cannot be given local legal effect according to their terms,
616 | reviewing courts shall apply local law that most closely approximates
617 | an absolute waiver of all civil liability in connection with the
618 | Program, unless a warranty or assumption of liability accompanies a
619 | copy of the Program in return for a fee.
620 | 
621 |                      END OF TERMS AND CONDITIONS
622 | 
623 |             How to Apply These Terms to Your New Programs
624 | 
625 |   If you develop a new program, and you want it to be of the greatest
626 | possible use to the public, the best way to achieve this is to make it
627 | free software which everyone can redistribute and change under these terms.
628 | 
629 |   To do so, attach the following notices to the program.  It is safest
630 | to attach them to the start of each source file to most effectively
631 | state the exclusion of warranty; and each file should have at least
632 | the "copyright" line and a pointer to where the full notice is found.
633 | 
634 |     <one line to give the program's name and a brief idea of what it does.>
635 |     Copyright (C) <year>  <name of author>
636 | 
637 |     This program is free software: you can redistribute it and/or modify
638 |     it under the terms of the GNU General Public License as published by
639 |     the Free Software Foundation, either version 3 of the License, or
640 |     (at your option) any later version.
641 | 
642 |     This program is distributed in the hope that it will be useful,
643 |     but WITHOUT ANY WARRANTY; without even the implied warranty of
644 |     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
645 |     GNU General Public License for more details.
646 | 
647 |     You should have received a copy of the GNU General Public License
648 |     along with this program.  If not, see <https://www.gnu.org/licenses/>.
649 | 
650 | Also add information on how to contact you by electronic and paper mail.
651 | 
652 |   If the program does terminal interaction, make it output a short
653 | notice like this when it starts in an interactive mode:
654 | 
655 |     <program>  Copyright (C) <year>  <name of author>
656 |     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
657 |     This is free software, and you are welcome to redistribute it
658 |     under certain conditions; type `show c' for details.
659 | 
660 | The hypothetical commands `show w' and `show c' should show the appropriate
661 | parts of the General Public License.  Of course, your program's commands
662 | might be different; for a GUI interface, you would use an "about box".
663 | 
664 |   You should also get your employer (if you work as a programmer) or school,
665 | if any, to sign a "copyright disclaimer" for the program, if necessary.
666 | For more information on this, and how to apply and follow the GNU GPL, see
667 | <https://www.gnu.org/licenses/>.
668 | 
669 |   The GNU General Public License does not permit incorporating your program
670 | into proprietary programs.  If your program is a subroutine library, you
671 | may consider it more useful to permit linking proprietary applications with
672 | the library.  If this is what you want to do, use the GNU Lesser General
673 | Public License instead of this License.  But first, please read
674 | <https://www.gnu.org/licenses/why-not-lgpl.html>.
675 | 


--------------------------------------------------------------------------------