"Sus" (Real Life Among Us)

Creating a real-life version of Among Us using Python, ESP32's, RFID, wifi and Raspberry Pi's

Public Chat
Similar projects worth following
As part of a school project, a group of students banded together to create a real life version of Among Us. To accomplish it, they designed a set of handheld scanners built using ESP32s with OLED screens, RFID scanners, buttons and a battery. The software was written in Python and MicroPython, with a centralised server running over WiFi on a raspberry pi.

This project has been completed, with the code and 3d models to be released as open source

This started as a 3-month project to teach the fundamentals of Software Development.  It uses Python and Flask to run an API backend as the main game server.  The front-end (on the handheld scanner devices) is written in Micropython and uses REST calls to request/pass data to the server.

The scanners themselves were designed in Solidworks and 3d printed on a standard-issue FDM printer (specifically a Neptune 2).  An ESP32 was selected as it provides a full fledged micro computer + display + wifi + battery management for a small price point.

The code itself was developed by a team of 12 students over the course of the 3 months using Github.  It was built using standard OO and MVC patterns to make the code as modular as possible.  Each scanner has a module to manage each hardware component as well as a simple mainloop.  The primary state of the scanner is managed by loading/running a minigame based on the actions of the player.

Gameplay itself starts with the players scanning their RFID-chipped ID badges (in this case their school ID badges, but any RFID tag would work) using the MFRC522 mounted to the back of each scanner.  Once all players have scanned in, the game starts when a "Start Game" tag is scanned by any scanner.  

When the game begins, the scanner tells each player their role (good guy or imposter) then gives them the options to play. 

For good guys they must wander around the area where there are "Stations" (RFID tags) stuck to the walls.  The scanner will randomly choose which station to go to and once a player goes there and scans the station they are given a minigame.  They must complete the minigame before moving to the next task.  There are a half dozen minigames, chosen at random when the station is scanned.

Imposters can pretend to scan stations/play minigames, scan player ID cards (which are attached to their backs) to "murder" them, or press a button to trigger a "sabotage".  

When a murdered player is discovered, scanning their ID badge will trigger a voting session.  Every scanner will All players must return to the voting room and scan the voting tag to register themselves in the room.  Failure to do so within a minute will result in their immediate death

Games are won if enough minigames are completed by the good guys, the imposters are voted out, or if the imposters murder down all the good guys

All project files for this project has been published on Github!  See the linky on the left for both code and 3d model files.

NOTE!  This project is concluded.  All issues on github will be ignored.  For contact, please message via ProfessorWoody here on hackaday or post on the discussion board below

Disclaimer: Photos have been edited to remove sensitive information.  For publicity rule reasons the name of the school has been omitted from this page.  For legal reasons the name of any specific students has been omitted, though the teammember names mentioned here are from those teammates which have explicitly chosen to be identified with this project.  To avoid all liability, responsibility, or legal claims the entire project is published under the MIT License

  • 1 × ESP32 + 0.96" OLED Provides CPU, wifi communications, battery charger, and OLED Display for less than $10
  • 1 × MFRC522 RFID Scanner, mounted to the back of the device
  • 4 × Momentary Switches To provide input from the players
  • 1 × Raspberry Pi To run as the back-end central server - though this could be any wifi-based computer
  • 1 × 3.7v Lipo battery we used 1100mah

