M A S A R Y K U N I V E R S I T Y
FACULTY OF INFORMATICS
Orchestration of hardware devices
for outdoor games
B A C H E L O R ' S T H E S I S
Tomas Rohlinek
Brno, 2024
Declaration
Hereby I declare that this paper is my original authorial work, which I
have worked out on my own. All sources, references, and literature used or
excerpted during elaboration of this work are properly cited and listed in
complete reference to the due source.
Supervisor: prof. RNDr. Jiří Barnat, Ph.D.
Acknowledgements
I would like to thank my supervisor, prof. RNDr. Jiří Barnat, Ph.D., for his
guidance and support throughout the work on this thesis. I would also like
to thank RNDr. Jan Mrázek, for inspiring me to work on this project with
his many interesting games, Mgr. Petr Sedlář for his help with the game
design and his long-term support, as well as my friends who had to listen to
me talk about this project for the last two years.
Annotation
This thesis presents a system for creating and running outdoor games. The
system consists of a game server, a GUI for managing games, and a set
of device firmwares. The system allows for the definition of games using a
JavaScript-based API.
Keywords
games, outdoor games, JavaScript, IoT, ESP32
Contents
1 Motivation 1
2 Overview 2
2.1 Technology use cases in games 2
2.2 Game examples 3
2.2.1 Lights Out 3
2.2.2 Delivery Cars 3
2.3 Requirements 3
3 Design 5
3.1 Device categories 5
3.2 Communication 5
3.3 Devices 6
3.3.1 Device firmware 6
3.4 Game definition 6
3.4.1 Device class 6
3.5 GUI 7
3.6 Game server 7
4 Hardware 8
4.1 Devices 8
4.1.1 Lantern 8
4.1.2 Semaphore 9
4.1.3 Mock Button 9
4.2 Game server 9
5 Implementation 10
5.1 Communication 10
5.1.1 Communication structure 11
5.2 Code structure 14
5.3 Device firmware 14
5.3.1 Supporting libraries 14
5.4 Game management 14
5.4.1 Core libraries 15
v
5.4.2 Game definition 16
5.5 GUI 17
5.5.1 Used libraries 17
5.5.2 Layout 17
6 Examples 20
6.1 Color switcher 20
6.2 Lights Out 21
7 Evaluation 24
7.1 GUI 24
7.2 Game server 24
7.3 Device firmware 25
7.4 Game definition 25
8 Future work 27
A Attachements 28
B Running the software 29
B . l Simplified deployment 29
B.2 Building and running 29
Bibliography 32
vi
Chapter 1
Motivation
Games are essential to any outdoor event, whether a camp or a team-building
exercise. Not only do they add an element of fun, but they also act as practical
tools for teaching and learning. While traditional games like Tag, Capture
The Flag, and various sports are simple to organize and require minimal
effort from coordinators, there are more intricate games that demand larger
playing complex rules, and dynamic game mechanics.
Complex games often involve multiple locations with varied tasks that
can evolve as the game progresses, necessitating considerable personnel to
manage and execute. However, most events lack the human resources needed
to organize and facilitate such elaborate games, which is where technology
can step in to fill the gap. Besides simplifying the organization of games,
technology can also enhance the experience for players.
1
Chapter 2
Overview
Since 2018, work has been done at Helceletka [1] to incorporate technology
into their games at their events to alleviate the personnel requirements and
make the games more intriguing for the participants [5]. Everyday devices
such as laptops, kitchen timers, and similar are used. Custom devices [8] [9]
have also been developed for this purpose in previous works. However, they
all work only as standalone units, which limits their applicability.
This thesis aims to increase their potential by creating a system that
allows the control of all devices to form a cohesive game environment.
2.1 Technology use cases in games
There are several roles that devices can fill in a game. They are somewhat
fuzzy, as a single device could fit multiple roles.
Game stations
The most common and useful devices are game stations. These are stationary
devices that players interact with during the game. They can be used
to display status, serve as capturable control points, or dispense tokens.
Game objects
Unlike game stations, game objects are meant to be moved. Although not
technological, a prime example of a game object is the flag in Capture the
Flag. A technological example might be a key that players need to open a
virtual gate.
User tokens
The last role is a user token. They are used to identify a single user during
the game. They can be used to track the user's progress and keep their
2
inventory or score.
2.2 Game examples
To better demonstrate the system's potential, let us consider a few examples
of games that could be played using it. This will also help in defining the
requirements for the system.
2.2.1 Lights Out
A simple example of a game is a variation on the logical puzzle game Lights
Out [3]. The game consists of a square grid of lights that can be turned on
or off. When a light is pressed, it and its direct neighbors, those sharing an
edge with it, are toggled. The goal is to turn all the lights off.
Unlike the original game, this version has the lights spread across a large
area, such as a soccer field.
2.2.2 Delivery Cars
Delivery Cars is a simple game for multiple players that combines game
stations and user tokens.
Multiple stations are spread across the game area, each accepts one type
of cargo at a given time. Each player has a token showing what kind of
cargo they carry. If they come close to one of the stations that accepts their
cargo, they deposit their cargo and are given a new one of a different type.
The type of cargo a station accepts changes with each delivery or after a
long period without delivery.
The player who delivered the most cargo wins.
2.3 Requirements
There are several requirements that the system needs to fulfill to be useful.
Communication
The first and main one is the ability to communicate with other devices.
Without that, the above games could not be achieved. While this could be
done on a purely peer-to-peer basis for the games above, it is simpler and
more robust to have the communication centralized, with a single source of
truth regarding the game state.
3
Ease of setup
The system should need minimal setup from the user, if any. Ideally, the
user should only need to turn on the devices, select a game, place the devices
at their designated locations, and start the game.
Game control interface
The organizers need to be able to access the current game state and control
the game easily. The interface should be accessible on commonly used
devices, including smartphones and laptops.
Game library
A library of games should exist from which users can pick. The games in
the library need to be generic enough to apply to a wide range of uses.
User defined games
While most users will likely be using pre-defined games, some advanced
users might want to create their own. Therefore, designing and deploying
new games under the system should be user-friendly.
Documentation
The communication protocols and user interfaces should be documented well
enough for even first-time users to operate the system.
For advanced users, most of the games provided in the library should
also be well-documented to be used as a reference for custom games.
4
Chapter 3
Design
Before diving into the implementation, it is beneficial to provide a high-level
overview of the system, as well as define some crucial terms.
3.1 Device categories
The device categories mirror the previously defined roles of devices in games:
game stations, game objects, and user tokens. There is, however, one additional
category: the game server.
The game server is the central hub of the game. It is responsible for
running the game logic and facilitating communication between devices.
Unlike the other categories, there will only ever be one game server in a
game.
3.2 Communication
The system might use multiple communication technologies to cover different
ranges.
• Short-range communication - used for communication between user
tokens and game stations (BLE, NFC, IR, WiFi)
• Mid-range communication - used for most communications (WiFi)
• Long-range communication - used for communication with faraway
stations (GSM/GPRS, LoRa)
Other technologies might be used for mid-range communication, especially
with B L E and WiFi meshing capabilities of chosen hardware, see Section
4. WiFi was chosen for its simplicity and the possibility of using existing
infrastructure.
5
3.3 Devices
The main parts of the system are devices. They facilitate interactions between
the players and the game.
Each device is a physical object that can communicate with the game
server. They are defined by:
• unique id
• tag - a human-readable string that identifies the device type
• commands - a set of commands that the device can act upon
• events - a set of events that the device can emit
• state - a JSON-like object that represents the device's state
3.3.1 Device firmware
Each device is running a firmware customized to each device type. The
firmware is responsible for handling communication with the game server
and handling device-specific logic. It is written in the native language of the
device's microcontroller, in this case, C+-h
3.4 Game definition
The user provides the game definition in the form of a script. This script
is run in a sandboxed environment to prevent malicious code from affecting
the server.
JavaScript was chosen as the scripting language because it maps well to
the event-driven nature of the game. The other possible choices were Lua
and Python.
3.4.1 Device class
Device class is an abstraction over devices. It is defined by a state object
and set of events.
They are meant to represent all devices that have the same behavior
in the game. They can introduce additional state and events that are not
present in the physical devices, this helps store additional information used
by the game logic and improve compatibility across different device types.
An event handler can be registered on a device class for each event,
forming the game logic.
G
3.5 GUI
The GUI is web-based to make it accessible from most user devices. It is
static and uses a WebSocket to communicate with the game server, this
makes it possible to host the GUI on a separate server and even possibly
on the user's device. Because it is web-based, the language of choice is
JavaScript (TypeScript).
3.6 Game server
The game server is the central hub of the game. It can be run on a separate
server or as part of the GUI to allow for simulations of games without
additional hardware or server. Because of the need to run as part of the
GUI and therefore in a browser, the server is also written in JavaScript.
7
Chapter 4
Hardware
4.1 Devices
Two devices were chosen for initial implementation to demonstrate the sys-
tem.
4.1.1 Lantern
Lantern is an example of a game station. It has 60 R G B LEDs arranged in
a circle on the top, 54 R G B LEDs forming a ring around the device, four
doors that can act as buttons when open, and a touchpad on the top. It is
based on the ESP32 microcontroller and can communicate over WiFi and
BLE.
Figure 4.1: Lantern
8
4.1.2 Semaphore
Semaphore is a simple device that is primarily meant as a user token. It
has 12 R G B LEDs arranged in a circle and two buttons (left and right). It
is based on the ESP32-C3 microcontroller and can communicate over WiFi
and B L E .
Figure 4.2: Semaphore
These devices were chosen because they have been tested in the past
with self-contained firmware and have been proven to work well in a game
setting, for example, in [5].
4.1.3 Mock Button
Additionally, a virtual Mock Button device was created for testing purposes.
It is a simple device with a single button and a single R G B LED, that can
be used as pure GUI user input for the organizers
4.2 Game server
For the game server, a Raspberry P i 5 was chosen for its ease of use. It can
act as a WiFi access point and as a router, which is crucial for the game to
function.
9
Chapter 5
Implementation
5.1 Communication
The M Q T T protocol was chosen for real communication over WiFi for its
simplicity and reliability. It follows a basic publish-subscribe model, where
devices can publish messages to topics and subscribe to topics. It also supports
other more advanced features that this project will not use.
For simulations, the whole pub-sub system was mocked using a simple
in-memory implementation.
10
5.1.1 Communication structure
The messages used to communicate are not limited by the M Q T T protocol.
For this project, JSON messages are used. JSON was chosen for its ubiquity,
simplicity, and human readability.
Three types of messages are recognized by the system: introductions or
hellos, commands, and events.
For defining shapes of data structures, such as state definition, command
parameters, and event parameters, JSON schema is used.
Figure 5.1 shows the sequence of communication between the game server
and devices.
Device Broker GarneServer
=| Server startup |=
subscribe: "devices/+"
New device introduction
subscribe: "devices/<device id>/commands"
devices/^device id>
devices/^devi cej d=•
subscribe: "devices/^device idWevents"
Event on device
event: "devices/^device id^/events"
event: "devices/-=device_id=>/events"
Update device state based on the game logic
command: "devices/^device id=>/commands"
command: "devices/<:device_id=>/commands"
Device Broker GarneServer
Figure 5.1: Communication sequence
11
Introductions
Upon connecting all devices will send an introductory hello message to its
device topic, which has the form of devices/<device-id>. This message
contains the device ID, device tag, list of commands the device can handle,
and list of events the device can emit. Sample hello message can be seen in
Listing 1.
"tag": "Semaphore_v2.0.0#0.0.0",
"stateDef i n i t i o n " : •[
"type": "object",
"properties": •[
"leds": {
"type": "array",
"items": {
"type": "object",
"properties": -[
{ "type"
{ "type"
{ "type"
u g i i
"b"
"number" },
"number" },
"number" },
"minltems"
"maxltems" 12
},
"events": -[
"buttonClicked": {
"type": " s t r i n g "
"enum"
>
" i n i t i a l S t a t e "
"leds": [
i
[ " A " , "B"
{
ir^. n
u g i i
"b"
{
0
10 more times
ir-j- n
u g i i
"b"
"AB" ]
},
"commands": {
"updateState" : {
// state definition is dup
},
"shutdown": { "type": " n u l l " }
}
}
Heated here
Listing 1: Introduction message
12
Commands
Commands are used to control the device. The most common command
is the updateState command, which updates the device state, but other
commands can be defined as well, such as shutdown.
Commands are sent to a command topic for that device, which takes
the form of devices/<device-id>/command. They take a single data parameter,
which is validated against the JSON schema defined in the hello
message. For convenience, an array of commands can be sent in a single
message.
Listing 2 shows an example of a command message.
{
"command": "updateState",
"data": {
"leds": [
{
" r " : 255,
"g": 0,
"b": 0
},
// . . . 10 more times ...
i
" r " : 0,
"g": 0,
"b": 0
}
]
}
}
Listing 2: Command message
Events
Events are used to notify the system about an interaction, that occurred
on the device. They are sent to an event topic for that device, which takes
the form of devices/<device-id>/event. Events, same as commands, can
have a single data parameter, which is validated against the JSON schema
defined in the hello message.
Listing 3 shows an example of an event message.
i
"event": "buttonClicked",
"type": "event",
"sourceld" : "semaphore!.",
"data": "A"
}
Listing 3: Event message
13
5.2 Code structure
The project is split into two main parts, the device firmware and the game
management.
5.3 Device firmware
Since each device is completely different, instead of writing a monolithic
firmware, a library was created to allow for easy device definition, along
with a few sample implementations for the devices used in this thesis.
All used hardware devices are based on ESP32 by Espressif. For that
reason, the ESP-IDF framework provided by Espressif is used. The framework
provides C A P I but allows for programming in modern C++. For ease
of use, C++ was chosen instead of C.
5.3.1 Supporting libraries
To make the implementation of device firmwares more convenient, a set of
libraries was created to wrap the ESP-IDF APIs to provide a C++ interface.
Some of the libraries include: WiFi, M Q T T , and NVS (Non Volatile Storage,
key-value persistent storage).
5.4 Game management
The game management takes care of running the game logic and propagating
the game state to the devices.
Because most parts need to run in the browser as mentioned in the
Design chapter, the language of choice is JavaScript. However to make the
development more convenient and the resulting code easier to maintain,
this project will use TypeScript to write the code instead. TypeScript is
a super-set of JavaScript, which introduces static types to the dynamically
typed JavaScript. This helps prevent some of the most common errors which
occur when working with JavaScript. Before deployment, it gets compiled
back into JavaScript.
The game management code is split into four libraries. The Core library
contains most of the business logic of the system. The CLI library contains a
wrapper around the Core library to allow for the running of the game server
from a terminal on a server. The GUI library contains the implementation
of the browser-based GUI as well as a wrapper to make the game server
runnable in a browser, for simulations. The Devices library contains definitions
of devices used by the GUI for displaying and simulation purposes.
Figure 5.2 shows a simplified class diagram of the game management
libraries.
14
• start;)
5 pauseO
• reset()
• receive Eve nt{)
• jp I oadGame Definition;)
(C) Runtime
• QjickJSContext
o evalCode(code)
i connectQ
i disconnect;)
i subscribeToDeviceTopics[deviceId)
i sendHello()
15 end Command^
i sendEventQ
®i connects
> disconnect;)
> sendMessage;topic, message)
> sut>scribe{topic>
i on[event: ConnectionEvent, callback)
®ConnectionEvent
Connect
Disconnect
Message
(E) MQTTConnectioi
s MQTTCDnnection(jrl, usernamer password)
:> connectQ
:> disconnect;)
s sendMessage[topic, message)
s 5ubscribe;topic)
(c) MockConnection
= connect;)
= disconnect)
= sendMessage(topic, message)
3 subscribe(topic)
Figure 5.2: Structure of management classes
5.4.1 Core libraries
Core libraries are a set of utility libraries that contain most of the business
logic code.
Used libraries
The core libraries use some useful external libraries.
The main one is the M Q T T library which provides a connection to an
M Q T T broker. The connection can be made either directly over a socket,
which is useful for server-side connections, or through WebSocket which is
necessary for usage in the browser.
The second heavily used library is io-ts. It is an input validation library,
which automatically generates TypeScript types for convenience. Besides
input validation, the core libraries use this library to store runtime information
about state definitions of devices as well as data parameters of their
commands.
15
Communication library
The communication library handles communication between a broker and
devices, including the game server.
The Connection interface provides a common interface for both real and
simulated connections. MQTTConnection implements the Connection interface
and provides a connection to an M Q T T broker, while MockConnection
provides a simple in-memory implementation.
The Client class is a wrapper around the Connection interface. It provides
an A P I to send and react to commands, events and hello messages,
instead of generic messages.
Game library
The Game class is used to run user-provided game code. To the outside it
provides API, to control the game, react to events and add hooks for device
state updates.
To protect the system from arbitrary code execution exploits, the userprovided
game logic code needs to be separated from the rest of the system.
To achieve separation, the Game class internally uses QuickJS JavaScript
runtime written in C and run under WASM.
Server library
The Server class manages the game runtime and the connection to the broker.
It also keeps track of all the devices currently in the system.
16
5.5 GUI
As previously discussed the GUI is a web-based app for controlling and
simulating a game. 1
5.5.1 Used libraries
Besides the core libraries, the GUI uses few other libraries.
The main library used by the GUI is the React framework. React is
one of the most popular modern web development frameworks. It uses a
component-based approach to building web applications, which makes it
easy to build complex user interfaces.
In addition to React, Material-UI is used. Material-UI is a set of React
components that implement Google's Material Design. It provides a set of
pre-built components that can be used to build a consistent and visually
appealing user interface.
5.5.2 Layout
As can be seen from Figure 5.3, the GUI is split into three main parts: the
devices tab, the control panel, and the device board.
Figure 5.3: Graphical user interface
Devices tab
The devices tab shows a list of devices currently present in the system. It
allows for adding new virtual devices, either for simulation or as control
widgets for the game. Upon hovering over a device, its current state is
displayed in the form of a JSON object. To prevent the device board from
overcrowding, the devices tab allows hiding devices.
1
Current deployment can be found at https://tet.vzorek.com
17
Figure 5.4 shows the devices tab, with two devices present, one of which
has its state displayed.
Devices
semafor
Semaphore_v2.0.0#0.0.0
MockButton_vO.O.O#0.0.0
Figure 5.4: Devices tab
Control panel
The control panel serves two purposes. It is used to select whether the GUI
is running in simulated mode or should connect to an actual game server.
After a connection has been established it is used to control the game and
upload the game definition.
Figure 5.5 shows the control panel with a mock connection, while Figure
5.6 shows the control panel with a real M Q T T connection.
18
Control Panel
Connection
Mock , MQTT
Game Controls
START STOP
d UPLOAD FILE
Figure 5.5: Control panel with mock connection
Control Panel
Connection
Mock £ MQTT
URL
Username (Optional)
Password (Optional) &
C O N N E C T
Game Controls
START STOP
^ UPLOAD FILE
Figure 5.6: Control panel with real M Q T T connection
19
Chapter 6
Examples
To demonstrate how the games are defined, two example implementations
are provided.
6.1 Color switcher
The first one is an almost minimal game definition. The game waits for a
button press on a MockButton device. When the button is pressed, the RGB
LED on the device changes color, based on the previous color. The game
demonstrates the basic concepts of the system: state definition and event
handling.
20
const rgb = Types.type({
r: Types.integerInRange(0, 255),
g: Types.integerInRange(0, 255),
b: Types.integerInRange(0, 255),
}, 'Rgb');
const state = Types.type(-[ l e d : rgb }, 'State');
const ColorSwitcher = game.defineDeviceClass('colorSwitcher', s t a t e , {
buttonPressed: -Q,
});
ColorSwitcher.on('buttonPressed', (source, data, state) => {
console.log('Button pressed', source, data, s t a t e ) ;
const states = [
{ l e d : { r : 255, g: 0, b: 0 }}, / / red
i l e d : { r : 0, g: 255, b: 0 }}, / / green
i l e d : { r : 0, g: 0, b: 255 }}, / / blue
] ;
l e t newState;
i f ( s t a t e . l e d . r === 255)
newState = states [1]
else i f (state.led.g ===
newState = states [2]
else
newState = states [0]
255)
}):
game.updateDeviceState('colorSwitcher', source, newState);
game.linkDeviceTypeCcolorSwitcher' , ' MockButton_vO. 0. 0#0. 0. 0 ' ) ;
Listing 4: Color switcher example
6.2 Lights Out
The second example is the Lights Out game from the introduction. Two
implementations are provided: static and dynamic. The static implementation
uses hardcoded device IDs, while the dynamic version uses the first 9
connected devices. This example mainly demonstrates that a device's event
can affect other devices. As well as the different ways devices can be mapped
to the device classes.
21
const rgb = Types.type({
r: Types.integerInRange(0, 255),
g: Types.integerInRange(0, 255),
b: Types.integerInRange(0, 255),
}, 'Rgb');
const state = Types.type({ l e d : rgb }, 'State');
const Lamp = game.defineDeviceClass('lamp', s t a t e , {
buttonPressed: -Q,
});
const on = { l e d : { r : 255, g: 255, b: 255 }};
const o f f = { l e d : { r : 10, g: 10, b: 10 » ;
// 0 1 2
// 3 4 5
// 6 7 8
const toggles = [
[0, 1 , 3 ] ,
[0, 1, 2, 4 ] ,
[1, 2, 5 ] ,
[0, 3, 4, 6 ] ,
[1, 3, 4, 5, 7 ] ,
[2, 4, 5, 8 ] ,
[3, 6, 7] ,
[4, 6, 7, 8 ] ,
[5, 7, 8 ] ,
]
function toggle (id) -[
const o r i g i n a l = game.getDevice(id);
const newState = o r i g i n a l . s t a t e . l e d . r === 255 ? o f f : on;
game.updateDeviceState('lamp', i d , newState);
}
Lamp.on('buttonPressed', (source, data, state) => {
toggles[source].forEach(index => {
toggle(index);
});
});
game.createDevice( lamp', '0' ) ,
game.createDevice( lamp',
1
1') ,
game.createDevice( lamp', '2') ,
game.createDevice( lamp', '3') ,
game.createDevice( lamp', '4') ,
game.createDevice( lamp', '5') ,
game.createDevice( lamp', '6') ,
game.createDevice( lamp', '7') ,
game.createDevice( lamp', '8') ,
Listing 5: Lights Out static example
22
const rgb = Types.type({
r: Types.integerInRange(0, 255),
g: Types.integerInRange(0, 255),
b: Types.integerInRange(0, 255),
}, 'Rgb');
const state = Types.type({ l e d : rgb }, 'State');
const Lamp = game.defineDeviceClass('lamp', s t a t e , {
buttonPressed: -Q,
});
const on = { l e d : { r : 255, g: 255, b: 255 }};
const o f f = { l e d : { r : 10, g: 10, b: 10 » ;
// 0 1 2
// 3 4 5
// 6 7 8
const toggles = [
[0, 1 , 3 ] ,
[0, 1, 2, 4 ] ,
[1, 2, 5 ] ,
[0, 3, 4, 6 ] ,
[1, 3, 4, 5, 7 ] ,
[2, 4, 5, 8 ] ,
[3, 6, 7] ,
[4, 6, 7, 8 ] ,
[5, 7, 8 ] ,
]
function get Index (id) -[
return game.getDevicesByClass('lamp').findlndex(lamp => lamp.id === i d ) ;
}
function toggle (id) -[
const o r i g i n a l = game.getDevice(id);
const newState = o r i g i n a l . s t a t e . l e d . r === 255 ? o f f : on;
game.updateDeviceState('lamp', i d , newState);
}
Lamp.on('buttonPressed', (source, data, state) => {
console.log(game.getDevicesByClass('lamp'));
const ownlndex = getlndex(source);
const toToggle = toggles[ownlndex];
const devices = game.getDevicesByClass('lamp');
toToggle.forEach(index => -[
toggle(devices[index].id);
});
});
game.linkDeviceType('lamp', 'MockButton_vO.0.0#0.0.0');
Listing 6: Lights Out dynamic example
23
Chapter 7
Evaluation
Overall the system is functional and meets the requirements for the first
round of in-scale in-production testing, which will be happening this summer.
However, there are some issues and missing convenience features that
could be improved.
7.1 GUI
The GUI is functional and allows for the management of running games
as well as their simulation, without the need for additional client software,
or server in case of simulation. There are however features that could and
should be added to improve the usability of the system.
The main one is the ability to add custom devices to the GUI. As it
stands now only the two device types, Semaphore, Lantern as well as an
additional Mock Button are supported. Ideally, the user would be able to
define their own devices and especially their graphical representation in the
GUI. For now, this feature was not implemented due to fear of potential
security related issues with user-provided code being executed.
The GUI and the game server allow for changing the game definition to
change mid-game, which is useful for making quick adjustments on the fly.
However, these changes need to be made off-site and then uploaded to the
server. It would be better to provide the user with the ability to modify the
game code in the GUI itself.
7.2 Game server
The game server works as specified, with some minor issues, or enhancements
that could be made.
The biggest issue from a user standpoint, is the volatility of the game
state. If the server crashes, or is restarted, the game state is lost. This
could be mitigated by adding a database to the server, which would store
24
all the messages that were sent during the game. Based on these messages,
the game state could be reconstructed at any time. This would also allow
for post-game analysis of the game, which could be useful for debugging, as
well as for pedagogical purposes.
7.3 Device firmware
The two provided game firmwares work as expected. They can connect to
a known WiFi network and game server. There is however yet a method
to change the server address, or the WiFi network without re-flashing the
device.
The solution is partly implemented but has not been introduced to the
firmware yet because of safety concerns. The dynamic server address is
implemented using mDNS technology which allows for the automatic search
of specific services on the network. This would allow the device to find the
game server on the network without the need for a static IP address.
The dynamic WiFi network choice is designed to work using provisioning
over B L E . Upon boot, the device would look for the game server over B L E .
If found the server would send the connection parameters to the device. This
would allow for mass reconfiguration of devices as well as potentially using
existing on-site network infrastructure for the game.
Both features have a high potential for introducing security vulnerabilities,
which is why they were not implemented in the first version of the
firmware.
Since the communication to the game server will inevitably face some
latency issues, the firmware is designed to use Jaculus in the future to run
user-defined event handlers on the device itself. Jaculus is a JavaScript
runtime for embedded devices by Petr Kubica. [2] This allows for faster
response times than if the handling was done solely on the server, which is
necessary for user feedback, such as haptics, animations on button presses,
etc. It also allows offline functionality when the devices are not connected
to the server, which is most useful for user tokens.
7.4 Game definition
The game definition was tested with people from Helceletka, who are versed
in the design of outdoor games and also have some basic programming knowl-
edge.
The feedback on the game definition style was positive, and the learning
curve was minimal. Both testers however expressed preference for a more
visual way of defining the game. Similar to the Scratch [7] programming
environment, where the user would drag and drop blocks of code to define
the game. This was expected and is planned for the future development of
25
the system. The current textual definition was designed to map well to this
future feature.
26
Chapter 8
Future work
The work on this project is not finished and will continue in the future.
As mentioned in the previous chapter many features could be added to the
system to improve its usability and functionality. This chapter will outline
some of the planned features and improvements.
Most of the features which are coming in the near future were already
mentioned in the previous chapter. The main two are the graphical programming
environment for defining games and runtime provisioning of device
configuration. There are however other features planned, that when
implemented will make the system more user-friendly and powerful.
Game library
For simplicity, most users will not need to define their games but rather use
games that are already defined. For these users, a library of games will be
provided. This library will contain community-contributed games, these can
be used either as they are, or as a base for further modification.
Additional hardware
Work is also underway on new hardware devices. Such as a new version of the
Lantern, which will have long-range communication capabilities using either
LoRa or GPRS. There are also plans for support for other devices created
by RoboticsBrno [6] and Vzorek, such as the Logic [1] game console.
27
Appendix A
Attachements
All source code written for this thesis is available in the attached zip archive.
The archive contains the following directories:
• sw - The source code for the server and the client.
• fw - The libraries used in the firmware and sample implementations of
the firmware.
The source code is also available on GitHub at https://github.com/
VZOREK/tet
The deployed version of the client GUI can be found at h t t p s : / / t e t .
vzorek.com
28
Appendix B
Running the software
All of the software, the parts meant to run on the server, or in the browser
are developed in TypeScript and run in Node.js or deployed to a webpage.
B.l Simplified deployment
The requirements for running the server are:
• Docker
• Docker-compose
Ports 1883 and 9001 must also be available on the host machine. A
script run-server. sh is provided. It will check the availability of the ports
and start the server and broker using the docker-compose file.
B.2 Building and running
If you want to configure the server to use a different broker, you can run the
server directly. Or if you want to build the client for deployment, you can
do that as well. For both, you will need to have Node.js installed. To build
or run any part of the project follow these steps:
1. Enter the sw directory of the project.
2. Run npm install to install all the dependencies.
3. Based on the part you want to run, choose one of the following:
To run the server, run npm run c l i .
To build the client for deployment and preview it on a built-in
development server, run npm run gui.
To build specific parts of the project, please refer to the package. j son
file.
29
Figures
4.1 Lantern 8
4.2 Semaphore 9
5.1 Communication sequence 11
5.2 Structure of management classes 15
5.3 Graphical user interface 17
5.4 Devices tab 18
5.5 Control panel with mock connection 19
5.6 Control panel with real M Q T T connection 19
30
Listings
1 Introduction message 12
2 Command message 13
3 Event message 13
4 Color switcher example 21
5 Lights Out static example 22
6 Lights Out dynamic example 23
31
Bibliography
[1] Helceletka - středisko volného času. "Helceletka - středisko volného
času, příspěvková organizace". URL: https://www.helceletka.cz/
(visited on 05/14/2024).
[2] Petr Kubica. Jaculus: Approachable Programming of Embedded
Devices via Javascript [online]. Bakalářská práce. SUPERVISOR :
Jan Mrázek. 2023 [cit. 2024-05-20]. URL:
https://is.muni.cz/th/xf5wo/.
[3] LightsOut. Sven van Huessen. URL: h t t p s : / / l i g h t s - o u t . s v e n v h . n l
(visited on 05/21/2024).
[4] Logic. Robotárna - Helceletka - středisko volného času, příspěvková
organizace. URL: h t t p s : / / l o g i c . r o b o t i k a b r n o . c z / (visited on
05/21/2024).
[5] Karolína MIKESKOVÁ. "Využití moderních technologií v táborové
pedagogice [online]". SUPERVISOR: Mgr. Pavla Vyhnálková, Ph.D.
Diplomová práce. Univerzita Palackého v Olomouci, Pedagogická
fakulta Olomouc, 2022 [cit. 2024-04-29]. URL:
https://theses.cz/id/iOohyf/.
[6] RoboticsBrno (RobotikaBrno). Robotárna - Helceletka - středisko
volného času, příspěvková organizace. URL:
https://robotikabrno.cz (visited on 05/21/2024).
[7] Scratch - Imagine, Program, Share. Scratch Foundation, URL:
https://scratch.mit.edu/ (visited on 05/21/2024).
[8] Tomáš VAVŘINEC. "BlackBox [online]". SUPERVISOR: Mgr.
Miroslav Burda. Středoškolská odborná činnost. Střední průmysloá
škola a Vyšší odborná škola, Brno Sokolská, příspěvková organizace,
2021 [cit. 2024-05-14]. URL:
h t t p s : / / p r i h l á š k a . s o c . c z / a r c h i v 4 3 / g e t W o r k / h a s h / 9 4 1 a 4 8 4 c -
989a-lleb-acaf-005056bd6e49.
32
Renata ZEMANOVÁ. "Univerzální modul pro podporu týmových her
[online]". SUPERVISOR: Pavel Šteffan. Diplomová práce. Vysoké
učení technické v Brně. Fakulta elektrotechniky a komunikačních
technologií. Ústav mikroelektroniky, 2023 [cit. 2024-05-14]. URL:
http://hdl.handle.net/11012/210145.
33