circuitpython_cpb-quick-draw-blueflash-woodentable-2000x1500-iii.jpg
Quick Draw Duo played on two Circuit Playground Bluefruits with external audio.

This project is a variant of the Circuit Playground Quick Draw game for a pair of Circuit Playground Bluefruit (CPB) boards using CircuitPython. Bluetooth Low Energy (LE) is used to exchange information between the boards. This means you can play the game wirelessly!

An additional CircuitPython program can be used to measure and compare visual and auditory reaction times. This can run on either a Circuit Playground Express (CPX) or CPB board.

Thank-you to Carter Nelson for the original game and Megan, Izzy, Elsa and Matilda for help in testing the new game.

The two CPB boards require the latest 5.x version of CircuitPython.

Parts

You will need two each of the following parts:

Circuit Playground Bluefruit - Bluetooth Low Energy

PRODUCT ID: 4333
Circuit Playground Bluefruit is our third board in the Circuit Playground series, another step towards a perfect introduction to electronics and programming. We've...
OUT OF STOCK

3 x AAA Battery Holder with On/Off Switch and 2-Pin JST

PRODUCT ID: 727
This battery holder connects 3 AAA batteries together in series for powering all kinds of projects. We spec'd these out because the box is slim, and 3 AAA's add up to about...
OUT OF STOCK

You will need a good USB data + power cable to program things:

USB cable - USB A to Micro-B

PRODUCT ID: 592
This here is your standard A to micro-B USB cable, for USB 1.1 or 2.0. Perfect for connecting a PC to your Metro, Feather, Raspberry Pi or other dev-board or...
$2.95
IN STOCK

Game Design

circuitpython_1280px-Duel_between_Aaron_Burr_and_Alexander_Hamilton.jpg
Duel between Vice President Aaron Burr and Alexander Hamilton in 1804. Engraving from the book "Our Greater Country being a Standard History of the United States".

The design of the game is very similar to the original with a few additions below marked with the † symbol. The additions are needed to synchronise the two CPB boards and exchange reaction times between them. There are also ten rounds to make this more fun although this doesn't strictly make sense for a duelling game!

The communication protocol between the two boards requires a different role is assigned to each board. This is set using the two-position switch on the board, i.e. the two boards must have the switch in different positions. The player's "draw" button is set to the button on the side the switch is set to.

Game Logic

  1. Turn off all of the NeoPixels.
  2. Determine the communication delay between the boards.
  3. Synchronise the boards.†
  4. Wait the determined (random) countdown time.
  5. If a player presses a button during this time, they drew too soon (misdraw).
  6. Once the countdown time has elapsed, turn on all of the NeoPixels (white).
  7. Wait for the button presses and exchange reaction time data between boards.†
  8. Look for the first (quickest) button press.
  9. Whichever button was pressed first is the Quick Draw winner.
  10. Repeat to step 3 until ten rounds have been completed.†
  11. Display a personalised summary of wins/misdraws on the NeoPixels.†

The exchange of data at step 7 can cause a delay compared to the original single board game. The winner cannot be determined until each board has received the data from the other board.

The winner at step 9 introduces a new colour (amber) to represent the unlikely outcome of both players simultaneously pressing their buttons.

Delay Calculation and Synchronisation Protocol

Sending data from one board to another takes a certain amount of time. If one board sends a "go now" command to another then the sender does not know when the receiver has received and processed that command. The receiver could send a reply but the same problem exists whereby the sender of the reply does not know when it has been received and processed. Measuring the transmission time including the time to receive and parse the data facilitates good synchronisation between the boards. This is one element of the Network Time Protocol (NTP) which can be used to distribute accurate time from reference clocks to computers and devices across the globe.

The send time on its own cannot be measured by the sender but the time to send and receive an immediate reply can be measured by the sender. If the network propagation and processing are symmetric then exactly half of this round-trip time (rtt) represents the time for the sender's data to propagate and be processed with the the other half representing the time for the receiver's reply to propagate and be processed.

