Magic Cards: Add RFID to Your Ring Alarm

What is Magic Cards?

Magic Cards is a project from Maddox available on GitHub https://github.com/maddox/magic-cards It was developed as a way to launch music on Sonos devices and integrate with Home Assistant and Channels. It also allows you to run shell scripts.

Integration Methodology

It is the script functionality of Magic Cards that we will leverage for integration with our Ring Alarm systems. In our article Ring MQTT: Do more with your Ring Products we were able to provide an MQTT interface through the Ring-MQTT project. You will want to have that functionality in place before continuing with this install.

The Hardware

Magic Cards was designed to run on a Raspberry Pi Zero W. If you don’t know a Pi Zero is a tiny single-board computer (60.0mm x 30.5mm x 5.0mm). It can run Linux, has a very low cost and has built-in Wi-Fi. This makes it a great option for solutions like this.

It also requires an RFID reader. The original project specifies an extremely low-cost 125kHz reader and cards using the older EM4100/TK4100 standard. Cards are available in a variety of form factors including cards, fobs and wristbands. Additionally, I have been using the system with more expensive readers capable of decoding modern encrypted cards from multiple vendors. Most likely including the one, you might use at work or a parking garage. A parts list is included at the end of the article with links for Amazon in Canada and the USA. If you are using an existing Pi Zero make sure you have a micro-USB – OTG adaptor. It is also recommended you have a second scanner as it will make entering new cards much easier.

Preparing the Pi Zero

Operating System Installation

To get the base operating system loaded and updated see our previous article Headless Mode Install: Raspberry Pi Zero W. As this device will be running a webserver. It is highly recommended that you also follow the section on setting a static IP.

Update: March 14, 2020
To save a bunch of time I have created a Raspbian Buster image with Magic Cards pre-installed. You simply need to write the image using Etcher. A few items from the Headless Mode Install are still required. Add the wpa_supplicant.conf file with your Wi-Fi information. Then place the card in your Pi Zero and start it up. If you have mDNS working as described you should now be able to open the web interface at http://raspberrypi.local:5000 or connect to raspberrypi.local with your ssh client.
The file is available on Google Drive: Magic-Cards.img
MD5 Hash: 414f9309ffb25f8ee2022a4f44f0cc90
You probably also still want to change the hostname and set a static IP address.

Software Pre-requisites

Several supporting packages are needed to ensure your Pi is ready to run Magic Cards

Permissions

In order to be able to access the RFID reader, your user pi needs to be part of the input group. This is because the reader is seen as an input device by the system.

sudo usermod -a -G input pi

Git

If you don’t already have git installed, you can install it with:

sudo apt-get install git -y

Node.js

The code for Magic Cards is written in Node.js. There are 2 running processes. There is a server for the management interface. Additionally, there is a scanner service that listens for card scans.
You can install Node version 9.11.2 with the following command. This specific version is required for Magic Cards.

wget -O - https://raw.githubusercontent.com/sdesalas/node-pi-zero/master/install-node-v9.11.2.sh | bash

To confirm the install run

node -v

You should get output similar to v9.11.2

Yarn

Now that Node is installed you can install Yarn. First, add the repo to sources.list

curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - 
echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list

Then to install, you can simply run.

sudo apt update && sudo apt install yarn

To confirm the installation run.

yarn –version

You should get output similar to 1.22.0

Mosquitto

To be able to send MQTT commands to Ring MQTT we need to install the mosquitto clients.

sudo apt-get install mosquitto-clients -y

Your Pi Zero should now be ready to install Magic Cards.

Magic Cards Installation

While a docker install is an option. With a Pi Zero, I found it to be both very temperamental and resource-heavy to the point of slowing down card processing.  Before continuing, plug your RFID scanner into your Pi Zero.

Download the Package

cd ~ 
git clone https://github.com/maddox/magic-cards.git

Start the Installation

cd ~/magic-cards
script/setup

1. Yarn install runs multiple times as there are several modules to build.
   1. It usually complains about fsevents but it doesn’t affect the function.
   2. It will also most likely complain about your network connection as it seems to overwhelm the connection at times.
   3. Occasionally the script dies fetching packages. Simply re-run script/setup and it will resume where it stopped.
2. The setup script takes a long time on a Pi Zero W.

Configuration Files

We will need to create a few configuration files to get Magic Cards to run.

actions.json

actions.json appropriately contains the actions that can be performed by Magic Cards. We will configure ours a little later, for now, we will just create a blank file.

cd ~/magic-cards/config
touch actions.json

config.json

config.json contains the main configuration options. An example is below

{
  "room": "Living Room",
  "input_device": "event0",
  "spotify": {
    "clientID": "XXX",
    "clientSecret": "XXX"
  }
}

The main item we need to confirm here is the input_device. If you only have the card scanner plugged in the default of event0 will most likely be correct.
To confirm run

cd /dev/input/by-id/
ls -l

You should see output like the example below. If there is more than one item look for the one ending in kbd. The corresponding event# is what you need.

Now we can create config.json with the appropriate input_device.

cd ~/magic-cards/config
nano config.json

