first commit

lib/Arduino_MFRC522v2-master/doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = src
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

lib/Arduino_MFRC522v2-master/doc/PICCMemoryLayout.md

@@ -0,0 +1,79 @@
+# Memory Layout of common PICCs
+
+To read and write from MIFARE PICCs, the MIFARE protocol is used after the PICC has been selected.
+
+## Datasheet References
+
+The **MIFARE Classic** chips and protocol is described in the datasheets:
+
+* 1K:   https://www.mouser.com/ds/2/302/MF1S503x-89574.pdf
+* 4K:   https://datasheet.octopart.com/MF1S7035DA4,118-NXP-Semiconductors-datasheet-11046188.pdf
+* Mini: http://www.idcardmarket.com/download/mifare_S20_datasheet.pdf
+
+The **MIFARE Ultralight** chip and protocol is described in the datasheets:
+
+* Ultralight:   https://www.nxp.com/documents/data_sheet/MF0ICU1.pdf
+* Ultralight C: https://www.nxp.com/documents/short_data_sheet/MF0ICU2_SDS.pdf
+
+## MIFARE Classic 1K (MF1S503x)
+
+Has 16 sectors4 blocks/sector16 bytes/block = 1024 bytes.
+
+```text
+The blocks are numbered 0-63.
+Block 3 in each sector is the Sector Trailer. See https://www.mouser.com/ds/2/302/MF1S503x-89574.pdf sections 8.6 and 8.7:
+    Bytes 0-5:   Key A
+    Bytes 6-8:   Access Bits
+    Bytes 9:     User data
+    Bytes 10-15: Key B (or user data)
+Block 0 is read-only manufacturer data.
+To access a block, an authentication using a key from the block's sector must be performed first.
+Example: To read from block 10, first authenticate using a key from sector 3 (blocks 8-11).
+All keys are set to FFFFFFFFFFFFh at chip delivery.
+Warning: Please read section 8.7 "Memory Access". It includes this text: if the PICC detects a format violation the whole sector is irreversibly blocked.
+To use a block in "value block" mode (for Increment/Decrement operations) you need to change the sector trailer. Use PICC_SetAccessBits() to calculate the bit patterns.
+```
+
+## MIFARE Classic 4K (MF1S703x)
+
+Has (32 sectors4 blocks/sector + 8 sectors16 blocks/sector)16 bytes/block = 4096 bytes.
+
+```text
+The blocks are numbered 0-255.
+The last block in each sector is the Sector Trailer like above.
+```
+
+## MIFARE Classic Mini (MF1 IC S20)
+
+Has 5 sectors4 blocks/sector16 bytes/block = 320 bytes.
+
+```text
+The blocks are numbered 0-19.
+The last block in each sector is the Sector Trailer like above.
+```
+
+## MIFARE Ultralight (MF0ICU1)
+
+Has 16 pages of 4 bytes = 64 bytes.
+
+```text
+Pages 0 + 1 is used for the 7-byte UID.
+Page 2 contains the last check digit for the UID, one byte manufacturer internal data, and the lock bytes (see https://www.nxp.com/documents/data_sheet/MF0ICU1.pdf section 8.5.2)
+Page 3 is OTP, One Time Programmable bits. Once set to 1 they cannot revert to 0.
+Pages 4-15 are read/write unless blocked by the lock bytes in page 2. 
+```
+
+## MIFARE Ultralight C (MF0ICU2)
+
+Has 48 pages of 4 bytes = 192 bytes.
+
+```text
+Pages 0 + 1 is used for the 7-byte UID.
+Page 2 contains the last check digit for the UID, one byte manufacturer internal data, and the lock bytes (see https://www.nxp.com/documents/data_sheet/MF0ICU1.pdf section 8.5.2)
+Page 3 is OTP, One Time Programmable bits. Once set to 1 they cannot revert to 0.
+Pages 4-39 are read/write unless blocked by the lock bytes in page 2. 
+Page 40 Lock bytes
+Page 41 16 bit one way counter
+Pages 42-43 Authentication configuration
+Pages 44-47 Authentication key
+```

lib/Arduino_MFRC522v2-master/doc/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=src
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

lib/Arduino_MFRC522v2-master/doc/requirements.txt

@@ -0,0 +1,6 @@
+breathe==4.36.0
+exhale==0.3.7
+myst-parser==4.0.1
+myst-parser[linkify]
+sphinx==8.2.1
+sphinx-notfound-page==1.1.0

lib/Arduino_MFRC522v2-master/doc/src/Doxyfile

@@ -0,0 +1,11 @@
+PROJECT_NAME           = "MFRC522"
+INPUT                  = "../../src"
+
+OUTPUT_DIRECTORY       = "./_doxygen"
+EXTRACT_ALL            = NO # YES
+EXTRACT_PRIVATE        = NO # YES
+RECURSIVE              = YES
+VERBATIM_HEADERS       = NO
+GENERATE_HTML          = NO
+GENERATE_LATEX         = NO
+GENERATE_XML           = YES

lib/Arduino_MFRC522v2-master/doc/src/conf.py

@@ -0,0 +1,86 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+import subprocess
+
+sys.path.append(os.path.abspath('../..'))
+
+# Create xml data by Doxygen for sphinx.
+subprocess.call('doxygen Doxyfile', shell=True)
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'RFID_MFRC522v2'
+copyright = '2023, GithubCommunity'
+author = 'GithubCommunity'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'breathe',
+    "exhale",
+    'myst_parser',
+    'notfound.extension',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.coverage',
+    'sphinx.ext.githubpages',
+    'sphinx.ext.ifconfig',
+    'sphinx.ext.inheritance_diagram',
+    'sphinx.ext.todo',
+    'sphinx.ext.viewcode',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'literal',
+    '.md': 'markdown',
+}
+
+# If this is not None, a ‘Last updated on:’ timestamp is inserted at every page bottom.
+html_last_updated_fmt = ''
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+html_theme = 'nature'
+html_static_path = ['_static']
+
+### Custom plugins ###
+## Markdown
+myst_enable_extensions = [
+    "linkify",
+    "smartquotes",
+    "strikethrough",
+    "tasklist",
+]
+## Bridge doxygen <> sphinx.
+breathe_projects = {
+    'MFRC522': "./_doxygen/xml/"
+}
+breathe_default_project = 'MFRC522'
+breathe_default_members = (
+    'members', 
+    # 'undoc-members',
+)
+## Auto generate doc for every cpp-file. 
+exhale_args = {
+    "containmentFolder": "./lib",
+    "doxygenStripFromPath": "..",
+    "rootFileName": "index.rst",
+    "rootFileTitle": "Library API",
+    # "createTreeView":        True,
+}
+

lib/Arduino_MFRC522v2-master/doc/src/index.rst

@@ -0,0 +1,38 @@
+.. toctree::
+   :maxdepth: 2
+
+.. include:: ../../README.rst
+
+Library documentation
+=====================
+
+.. toctree::
+   :maxdepth: 4
+
+   lib/index.rst
+
+PICC
+====
+
+.. include:: ../PICCMemoryLayout.md
+   :parser: myst_parser.sphinx_
+
+Changelog
+=========
+
+.. include:: ../../changes.txt
+   :literal:
+
+
+License
+=======
+
+.. include:: ../../LICENSE
+   :literal:
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`