The diagram below shows how the rtt measurement operates. Time progresses downwards in the diagram.

circuitpython_cpx-quick-draw-ping_for_rtt-protocol-v3.png
Sequence diagram showing how round-trip time is measured between CPBs.

For comparison, the approach is the similar to how ping works using the ICMP echo service. The traditional TCP/UDP echo service is another similar, higher-level service.

The asymmetric roles for the two boards in the measuring process are commonly referred to in computing and electronics as master and slave. In this example only the master is measuring the rtt but it then passes the value to the slave in subsequent packets. A simple way to set the role (or any boolean quantity) is to use the two-position switch on the CPB board.

In Bluetooth LE terminology, the two devices are a central device which connects to a peripheral device. This also gives the boards different roles in terms of a client/server model.

An approximate, but reasonably accurate, send time can be calculated from the measured round-trip times. This duration can then be used by one board to compensate for the send time and this allows the two boards to be synchronised, enabling the game to start on each board at the same time.

circuitpython_cpx-quick-draw-barrier-protocol-v2.png
Sequence diagram showing how CPBs are synchronised before each game round.

The procedure name used in the design is barrier, a reference to a type of synchronisation used for multi-threaded applications. This procedure aims to complete at the same time on each CPB board causing the subsequent code on each to execute near simultaneously. In this case, the aim is to be within a few milliseconds of each other. If the player is reacting to their own white NeoPixel flash then they do not have to be perfectly synchronised.

The staccato nature of Bluetooth LE communication (see diagram in GATT Transactions) is not accounted for in the synchronisation technique and this is one factor reducing its accuracy.

In this design, the same type of messages are used by the request and the response for simplicity.

A message which always elicits a reply message is often referred to as a request and response. This style of interaction in this protocol could also be regarded as a remote procedure call (RPC).

CircuitPython on Circuit Playground Bluefruit

Install or Update CircuitPython

Follow this quick step-by-step to install or update CircuitPython on your Circuit Playground Bluefruit.

Click the link above and download the latest UF2 file

Download and save it to your Desktop (or wherever is handy)

Plug your Circuit Playground Bluefruit into your computer using a known-good data-capable USB cable.

A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.

Double-click the small Reset button in the middle of the CPB (indicated by the red arrow in the image). The ten NeoPixel LEDs will all turn red, and then will all turn green. If they turn all red and stay red, check the USB cable, try another USB port, etc. The little red LED next to the USB connector will pulse red - this is ok!

If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!

(If double-clicking doesn't do it, try a single-click!)

You will see a new disk drive appear called CPLAYBTBOOT.

 

 

 

Drag the adafruit_circuitpython_etc.uf2 file to CPLAYBTBOOT.

The LEDs will turn red. Then, the CPLAYBTBOOT drive will disappear and a new disk drive called CIRCUITPY will appear.

That's it, you're done! :)

CircuitPython

Libraries

Once you've gotten CircuitPython onto your Circuit Playground Bluefruit boards, it's time to add some libraries. You can follow this guide page for the basics of downloading and transferring libraries to the board.

Libraries for Quick Draw Duo

From the library bundle you downloaded in that guide page, transfer the following libraries onto the two CPB boards' /lib directories:

  • adafruit_ble
  • adafruit_bluefruit_connect
  • adafruit_circuitplayground
  • neopixel.mpy

Libraries for Reaction Timer

From the library bundle you downloaded in that guide page, transfer the following libraries onto the CPB (or CPX) board's /lib directories:

  • neopixel.mpy

Development Testing

During development, the Quick Draw Duo application was tested on CPBs using CircuitPython 5.0.0-beta.2 with libraries from the adafruit-circuitpython-bundle-5.x-mpy-20200107.zip bundle. It should work on subsequent versions, the latest version is recommended.

