HitPlay

Hardware audio player intended for music games. Allows binding of (NFC enabled) game cards to music files.

Hardware

While this version of HitPlay should work with most ESP32 based boards with minimal changes to the Platform.io configuration, the reference device has been built using a Lolin32 Mini clone, simply due to it already having ob-board support for Lithium batteries so that the player can be powered without any cable. The following list shows the parts initially used for the prototype.

Component	Use
Lolin32 Board	Main board housing CPU, WiFi and a battery management system. Most other ESP32 boards should work as well, though.
I2S Audio Board	Used for audio output over line-out
Micro SD card reader module	Connecting an SD card for reading audio and configuration data from
PN532 RFID module	Reader used to read the NFC chips inside the game cards. Mainly used since it works with SPI - saving two pins and some headache when working together with the micro SD card module.
Arcade Button with LED	Used for play status display and as stop button. I replaced the original LED with one that is fit for the lower 3.3V of the ESP32.

Wiring diagram

‼️ Attention ‼️

When setting up the hardware, make sure that the dip switches at the bottom of the RFID module are set to SPI (I0 pointing to the right, I1 pointing to the left).

Software

You need an installed version of PlatformIO - either in your IDE of choice or as commandline setup.

For ease of use, the next steps assume, that you have VisualStudio Code with the PlatformIO extension installed. For more information about installing this development stack, see the official documentation.

Once you have downloaded or cloned this repository, installing the software is just a matter of loading the project, hooking up your assembled hardware to your computer via USB and pressing some buttons in the IDE.

To be able to play your game, some steps need to be done:

• Configuring the build
• Building and uploading the firmware
• Uploading the file system to the ESP32 board's internal flash storage
• Preparing the Micro SD card with music and system files
• Registering the cards

Build configuration

Open the downloaded project in VSCode by using the menu entry File -> Open Folder.... This will also load the PlatformIO extension and install all the dependencies this project needs.

Once this is done, there are two configuration files you should have a look at:

src/secrets.hpp

This file does not exist by default. You can copy the secrets.hpp.example and name that copy secrets.hpp. Here, you enter all the details that configure the WiFi connection of your hardware as well as the secret used for OTA updates later on. Fill in the details you desire.

src/configuration.hpp

This file contains the main settings for the game and the connected hardware. Normally, all settings should be good as they are, but if you want to change any of the defaults, this is the file to go. Every setting inside this file should be documented with a comment.

Uploading the firmware

Once you have configured your project, you can build and upload the firmware to your hardware by opening the PlatformIO menu on the left (the icon with the ant face) and pressing the menu entry called Upload.

If all is fine, you should see something alike the following in the terminal on the bottom of VSCode:

Uploading the file system

The files for the administration web interface are separate from the other source code. These files need to be built into a filesystem image and also uploaded to your ESP board. For this to happen, use the PlatformIO sidebar menu as before and click the Upload Filesystem Image instead. This will package everything and upload it to the ESP board's internal flash memory.

Preparing the SD card

Last but not least, a SD card needs to be prepared. This card will contain all your music files for the game as well as some system files the firmware needs to work with.

Preferably you should use a cleanly formatted SD card. Other files on it will not hurt, but might make keeping an overview on the contents a hassle.

Music files

Music used for your game has to be in individual .mp3 files. Where the files are placed is up to you. You will set the files to play once you register the game cards via the administration web interface.

It is important to not move the files after you registered the game cards, though.

System audio

This project contains some system audio files played on different events during the runtime of the player. These files can be found inside the audio directory inside this project. Create a new directory named .system-sounds on the SD cards and copy all the MP3s inside the audio folder there - not including the folder itself.

Once all files are copied, you are free to place the prepared SD card in your player and start everything up.

Registering the cards

When your game hardware boots up for the first time, it does not know which game cards should play which music. To let it know, connect to your hardwares WiFi network (the one you configured in the secrets.hpp) and open the administration website at http://192.168.4.1.

The site should show a list of music files and folders on your SD card:

Each file has two icons:

• plays the selected audio file
• starts the card assignment process

Assigning a card is simple:

• Press the assignment button of the MP3 file you want to assign the card to
• When the audio prompt can be heard, put the card on the RFID reader until you hear the confirmation from the device
• After 10 seconds of not assigning any new card or playing any music, the assignments are saved to the SD card, followed by another audio confirmation