AWOL Box

The AWOL boxes are a type of reverse-geocache type device. The boxes consist of a motorized latch, GPS receiver, card reader, display, and a single exterior button. The device has several different modes, such as opening when the box reaches a target.

Overview

Hardware

The boxes use an ESP8266 as the main processor, which has just enough pins to do what I need it to do. This chip was picked mostly because of it's more powerful processor, larger amount of RAM, and more storage space compared to some of the smaller Arduino micros I've been using. As a side effect of this, the boxes have Wifi capability, allowing me to program the boxes even while still closed, with no physical connection between them. The filesystem means that I can store settings inside files inside the device, and don't need to re-upload firmware every time I want to change the target location. I have provided a web interface when the box's Wifi is turned on, so that all I need to program the box is a computer with a web browser, no special programs are required.

Settings

The boxes are programmed by a few configuration files stored on the device, so that one does not need to upload an entire new firmware if you need to change just one thing. Any item that might need to be changed is stored in a configuration file.

The boxes have three main nonvolatile variables that control the game.

• A "status" or "lock" variable that keeps track of whether the box is either locked closed or can be opened freely.
• A "credits" variable that tracks the number of credits
• A "target" variable, which stores settings such as what the objective is, where the target location is, what to display during an attempt, how many credits the attempt costs, etc.

There are also a few other "read only" files that store things like the box's ID number, the conversion from meters to whatever units you want, the open/close values for the latch servo, and the wifi password.

Files

Below is a table listing all files on the device. "Read only" files are files that are never written to by the box in operation, they can of course be changed when configuring it.

Filename	Read/Write	Discription
aconf.bin	R	Stores the servo open/close setting, ID number of the box, group bit of the box, and unit name and conversion from meters (Eg. "Tads" , 0.35486913 - Multiplying a value in meters by this will convert it to tads.)
bconf.bin	RW	Stores the current "solveMode" (whether the box is locked closed or it can be opened freely), the current target file number, and the number of credits.
targetn.bin	RW	Stores everything you need to know about the box's current objective. Only written to when settings are loaded from a card.
wifi.asc	R	Stores the Wifi SSID and password to connect to. When in Wifi mode, the box tries to connect to this AP, and if it can't find it, it will make it's own. This is so your computer can stay connected to the internet while still accessing the box on the same network.
splash.asc	R	Contains text that is shown on the LCD on boot, like "Wintercamp XLI"
log.bin	RW	When an attempt is begun, the box stores the GPS location of the box in this file. It also serves as the attempt counter, by measuring the size of the file.
rlog.bin	W	Similar to log.bin, but stores location and time when a target is reached. Also stores the target number, for identification.
log.kml	W	In the web-config page, you can generate this KML file from the targetn.bin files and the log.bin file, which can then be viewed in google earth.

Targetn.bin

The targetn.bin file is a configuration file that stores information about what the objective is, and what you need to do to reach that objective. When the objective is reached, it tells the box what to do next also. Each targetn.bin files has one objective, and it is in use only when working on that part of the puzzle. If the box is currently using target #15, it will load "target15.bin" and so forth.

Organization

The target files have four main variable types:

• Variables that define a reference quantity/location; eg. "15 tads", "3 credits", geo-coordinates of a location, etc.
• Variables that define what the objective is; eg. "When box is within [15 tads] of [a location], then success"
• Variables that define what to do when the objective criteria is not met; eg. what information to display on the screen and for how long
• Variables that define what to do after the criteria is met; eg. "Display a message for 15 seconds, then load target #12" or "Open the box, and say `You win` for 10 seconds"

Format

The format of the physical file is designed to closely follow the format of the cards, so I don't accidentally store more variables than the card can hold. The table below shows what is stored.

Location (bytes)	Variable name	Desciption
0-3	Latitude coordinate	IEEE 754 float of latitude.
4-7	Longitude coordinate	IEEE 754 float of longitude.
8-11	Radius	Radius - The intended distance between the box and the target coordinates. For example, the box can be programmed such that if the true distance between the box and the target is less than the radius, success is achieved.
12	frametime	Number of seconds to display information when success is not met. If success is reached within this time, the box executes the desired success routine. Otherwise, the attempt ends.
13	tgtmode	Target mode - defines what to do when the success condition is met. Valid values are: 0 - Do nothing 1 - Open the box, then load the target specified by nxtgt 2 - Load the target specified by nxtgt
14	nxtgt	Stores the number of the next target to be loaded. Used only when success is defined to do this by tgtmode.
15	dispmode	Display mode - defines what to display when the success condition is not met. Valid values are 0 - Display nothing (too evil to use) 1 - Display distance to target 2 - Display angle between direction of travel and vector to target, in degrees. An angle of 0 means you are heading right towards the target coordinates; positive angles means the target is counterclockwise of your direction of travel; negative angles mean the target is clockwise of your direction of travel.) 3 - Distance and angle to target coordinates 4 - Radius minus distance. Used in susmode 3 when inside circle.
16	wmsgTime	Time to display the win message. This operates independently of tgtmode or the success definition.
17	cost	Number of credits it costs to begin an attempt.
18	susmode	Success mode - Defines what is success. Valid values are 0 - Success is never met 1 - Success is always met 2 - If distance between box and target coordinates is less than radius 3 - If distance between box and target is greater than radius 4 - if current block is solved inside radius (block states changes to solved when condition is met, and target is solved when all enabled block points are solved.)
19	miscB	Miscellaneous variable. Not presently used.
20	miscC	Miscellaneous variable. Not presently used.
21 - 24	bspeed	IEEE 754 float not presently used. Could be used for storing speed.
25 - 57	wmsg	Win message. If wmsgTime is greater than zero, display this message for wmsgTime seconds.

log.bin

This file logs the GPS location and GPS time whenever the user begins an attempt. A couple other administrator test functions will log the GPS location to a file, turning the box into a GPS logger.

Data appears as a series of these

Location (bytes)	Name	Description
0-3	Latitude	IEEE 754 float - latitude coordinate
4-7	Longitude	IEEE 754 float - longitude coordinate
8	hour	Hours - GPS time
9	minutes	Minutes - GPS time
10	seconds	Seconds - GPS time

Operation

Home screen

The box is turned on, and it loads the current targetn.bin file. A "home" screen is shown to the user, which displays the current target number and the number of credits.

Attempts

When the user begins an attempt (by pressing the button once), the box checks if a GPS signal is available. If isn't, it will display a message and wait The user can cancel by pressing the button again, and no credits will be used. If it is, the box updates the credits value given the current credit cost defined by the current target. Then, it checks the success condition once a second, as often as the GPS data comes in. If the success condition is met, it does the success action. If it is not met, it displays something specified by the not-success action. If the success condition is not met within a certain amount of time, the attempt ends, and the box returns to home. However, if the box loses GPS signal during the attempt, it will pause the timeout timer and wait for a GPS signal. If the button is pressed at any time after the attempt has started, it will end it and return to the home screen.

If the box's number of credits is less than the cost for one attempt, the box will display "Not Enough Credits"