The Reaction Timer code was tested on a CPX using CircuitPython 4.1.2 and on a CPB using CircuitPython 5.0.0-beta.2. The libraries were from the adafruit-circuitpython-bundle-4.x-mpy-20200107.zip and adafruit-circuitpython-bundle-5.x-mpy-20200107.zip bundles, respectively. It should work on subsequent versions, the latest version is recommended.

Reaction Times

circuitpython_Thorpe-FabreThorpe-Neuroscience-Seeking-categories-in-the-brain-monkey-visual-latency-estimate.jpg
Estimated processing flow and minimum-average latencies in a monkey brain from Science Vol. 291 2001: Seeking Categories in the Brain. Simon J. Thorpe, Michele Fabre-Thorpe.

The time to react can be termed a response time composed of:

  1. a reaction component which will vary depending on many factors including the type of stimulus, the complexity of recognition and the complexity of decision making and
  2. a movement component.

In this guide, the term reaction time is used for the total. The movement time is expected to be low for pressing a touch pad or a button.

The diagram above shows some of the processing in a monkey brain with an estimation of the connectivity and minimum-average latencies in milliseconds (ms). This diagram may be familiar from the Stadia Streaming Tech: A Deep Dive (Google I/O'19) which takes it and misrepresents it as human and changes the meaning and value of the times.

Movement Time

A prototype of the Reaction Timer used a touch pad for input. A high-speed video revealed that a typical finger movement took 20-30ms. This may be partly because a cautious user needs to carefully hover about 3-4mm to avoid getting too close and accidentally triggering the capacitive input.

Frames 3-10 (234fps) showing finger movement time circa 29ms.

The input was changed to the right button to allow the user to rest their finger on the button and reduce the travel distance.

Measurement Platform

There are many reaction timing programs including ones that run in the browser. A typical, modern desktop computer is unfortunately not the best platform for measuring reaction times. Dan Luu has studied this and published a list with a great write-up on his computer latency page. His tests measure the time from a keyboard press to the character appearing on screen. The Apple IIe from 1983 is the current winner! The page explains the elements of this latency from the keyboard to the operating system (o/s) to the screen. There is also another page dedicated to keyboard latency which discusses travel time and debouncing.

For basic reaction timing, this explains why the cheapest microcontroller board with an LED is superior to an expensive computer with a keyboard, general purpose operating system and an LCD screen.

When CRT computer displays were superseded by TFT LCD panels the refresh rate standardised from around 50-90Hz to 60Hz. This means that a modern desktop computer only displays a new image every 16.7ms and many tablets and smartphones have a similar limitation. Television models can vary in their refresh rates but often have added latency from additional image processing. This can sometimes be minimised with a "game mode" setting.

LCD displays also have a significant response time. The small PyGamer's screen can be seen below taking around 6 frames (26ms) to reach full brightness for a red letter A.

Frames (234fps) showing LCD response time on PyGamer 1.8 inch TFT LCD.

Most computer displays would be slightly better than the PyGamer's screen but there is no standard way to measure and summarise the response time. Some caution is required when comparing manufacturers' published numbers. Blur Busters have some interesting techniques to visually compare displays.

Latency in all its forms is an important factor in games. particularly fast-paced, distributed, multi-player games. Linus Tech Tips conducted a set of tests on 60, 144 and 240Hz refresh rate displays to see how frame rate affects the gaming experience. This also included some simple reaction time tests using a mouse and reacting to a (visual) red/green banner. The summary of their results is shown below.

circuitpython_linustechtips-displayfps-test2-reaction-times-dodgystddev-squashed43.png
Linus Tech Tips PC-based simple reaction time test results exploring effect of display refresh rate.

In the video there is mention of "run them until we see statistical convergence" - for a basic reaction time test, this sounds like cherry picking of the test results. This explains the low but plausible mean (AVG) reaction times. The standard deviation (sd) numbers look less plausible based on calculating sd from the low values actually shown in the video (sd=15.7ms) and from trying to reproduce low sd results for a visual stimulus.

On a similar theme, the reaction times for the finalist sprinters from the World Athletics Championships are shown below. These particular results are highly selected in two ways: the elite nature of the athletes; and their success in reaching the final. The graph starts at 0.1 seconds (100ms) because IAAF rules regard lower values as impossible, i.e. false starts. These results cannot be directly compared to the previous visual results as athletics uses sound to start the race (from equidistant speakers) and pressure from the starting blocks.

circuitpython_reaction-times-elite-sprinters-finalists-tonnessen-haugen-shalfawi-fig3-43squashed.png
Reaction Time Aspects of Elite Sprinters In Athletics World Championships: mean reaction time and 95% confidence interval of the finalists' reaction time development through competition (2003-2009). Copyright National Strength and Conditioning Association.

Some results from the Reaction Timer in this guide are shown on the next page.

Reaction Timer Results

circuitpython_M75-Rifling-Adafruit-Circuit-Playground-Bluefruit-00CPB.jpg
Circuit Playground Bluefruit over M75 canon barrel, photograph by Petar Milosevic.

CPX Results

This is a set of graphs showing the results from various trials on a Circuit Playground Express. The graphs only show values between 0ms and 450ms. Any values less than 100ms are not used in the calculations for arithmetic mean and sample standard deviation (sd). The graph on the right shows the same data in the form of a violin plot. This shows the distribution and provides some indication if there are values above 450ms.

The test conditions vary wildy - these are described in the title on each graph. The degree of practice by the test subject varies too. The later tests were conducted with a button rather than the original use of a touch pad. These three factors make comparisons between the test subjects hard.

Graphical summary of results from Reaction Timer running on a Circuit Playground Express.

See results for the individual graphs.

Conclusions

  • Reaction to an auditory stimulus is faster than a visual one - this is a common and well-known result. The variance may also be less but more data is needed to prove this.
  • Minimum reaction times do not vary considerably with age but very young children may struggle with consistency. 
  • Auditory reaction time decreases with increase in background noise even when there are no sounds which mimic the test sound.
  • The auditory reaction time test is much harder if another test is being performed at the same time even if the sound's pitch is different.
  • The absence of a penalty for false reactions probably decreases reaction times but this was not studied explicitly.
  • Distribution does not follow the normal distribution reducing the significance of the mean. It's generally asymmetric unless the subject can maintain a very high level of attention during test.
  • The movement time appears to be less for a button compared to cautious use of a capacitive touch pad.
  • Very tempting to cherry pick results and discard slow times leading to a form of sampling bias.

Going Further

Ideas for Areas to Explore

Quick Draw Duo

  • Add some winning and losing sounds.
  • Use the accelerometer to change the game to one with a physical draw.
  • Find some other uses for a pair of synchronised CPB, e.g.  light shows, stereo/spatial audio playback.
  • Technical challenge 1: increase the robustness of the communication, e.g. make it recover from transient connectivity issues; match request and response with a suitable identifier.
  • Technical challenge 2: understand and set the connection interval for Blutetooth LE GATT transactions and factor this into the design of the board syncronisation process.

Reaction Timer

  • Add a cheat detector to the reaction timer to highlight impossible times and early presses.
  • Use the NeoPixels to show the reaction time graphically.
  • Increase the complexity of the visual (e.g. different colours, odd vs even) and auditory (e.g. different pitches) stimuli to investigate the additional delays from discrimination.
  • Investigate tactile reaction time with some sort of actuator controlled by the CPX/CPB board.
  • Examine any effect of using peripheral vision and lower brightness settings on reaction time.

Both

  • Add an announcement of each time or the fastest time using sound samples for each digit.
  • Independently verify the reaction timing - many smartphones offer high fps video recording in the form of a slow motion mode.

Related Projects

Further Reading

 

This guide was first published on Jan 20, 2020. It was last updated on Jan 20, 2020.