HiveMind

Log in

NFC Reader Configuration

This page contains setup instructions for NFC Player Stat Trackers.

The stat trackers each use one Raspberry Pi Zero W, and contain buttons and lights and a USB NFC card reader. The blue stat tracker also connects to the cabinet via Ethernet and runs the stats client.

Easy Configuration

  • Download the image:
  • Write the image to an SD card.
    • You can use the Raspberry Pi Imager for this.
    • Download and unzip the image, click to select an operating system, then select "Use Custom"
  • The system will start up in test mode. Tapping any card and pressing a button will turn on the light. Pressing the button again will turn it off.
  • To configure the system, connect to the WiFi network "HiveMind Config". The configuration screen should automatically load -- If it doesn't automatically load the URL is http://portal.kqhivemind.com/
  • Enter your WiFi and cabinet configuration information. You can also optionally set a password for the hivemind user, and/or add a SSH public key.
  • After saving the configuration, the system will reboot with the new configuration.

Manual Setup

Use these instructions to install and configure an older version of the image if the above does not work for you.

Initial Setup

Basic Info

Connect using SSH.

  • Username: hivemind
  • Initial password: HiveMind123

You can also configure the stat trackers by placing the following files in the SD card's boot partition:

  • wpa_supplicant.conf - WiFi network configuration
  • config.json - stats client config
  • nfc-config.json - card reader config

Configuration Files

wpa_supplicant.conf

This file contains the WiFi network configuration. It is needed on both readers. This file can contain multiple networks, and the system will connect to whichever one is in range.

If using SSH, you can add a new network using the wpa_passphrase command. See "Add a New Wifi Connection" below.

To create a new configuration file, place a file called wpa_supplicant.conf in /etc/wpa_supplicant or in the boot partition of the SD card. You can use https://codepen.io/LilTrublMakr/full/yRGPrv to generate this file.

Example contents:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
country=us

network={
  ssid="<SSID>"
  psk="<PASSWORD>"
  scan_ssid=1
}

config.json

This file controls the stats client. It is only needed on the blue reader.

On the blue reader, in your home directory or in the boot partition of the SD card, create a file called config.json.

Example contents:

{
  "cabinets": [
    {
      "sceneName": "<scene name>",
      "cabinetName": "<cabinet name>",
      "token": "<cabinet client token>",
      "url": "ws://10.68.182.100:12749"
    }
  ],
  "servers": [
    {
      "name": "HiveMind",
      "url": "wss://kqhivemind.com/ws/stats_listener/v3"
    }
  ]
}

nfc-config.json

This file controls the card reader sign-in system. It is required on both readers.

The images contain a version of this file that will run the readers in test mode. In test mode, tapping any card and pressing a button will turn on the corresponding light, and pressing the button again will turn it off. This can be used to test hardware without needing to configure the reader.

If editing the existing version of this file, be sure to remove the test_mode: True entry.

In your home directory or in the boot partition of the SD card, create a file called nfc-config.json.

Example contents for blue reader:

{
    "pin_config": [
        { "player_id": 4, "button": 22, "light": 21 },
        { "player_id": 6, "button": 12, "light": 16 },
        { "player_id": 2, "button": 19, "light": 18 },
        { "player_id": 8, "button": 13, "light": 15 },
        { "player_id": 10, "button": 24, "light": 23 }
    ],
    "scene": "<scene name>",
    "cabinet": "<cabinet name>",
    "token": "<cabinet client token>",
    "reader": "blue",
    "usb_device": "usb:072f:2200",
    "light_mode": "low",
    "button_mode": "low",
    "pins_low": [26]
}

Example contents for gold reader:

{
    "pin_config": [
        { "player_id": 3, "button": 22, "light": 21 },
        { "player_id": 5, "button": 12, "light": 16 },
        { "player_id": 1, "button": 19, "light": 18 },
        { "player_id": 7, "button": 13, "light": 15 },
        { "player_id": 9, "button": 24, "light": 23 }
    ],
    "scene": "<scene name>",
    "cabinet": "<cabinet name>",
    "token": "<cabinet client token>",
    "reader": "gold",
    "usb_device": "usb:072f:2200",
    "light_mode": "low",
    "button_mode": "low",
    "pins_low": [26]
}

