Keep Talking Or The Microcontroller Explodes (KTOME)

The Physical Build Project based on the game Keep Talking And Nobody Explodes

Project maintained by bcorwen Hosted on GitHub Pages — Theme by mattgraham

Dev blog

I’m currently making short update videos on progress on my Youtube playlist. It’s certainly much quicker to film/narrate what’s new than type up a new blog post! Check there for more up-to-date info, meanwhile a more detailed write-up will appear here going into much more detail.

Prev post: Communications (part 1): CAN

Next post: Coding The Timer and Widgets module

2021/02/06 - Communications (part 2): BLE

This is another long overdue update covering about August to November 2020.

On the subject of manual setup

As hinted at in previous posts, you can categorise modules into two groups: those that need manual setup and those which do not.

In the videogame, each bomb is randomly generated. You start a new game and are handed a bomb with random modules, and on those modules are random coloured wires / symbols / buttons etc.

There is a choice to be made on where to draw the line between the game being generated by the ESP32 and where it is built by the user. Other builders on the Discord server have different preferences as to where that line lies, but my approach is to have the computer do most of this generation. By taking it out of the hands of the user, that same user can enjoy a more random experience and not influence the gameplay (knowingly or subconsciously).

The flip side to having the computer generate the game is that there is more manual setup required. For a module such as password, the game generates a password and a list of characters to scroll through on the screen. This needs no manual setup as the ESP would just have to change what it shows on the screen during the game. However a module such as Keypad would need physical keys with the correct symbols attached to it before the game starts. This is an inconvenience which I believe is worth the downsides!

However, there is the question about how the ESP32 is going to inform the user which keys need to be attached to the Keypad module. While building the Arduino prototype, I started displaying much of the info to the serial monitor (a text window on the computer showing messages from the microcontroller). However, I knew this could not rely on an attached computer and may need a more physical solution. At that time, with my limited resources and knowledge, I used an LCD screen to display the relevant data. This was fine for the bare bones physical layout I had, but would be difficult to integrate such a useful display into the look of the bomb prop while keeping it as close to the original as possible. A random screen might distract a player! I had also thought about trying to double the screen up as the serial number display, however the LCD is also quite limited in what it can display.

Trying to show the Keypad symbols on an LCD. I used custom characters but it was still a challenge to easily make out the symbols!

Making use of the ESP32’s Bluetooth

As I was learning the ins and outs of the ESP32 by reading articles and project builds, I came across the ESP32 communicating with a mobile phone to interact with a user. After starting to become more comfortable with the operation of the ESP32, I thought I could write a custom Android app to create an interface for the ESP32 game setup - mirroring the game selection and configuration screen in the game.

The in-game menu to create a random bomb

BLE was quite a tricky area to dive in to, but credit to Juan Antonio’s very insightful range of tutorials which not only covered the ESP32 code but how to build the phone app.

I selected the website Kodular as it allowed free Android app creation, with a good selection of flexible features and a framework phone app which could allow debugging and alterations on the fly - this was great at tweaking the layout and getting immediate feedback or in fixing issues!

A screenshot of the Kodular visual code editor

Bluetooth Low Energy

So a little about how this works! Bluetooth Low Energy (BLE) is the newer alternative to traditional Bluetooth. Rather than a stream of data, such as with music streaming, BLE is for short, occasional messaging, e.g. for sending updates on heart rate from a wearable fitness band.

To set up BLE comms, one device is configured as a server with the others as clients which connect to the server. In KTOME, the Timer ESP32 is the server with the phone app acting as a client.

To send data, a service and a characteristic must be created. A characteristic is essentially storage for a value, and it will have a certain method of interaction (they could be read from, written to, cause a notification, etc). A service is simply a collection of characteristics.

Lastly, a message sent via BLE can be a maximum of 23 bytes. Again not large, but more than with CAN and with a little careful planning this is plenty!

How I used BLE for KTOME

The Timer ESP32 creates a service, and within that creates two characteristics: one set to read and one to write. These two characteristics allow the ESP32 to intitiate sending data to the phone and vice versa, rather than the app having to wait for the ESP to poll it in other to send a reply.

After setting up the BLE server, the Timer sits and waits. Without an app to co-ordinate with the user and allow setup, KTOME cannot proceed.

The phone must find and connect to the ESP for the ESP to continue. The ESP’s service has the name “KTOME” which the phone app can scan for to connect to the correct device.

As soon as they are connected, the ESP continues with its code. It uses CAN to scan for connected modules automatically and reports this back to the phone app by BLE.

The phone app moves to the “Game Manager” screen, where the connected modules are displayed and the user can setup features of the game, such as game length and hardcore mode (no mistakes allowed). Changes to the game length and hardcore toggle are relayed to the ESP.

The Game Manager screen of the app

The game cannot be started until manual setup is completed. When this button is pressed on the app, the Timer ESP begins to instruct other modules to generate a game. The Timer cycles through modules which are classified as modules needing manual intervention in their setup and requests further information (e.g. it will ask the Wires module which colours of wires are to be attached). The Timer will use BLE to update the app, which will display the wire colours. The user shall then attach the wires as instructed, confirm this with a button press on the app, and the Timer will continue through all manual setup modules until all are satisfied. Then the game is prepared and can begin.

The manual steup screen of the app

On game start, the phone app changes to reflect a readout of the game timer, number of strikes and number of defused modules (to help facilitate the players and provide spoiler-free game tracking). The Timer sends periodic messages to the phone app to update the timer, strike and defusal displays. The game can be aborted from this screen back to the Game Manager screen.

The game running and debriefing screens of the app

If the bomb is defused or explodes, the phone app is informed by the Timer, which displays a results screen. This mirrored the videogame’s debrief screen.

Unlike the CAN communication post, I will not go into details of the messages sent between the app and ESP32. Most are single characters which reference a certain action or event, and it’s probably quite easy to guess when these messages are sent from the high-level description above. E.g. Pressing the button to start a game on the app sends an “A” message to the ESP. When the game is lost, a message “z 3” might be sent to the app. ‘z’ meaning the game has finished, the number referencing the module responsible for losing the game, and these being separated by a space (a convenient divider given the functions available in Kodular).

If you want to see more, I’d recommend this video for a short run through of how the app controls the game, this earlier video for a more immature description but with more detail on the BLE messages, and finally this short one which includes the widget setup!

Prev post: Communications (part 1): CAN

Next post: Coding The Timer and Widgets module