matrix-lite-nfc 0.0.2

A Python wrapper for MATRIX HAL NFC

MATRIX-Lite-NFC-Py

MATRIX Lite NFC Py is a package that allows users of varying skill levels to easily program NFC with their MATRIX Creator.

Smartphone Apps For Debugging

• IOS App
• Android App

Roadmap

• [x] Reading Info (All tags)
• [x] Reading Pages (MIFARE Ultralight & NTAG)
• [x] Writing Page (MIFARE Ultralight & NTAG)
• [x] Reading NDEF (MIFARE Ultralight & NTAG)
• [x] Writing NDEF (MIFARE Ultralight & NTAG)

Installation

1. Install MATRIX HAL NFC

https://github.com/matrix-io/matrix-hal-nfc

2. Install PIP3

To call your scripts with python 3, use python3 YOUR_SCRIPT.py

sudo apt-get install python3-pip

3. Upgrade PIP

python3 -m pip install --upgrade pip

4. Install matrix-lite-nfc-py

sudo python3 -m pip install matrix-lite-nfc

Reference

Import Statement

import matrix_lite_nfc as nfc

nfc.status

When a read or write function completes, it will contain a status code to indicate the result. nfc.Status returns a string of what that number means.

nfc.status(/*number*/)

nfc.read

There can only be one instance of NFC reading. This is a hardware limitation that will not change.

Synchronous Read

A simple read that returns an object with tag data.

nfc.read.scan({
    # At least 1 read options is required. Less options -> faster reading!
    "info": True,  # Generic information for any NFC tag
    "pages": True, # All page data
    "ndef": True,  # A single page(faster than pages)
    "page": 0,     # All NDEF data
})

Starting Read Loop

A non-blocking loop that passes tag data to a callback.

def read_callback(tag):
    if(tag.status == 256):
        print("NFC Tag Scanned!")
        print(tag)
    elif(tag.status == 1024):
        print("Nothing Scanned!")

# Configure what you want to read
nfc.read.start({
    "rate": 0.5, # Read loop speed (Seconds)
    "info": True,
    "pages": True,
    "ndef": True,
    "page": 0,
}, read_callback)

Stopping Read Loop

nfc.read.stop()

nfc.Message

1. Creating a new NDEF Message

# Create an empty NDEF message
msg = nfc.Message()

# Add NDEF Records to message
msg.addUriRecord("https://community.matrix.one")
msg.addUriRecord("tel:[phone]")
msg.addTextRecord("Hello World")
msg.addTextRecord("Hola Mundo", "es")
msg.addMimeMediaRecord("text/json", '{"answer": 42}')

# You then pass msg into nfc.write.message(msg)

2. Reading a new NDEF Message

# Get NDEF data from scanned tag
tag = nfc.read.scan({"ndef": True})

# Create & print NDEF message
msg = nfc.Message(tag.ndef.content)
print(msg.getRecords())

nfc.write

Writing to an NFC tag should normally be done inside the read loop.

Writing an NDEF message

# Create new message
msg = nfc.Message()
msg.addUriRecord("https://community.matrix.one")

# Write and then Print status codes for activation & writing
print(nfc.write.message(msg))

Erasing an NDEF message

print(nfc.write.erase())

Writing to a tag's page (WARNING)

Be careful when writing to a page. You can accidentally lock your NFC tag!

# arg1: page you want to overwrite
# arg2: Array of numbers that represents a byte
print(nfc.write.page(25, [48,45,59,21]))

Building Locally For Development

Download the repository.

git clone https://github.com/matrix-io/matrix-lite-nfc-py

Install pybind11.

sudo python3 -m pip install pybind11

Compile and install library.

sudo python3 -m pip install ./matrix-lite-nfc-py

Test your changes by importing any of the following libraries into a .py file.

# Direct C++ bindings
import _matrix_hal_nfc as hal_nfc

# Abstractions to _matrix_hal_nfc
import matrix_lite_nfc as nfc