View all 6 components

  • So Why Rest API?

    Professor Woody03/01/2022 at 11:42 0 comments

    During the project several of the students asked "Why are we using REST calls to pass/fetch data? Couldn't we set up a socket connection instead?" There's a few reasons for this, but first we should at least talk about the pros and cons of using REST.

    On the pros side, it's quite easy to support treating all our networking like they are web requests.  There are numerous libraries in place to handle all the data transfer, minimal networking involved, and the actions are well understood and documented.  On top of this, testing is made easier as we could easily try many of our API calls with nothing more than a smartphone and it's web browser.

    Using a shared networking standard also makes integration with other apps easier.  Early on there was a lot of discussion about building additional stations out of computers, projectors, raspberry pi's, etc.  By using such a ubiquitous standard as web requests, any software and hardware we wanted to use would already be compatible.  If could fetch a webpage from the internet then it could be wired into our game.

    There are a couple cons though.  The largest of these is the asynchronous "pull" nature of REST.  Data can only be requested, it can't be pushed.  This means if a change happens on the server, then there's no immediate way to tell the clients about it.  Instead, we had to design into the scanners a regular "keepalive" check.  This was a timer which would contact the server every half second to see if there were any updates the scanner cared about.

    This naturally leads to a couple more issues.  Firstly, this meant we had to do more work keeping track of our game states and player states, as different scanners would call in at different times.  There was also no guarantee of when a scanner would update next, so it was possible for scanners to receive updates at different times.  There were several instances during play where scanners temporarily lost network connection and missed updates like voting for upwards of 4-5 seconds.

    Theoretically this also wasted a bit of network bandwidth and put stress on the server, as every scanner was pinging home twice a second whether there were updates or not.  In reality though we never saw any degradation with just 8 scanners, and a stress test using Postman showed the server could process at least several hundred requests/second, so the 16-25 requests we were throwing at it weren't really an issue.

    Overall though, the biggest reason we went with REST was to give the students a real-life experience using it.  The vast majority of programming work out there today is web-based; it's something they'll be going into anyway.  A project like this taught them all how to build APIs, make GET/POST requests, and move data, while being a lot more fun than simply building out a forum board or accounting application :)

  • A couple other asides

    Professor Woody02/15/2022 at 10:12 0 comments

    There were two additional tools in the files which deserve a little mentioning.

    The first is an RFID scanner application. The idea was we were going to use it to scan the RFID tags to get their UIDs.  We'd then store the UIDs on the server in a simple table referencing the actual tag name.

    To be sure, the tag UIDs are stored on the server and work exactly like that.  Every time a scanner 'scans' an RFID, it calls the server with the UID to ask what the name of the tag is.  This way we could decouple the actual tags from the game code on the scanner - or even dynamically remap them without rebooting everything.  I'm not sure if the RFID scanner app is functional though.

    The second item is a small AutoDownloader ( script.  This was designed to delete all the files off the scanner (with option for exclusions) then download new ones from the server using the same REST calls we used for everything else.  

    It's fairly crude and wiping/rewriting the memory of the little ESP32's hundreds of times certainly isn't recommended in the long term.  But using it rapidly increased the speed at which we could prototype one - or multiple - scanners simultaneously.  

    In the time it took to copy the changed code to one scanner manually we could flash with this script to 4-5 prototypes, test, make changes, and reflash again.  It also centralised the code as the raspy server would just pull the main dev branch straight from Github, then everything would work off that copy.  

    This second item is fully functional and is in (and integrated into controller/ of the API)

  • Final status of the game

    Professor Woody02/10/2022 at 16:25 1 comment

    This project is complete and will no longer be updated (unless one of the team chooses to pick it up and work on it independently).  

    The game in it's current state works and is playable.  Specifically, the following features have been built:

    • Connection to the central server
    • Scanning of ID badges/stations/special tags
    • assigning of teams
    • playing of minigames
    • sabotages
    • murdering
    • voting
    • game winning/losing

    What was not implemented:

    • Rejoining of games in progress (I.E. if your scanner is turned off or loses wifi)
    • Ghosts

    What could be done better:

    • Code needs a major refactoring (very messy, work of a dozen people with varying skill levels in a bit of a rush)
    • 3d printed case needs a screen cover (too easy to see each other's screens over one's shoulders)
    • A written "rulebook" covering actions required by humans
    • Several minigames could do with tightening up/minor bug fixes.  One potentially locks you out of doing anything until a voting session starts

View all 3 project logs

Enjoy this project?



Similar Projects

Does this project spark your interest?

Become a member to follow this project and never miss any updates