An IoT lockbox for hybrid scavenger hunts.
Cipherlock is an IoT-based lockbox for hybrid scavenger hunts.
Cipherlock consists of three main components: the lockbox, the lockbox controller, and the game server. In a future version, a fourth key component will the LoRa gateway.
The lockbox is a 3D-printed treasure chest that cannot be manually opened from the outside.
Internally, the lockbox uses a spring-loaded latch to provide to hold the lid shut. The lockbox controller controls a servo motor which retracts that lid, allowing the box to open.
Magnets in the box's lid and base ensure that the lid opens automatically, once the latch is retracted.
The lockbox controller unlocks the box when it receives a command to do so from the game server. In its current implementation, the controller connects directly to the game server via a WebSocket. In a future version, this will be relayed through a LoRa connection between the lockbox controller and a LoRa gateway.
Outward, the game server provides REST API with several endpoints, one of which being POST /checkAnswer. A game spec file defines what type of answer is expected for a given lockbox (a.k.a. cache) and what answers are considered correct. When an acceptable answer is provided during a requet to the /checkAnswer endpoint, the corresponding lockbox receives an unlock command, causing the lid to open automatically. A single game spec may define an arbitrary number of caches, each with their corresponding lockbox and answer definition.
This repository contains the code for the following components of Cipherlock:
game-server: The web API that contains the core game logic, such as receiving player answers and triggering lockboxes to unlock.lockbox: The ESP32-based lockbox controller.lora-gateway: Not yet implemented.
- CAD files (not currently available to the public)
- Player and admin frontends (not part of this project; see Implementing a user interface)
- Basic ESP32 development board setup (see Flashing the Micropython firmware)
When setting up Cipherlock, it is recommended that you first complete the external tasks outlined below, before proceeding with the deployment of Cipherlock itself.