Type or paste the example into the new file. Confirm input_device matches what you determined earlier. Additionally, change the room variable to correspond to your install location. This is more important if you will have multiple Magic Cards hosts in your home.

{
  "room": "Polargeek",
  "input_device": "event0",
  "spotify": {
    "clientID": "XXX",
    "clientSecret": "XXX"
  }
}

Once you have made the appropriate changes.
Press Ctrl + x to exit.
When prompted hit Y then Enter to save and exit

Running Magic Cards

First Startup

Now that the initial configuration is complete we need to run the install script. It will create the service files needed for automatic startup and start Magic Cards.

cd ~/magic-cards
script/install

When you see Magic Cards has been started. You can open a web browser to HTTP://<ipaddress of pi>:5000 You should see a screen like

Magic Cards is now up and running and we can move on to adding actions and cards.

Creating Our Action

As we are using the script action type we will need two files. The built-in actions.json and a separate shell script.

The Script

I have chosen to call my script disarm.sh but you can call it whatever you choose. Running the commands below will create the file, make it executable and open it for editing.

cd ~/magic-cards/config
touch disarm.sh
chmod +x disarm.sh
nano disarm.sh

The example script’s contents below perform two actions. First, it disarms the panel and then unlocks a specific door. So if you were to install multiple units you could key the device to the door it is placed by.

Variables

<mqtt-broker> enter the IP address of your MQTT broker.
<location_id> Your Ring location ID.
<device_id> The specific internal ID of the device you are controlling.
<user> The username for your MQTT server.
<password> The password for your MQTT server.

#!/bin/bash
# Alarm Panel
mosquitto_pub -h <mqtt-broker> -m "DISARM" -t ring/<location_id>/alarm/alarm_control_panel/<device_id>/alarm_command -u <user> -P <password>
# Door Lock
mosquitto_pub -h <mqtt-broker> -m "UNLOCK" -t ring/<location_id>/alarm/lock/<device_id>/lock_command -u <user> -P <password>

Once you have made the appropriate changes.
Press Ctrl + x to exit.
When prompted hit Y then Enter to save and exit

Editing actions.json

Now we need to add an action to actions.json that will trigger our script. Open the file for editing

nano ~/magic-cards/config/actions.json

The structure of the script action is fairly simple.
The first variable is the name of the action. In this case Alarm.
Second, we have the type which for our purposes is script.
Lastly, we need to specify the filename. If you used the example name it is disarm.sh Otherwise adjust to the name you chose.

{
    "Alarm": {
      "type": "script",
      "filename": "disarm.sh"
    }
  }

Once you have made the appropriate changes.
Press Ctrl + x to exit.
When prompted hit Y then Enter to save and exit

Adding a Card

Now that we have our action defined we will add a card and set it to use the action. Head back to the web interface HTTP://<ipaddress of pi>:5000 Click Add Card in the top right corner of the window. You will be presented with a blank card as shown. We will need to fill out a few fields to make the card work.

Critical Fields

Set Content Type to Event.
Additionally set Action to Alarm. (It will default to Alarm if you have no other actions defined.)

Card Code is especially critical as this is the Unique ID of the card.
If you followed the recommendations and purchased an additional card reader. Getting the ID is very simple. Plug that reader into the computer you are editing the cards on. The reader acts as a keyboard so will enter the ID for you. Simply ensure you are on the Card Code field and swipe the card.

If you did not get another reader. The code as Magic Cards sees it can still be retrieved. Swipe the desired card on the reader attached to the Magic Cards host. Then from a shell on the host run.

cat /var/log/daemon.log

You will get a screen full of text. Near the bottom, you should find.
Read Card ID: xxxxxxxxxx
Finding card…
Card not found.
It is the 10 character ID that you need to copy into Card Code

Optional Fields

Title can bet set to whatever you’d like. But a name representing the user of the card makes the most sense
Art URL can be filled with a hyperlink if you’d like a nice visual for the card on the listing screen.

Once you have it filled out like below click Create Card

You will be returned to the main screen. If your card was added successfully you will see it listed. Additional cards can be added the same way.

Conclusion

If everything has gone as planned swiping your card should turn off your alarm and unlock your door. By combining two excellent Open Source projects. We have now extended the functionality of our Ring Alarm, to now include features usually only found on higher-end systems.
Once again there is a parts list below for Amazon in Canada and the USA. Full disclosure they are affiliate links but are units known to work. The EM4100 stuff can also be found cheaper on AliExpress. If you do source them from there make sure the readers are configured to send the serial number as 10 digit hexadecimal as they come in 4 different configurations.

Troubleshooting

If you swipe your card and nothing happens there a couple of things to try.
First, you can confirm your action is working. To do this hover your mouse over the card. A play arrow will appear. Clicking it will test the action.

If that doesn’t work then check your script and action.json to make sure everything is correct. If the play button works then it’s probable that your Card Code is wrong. Once again from the console run.

cat /var/log/daemon.log

A correctly identified swipe should show as below.

If you get the Card not found message again. Double-check your numbers as they don’t match. Watch for leading or trailing spaces. You can edit the card by clicking on it.

Shopping List