Skip to content

Module: NFC Reader

Jump to bottom
Ant edited this page Aug 30, 2026 · 21 revisions

Allows you to use an PC/SC compatible NFC reader to watch videos associated to NFC Cards/Tags.

We've tested with both PN532 USB and ACS ACR122U NFC readers specifically. If you have a reader that is PC/SC compatible but it isn't being recognized, please let us know.

Contributors: jmcerrejon, anthonycaccese

Video Overview

Watch on Youtube

Features

  • Start video playback via NFC cards
  • Maps cards to videos via per-card text files in an nfc_tags data directory. The filename is the display title, line 1 the card UID, line 2 the video path or URL, and an optional line 3 for a playback mode
  • Path supports relative or absolute paths along with remote URLs and YouTube video/playlist URLs
  • Cards can also point at content in your Plex library — a movie, an episode, a season or a whole show. See Plex cards below
  • Resume playback supports playlist position as well as timecode so you can create "boxset" cards that contain a reference to a playlist for things like a full season of a given show or a YouTube playlist.
  • Tapping an unknown card will auto-create a stub tag file for it; simply rename that generated file and add a path to map the card

Settings

Option Values Info
Enabled On/Off Sets if the module should display in the main module list when you start 240-MP.
Tags Directory Default or User Selected Allows you to choose where the module will look for tag mapping files
Resume Playback Ask/Always/Never 'Ask' will present you with an option to restart playback or resume, 'Always' will resume without asking and 'Never' will restart playback from the beginning without asking
YouTube Video Resolution 480p (Default), 720p, 1080p Set the resolution of the video to request from YouTube for playback. I recommend to keep this on 480p for the Raspberry Pi on a CRT for best performance
Auto Show Subtitles On/Off/Forced Only Sets your preference for subtitle display when starting playback. On means if a subtitle is available then it will be set to display be default (based on your language preference). Forced only means it will attempt to find a subtitle track with a forced flag based on your language preference and if not default to off. Off will default to off =). All options still allow you toggle during playback.
Subtitle Language [Language] Sets your preferred language for subtitles and works in conjunction with the Auto Show Subtitles setting

To Enable

  1. Connect a compatible NFC Reader (we use and recommend PN532 USB or ACS ACR122U reader variants)
  2. Make sure the necessary drivers are installed
    • On Raspberry Pi:
      • Run the nfc reader set up script via: 
        bash <(curl -fsSL https://github.com/anthonycaccese/240-mp/releases/latest/download/setup-nfc-reader.sh)
      • This will set up the needed drivers on Raspberry Pi, you should see your reader is detected when it completes
    • On macOS:
      • The PC/SC drivers are included by default on MacOS so plugging in a compatible NFC reader should just work
    • On SteamOS:
      • PN532 USB readers work out of the box typically. however if you find your PN532 reader is not connecting then run the nfc reader setup script via: 
        bash <(curl -fsSL https://github.com/anthonycaccese/240-mp/releases/latest/download/setup-nfc-reader.sh)
  3. Create a .txt file for each card/tag you'd like to map inside the /nfc_tags/ directory located in 240-MP's data directory
    • Where:
      • On Raspberry Pi / SteamOS: ~/.local/share/240-MP/nfc_tags/
      • On macOS: ~/Library/Application Support/240-MP/nfc_tags/
    • Note: When you tap an un-mapped card with the module active... it will create a starting .txt for you in the same directory so you can simply change it's filename and add a video path the second line (the card ID will already be added on the first line for you). So if you'd like to wait until the module is running you can do this step later.
    • For each .txt file you add:
      • The filename will be used as the Title of the card in the UI
      • The first line of the .txt file should be the ID of the Card you'd like to map
      • The second line of the .txt file should be the Path of the video you'd like to play
      • Example: Contact (1997) Trailer.txt 
        04:23:58:DF:3F:02:89
https://www.youtube.com/watch?v=SRoj3jK37Vc
      • Paths can be absolute, relative, direct media URLs, YouTube page URLs (YouTube playback requires yt-dlp to be installed), or a Plex item reference (see Plex cards)
      • Relative paths are resolved from the app/data roots at runtime.
      • An optional third line sets a playback mode. Right now the only mode is shuffle, which applies to cards that point at a Plex show or season. Leave the line off for everything else.
  4. Then go to Settings > NFC Reader and set Enabled to On
  5. Open NFC Reader from the module list
  6. Present a mapped card to start playback

YouTube URL support

Make sure the latest version of yt-dlp is installed (mpv requires this to resolve YouTube URLs at playback time):

Please read the following wiki page for details on how to set it up: YT-DLP

Plex cards

A card can point at something in your Plex library instead of a file or URL, so you can make a card for a movie, a single episode, a season, or a whole show.

The easy way: let 240-MP write the card for you

  1. Make sure the NFC Reader module is enabled and your reader is plugged in
  2. Open the Plex module and browse to the movie, show, season or episode you want
  3. Choose Write NFC Card (it appears under Play / View Extras, and only shows up when a reader is connected)
  4. Tap a card when prompted
  5. For a show or season you'll be asked how it should play:
    • Sequential Episodes — plays the next episode you haven't watched, so tapping the card again tomorrow picks up where you left off
    • Shuffle Episodes — plays a random episode, jukebox style
  6. If the card already plays something else you'll be asked to confirm before it's changed

That's it, once done the tag file is written for you in the nfc_tags directory, and you can rename it afterwards if you'd like a different title on screen.

Writing one by hand

Line 2 of the tag file takes a Plex guid, which you can copy out of Plex's web app: find the item, choose Get Info, then View XML, and copy the guid value from the top of the page. Add shuffle on line 3 if you want a show or season card to play randomly.

The Simpsons.txt

04:23:58:DF:3F:02:89
plex://show/5d9c081ce264b7001fd60c0c
shuffle

Blade Runner.txt

04:B3:17:DD:3F:02:89
plex://movie/5d7768257b4b6a001f79b9e6

Things to know

  • Playback uses whichever Plex server and user profile you currently have selected. A card never switches servers or profiles for you — if the item isn't on the current server, or the current profile can't see it, you'll get a "not found on this server" message rather than a surprise profile switch
  • The Plex module has to be enabled and signed in. If it isn't, a Plex card simply won't play
  • Cards follow the Plex module's own settings for resume, video quality and Auto Play Next Episode. So if you have auto play turned off, a show card plays one episode and stops — shuffle included
  • Shuffle Episodes deliberately doesn't update your watch history. A shuffle card won't mark episodes watched or fill up Continue Watching, so leaving one running doesn't disturb where you actually are in a show. It plays through every episode once in a random order before repeating any
  • Only Plex guid references work
  • If a library still uses one of Plex's older metadata agents, its guids look like com.plexapp.agents.themoviedb://335984?lang=en instead of plex://movie/.... Those work fine, but they're tied to that agent so if you ever switch the library over to the newer Plex Movie / Plex TV Series agent, cards written against the old guids will stop resolving and need rewriting

Additional Notes

Install

Modules

Configuration

Hardware

Community

Clone this wiki locally