Unless you have built your own reader, you should only need to change the scene, cabinet, and token values.

  • token is on the HiveMind admin page for the cabinet and is the same value used by the stats client's config file.
  • usb_device is the vendor and product ID of the card reader from the previous section.
  • reader is blue or gold.
  • pin_config should contain one entry per player station:
    • player_id is the ID of the station - for example, 2 is Blue Queen. From left to right, these are 4, 6, 2, 8, 10 on the blue side, and 3, 5, 1, 7, 9 on the gold side.
    • button and light are the pin numbers associated with the button and light for this station.
  • light_mode: set to "high" if the common wire to the LEDs is on a +5V pin, or "low" if connected to ground.
  • button_mode: set to "high" if the common wire to the buttons is on a +5V pin, or "low" if connected to ground.
  • pins_low is an array of pins that should always be set to ground.
  • pins_high is an array of pins that should always be set to +5V.
  • test_mode: set to True to enable test mode (see above).

Hardware

Parts List

Wiring

  • See https://pinout.xyz/pinout/io_pi_zero for the pin configuration. You will need to connect 12 wires - one power, one ground, and ten GPIO.
  • Lights should be connected from a GPIO pin to ground.
  • Buttons should be connected from a GPIO pin to power.
  • Make note of the pin number of each GPIO pin used. You will need the "Physical/Board" pin number (1-40).
  • Do not use pins 27 and 28. These are reserved.

Multiple Configuration Files

If you are going to be moving your NFC readers between cabinets often, and want to connect the stats to a different cabinet on HiveMind when moving, you can set up separate config files, and use symlinks to point to the correct one.

Other options include swapping out the SD cards based on location, or simply leaving the config files to point to a single "cabinet" in HiveMind that just tracks wherever you have the readers.

The blue reader uses config.json for the stats client and nfc-config.json for the sign-in system, while the gold reader only uses nfc-config.json.

In this example, the readers are configured for cabinet1, and we will add config files for cabinet2.

Move the Configuration Files

cd ~

# on both blue and gold
mv nfc-config.json nfc-config.cabinet1.json
ln -s nfc-config.cabinet1.json nfc-config.json

# on blue only
mv config.json config.cabinet1.json
ln -s config.cabinet1.json config.json

Copy and Edit New Config Files

# on both blue and gold
cp nfc-config.cabinet1.json nfc-config.cabinet2.json

# on blue only
cp config.cabinet1.json config.cabinet2.json

Edit the cabinet2 configuration files, changing the cabinet name and token. If your network setup is different, you may also need to edit config.cabinet2.json so it can connect to the cabinet.

Add a New Wifi Connection

wpa_passphrase "<SSID>" "<PSK>" | sudo tee -a "/etc/wpa_supplicant/wpa_supplicant.conf"

The OS will select whichever network is in range, so this will not need to be changed every time.

Switching Configurations

# on both blue and gold
ln -s nfc-config.cabinet2.json nfc-config.json
sudo systemctl restart hivemind-nfc-reader

# on blue only
ln -s config.cabinet2.json config.json
sudo systemctl restart hivemind-client

Support for PN532 NFC Reader

The PN532 reader can be used as an alternative to the ACR122U.

  • Set to I2C mode using switches
  • Connect wires:
    • GND -> 6
    • VCC -> 4
    • SDA -> 3
    • SCL -> 5
  • Enable I2C in raspi-config
  • Add hivemind user to i2c group:
sudo gpasswd -a hivemind i2c
  • Install required packages:
sudo apt -y install i2c-tools libnfc-bin libnfc-examples
  • Test I2C connection: i2cdetect -y 1
    • If connected properly, the number "24" should appear in the table.
     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
00:          -- -- -- -- -- -- -- -- -- -- -- -- -- 
10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
20: -- -- -- -- 24 -- -- -- -- -- -- -- -- -- -- -- 
30: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
50: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
60: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 
70: -- -- -- -- -- -- -- --
  • Add device to /etc/nfc/libnfc.conf:
device.name = "PN532-I2C"
device.connstring = "pn532_i2c:/dev/i2c-1"
  • Add setting to nfc-config.json file: "driver": "pn532_i2c"
    • The usb_device setting can be removed.