MR Physics Escape Room

A complete escape room on MR Physics, as presented at the 2025 ESMRMB Annual Meeting.

Assembly photos and step-by-step operating instructions for every puzzle are in Documents/Master/Escape Room Solution.odt. Documents/Player contains player-facing material (a sequence booklet and a gyromagnetic-ratios sheet) that can be printed and handed out during the game. BOM.ods is the bill of materials for all the electronics.

Repository structure

The room is built around six ESP32 nodes that talk to each other over ESP-NOW (see Arduino_Libraries/MREscapeRoomLib), plus one standalone utility. Each node has its own top-level folder containing the Arduino sketch, the Eagle PCB design, and 3D-printable/CNC parts for its enclosure:

• Keypad — 3x4 matrix keypad + RGB LED; player enters a secret code.
• Scale — load cell (HX711) puzzle; checks the weight of objects placed on the scale.
• SequenceComposer — 10 RFID readers under a board where players place physics-concept tiles in the right slots/order.
• Speaker — plays idle/success/failure/sequence audio from SPIFFS.
• Timer — e-Paper countdown display for the whole room.
• Monitor — TFT status console for the game master; shows live status from every other node and can reset the game.
• SPIFFSTool — standalone sketch + Python script used to upload audio files onto a node's SPIFFS filesystem over serial (used by Speaker).

Other top-level folders:

• Arduino_Libraries — third-party libraries (see below) plus the project's own MREscapeRoomLib, shared by all node sketches.
• Eagle_Libraries — custom Eagle component library used by the PCB designs.
• Documents — assembly/operating instructions, player handouts, and label artwork.
• BOM.ods — bill of materials.

Setup

1. Fabricate the PCBs from the Eagle folder of each node using BOM.ods, and build/print the enclosures from each node's 3D Files (and, for SequenceComposer, CNC Files).
2. Flash each node's sketch onto its ESP32 once to read out its MAC address (printed to Serial on boot), then update the corresponding *_MAC constant in Arduino_Libraries/MREscapeRoomLib/MREscapeRoomLib.h and reflash. All nodes must be flashed with a copy of the library that has the full, correct set of MAC addresses.
3. SequenceComposer: choose the RFID tags for each physics-concept tile, read their UIDs (enable DEBUG_OUTPUT in EscapeRoom_SequenceComposer.ino to print the UID seen by each reader instead of just a match indicator), and set the TILE_* constants and tile_mapping array accordingly.
4. Scale: pick the 4 objects that must be placed on the scale to solve the riddle, place them on the scale, and adjust scaleFactor and/or target/tolerance in EscapeRoom_Scale.ino until the node reports SAFETYOK (see Scale/README.txt).
5. Speaker: prepare the audio assets before flashing the final sketch. Source clips are in Speaker/Arduino/Original audio; the sequences used are listed in Speaker/Arduino/Sequences.txt (cine bSSFP, MPRAGE, ASL, EPI). Convert each clip to raw, unsigned 8-bit, mono, 16000 Hz PCM (matching sampleRate in EscapeRoom_Speaker.ino), e.g. with ffmpeg:

   ffmpeg -i input.m4a -f u8 -ar 16000 -ac 1 output.raw

   Then, per SPIFFSTool/README.txt:
   1. Flash SPIFFSTool/SPIFFSTool.ino onto the Speaker's ESP32.
   2. Use SPIFFSTool/serial-upload-script.py to upload the converted .raw files (pump.raw, success.raw, failure.raw, sequences.raw — see Speaker/Arduino/data for the files already used in this build) onto its SPIFFS partition.
   3. Reflash the ESP32 with EscapeRoom_Speaker.ino; the previously uploaded SPIFFS files are preserved across this reflash.
6. Timer: set INITIAL_TIME_SEC in EscapeRoom_Timer.ino to the desired game duration. Only regenerate the char_*.h/bg_black.h/ ry_success.h/ry_failure.h bitmap headers (and CHAR_X/CHAR_Y) if you change the display artwork or model.
7. Keypad: set SECRET_CODE/SECRET_CODE_LENGTH to the desired code and adjust SWITCH_MAPPING if the physical key layout differs.
8. Monitor: adjust RESET_DURATION (how long the reset button must be held) and LINE_LENGTH if needed, then use it to verify that every node shows up green (i.e. answers ESP-NOW pings) before running the room.

External libraries

The Arduino_Libraries folder contains third-party Arduino libraries used by this project. MREscapeRoomLib is custom code written for this project and is not a third-party import.

• TFT_eSPI by Bodmer — https://github.com/Bodmer/TFT_eSPI Originally based on Adafruit's Adafruit_ILI9341/Adafruit_GFX libraries (MIT/BSD licensed, Copyright (c) 2012 Adafruit Industries). Original contributions are licensed under the FreeBSD License, Copyright (c) 2023 Bodmer. See Arduino_Libraries/TFT_eSPI/license.txt.

• MFRC522 by GithubCommunity / miguelbalboa et al. — https://github.com/miguelbalboa/rfid Released into the public domain under the Unlicense. See Arduino_Libraries/MFRC522(1)/UNLICENSE.

• HX711 by Rob Tillaart (based on work by Bogdan Necula) — https://github.com/RobTillaart/HX711 MIT License, Copyright (c) 2019-2025 Rob Tillaart, Copyright (c) 2018 Bogdan Necula. See Arduino_Libraries/HX711/LICENSE.

• waveshare-e-Paper by Waveshare — http://www.waveshare.net/search.html?kw=e-paper GNU Lesser General Public License v2.1, Copyright (C) 1991, 1999 Free Software Foundation, Inc. See Arduino_Libraries/esp32-waveshare-epd/extras/License.txt.