Please check to see if there are more recent set up instructions on my web site here:

https://www.seismicmatt.com/handshake-set-up-instructions/

I am slowly porting these instructions to the project GitHub page here:

https://hardwaremonkey.github.io/microbit_hand_shake/

This is generated using mkdocs with markdown and image files. I recently learned how to do this  from the series of short videos here:

https://calmcode.io/mkdocs/material-mkdocs.html

All the markdown and images needed to generate the instructions will be on the gh-pages branch of the GitHub repository. Then the instructions will be open source.

Please find a copy of the setup instructions from my website below.

Safety

The BBC micro:bit was designed to be safe to use in education with 11-12 year-olds, so has safety designed in.

The transmitter board is powered by two AAA batteries in a case. Normal safety practice should be followed with the batteries – keep them dry.

Parts

2 x BBC micro:bit boards

1 x AAA battery pack for a micro:bit board

1 x wrist holder – construction instructions below

1 x micro USB cable to connect the receiver micro:bit to the communications device.

I am testing an iPod touch 4G Sport Armband made by Tune Belt and an iPod classic holder made by igadgitz. Both of these work as a wrist holder for a microbit and battery pack.

 I made my own, picture below, before finding the two off-the-shelf solutions. I still think the one I made looks better. But you can save yourself a few hours by buying a ready-made solution.

Build details for the holder that I made are at the end of these instructions.

How to set up the system-summary

The transmitter micro:bit goes on your wrist, the receiver micro:bit is connected to your PC or laptop computer using a micro USB cable.

Each of the micro:bits needs different code loaded onto it. The hex files can be drag and dropped onto each micro:bit through a file explorer to program them.

The transmitter is shaken. This shake sends a signal to the receiver. This causes the receiver to send a signal to the computer through the USB port.

A piece of software running on the computer detects this message and sends a keystroke out. This keystroke can be used to control communication software running on the computer.

Hopefully, you can just plug the micro:bits into the Windows machine and they will be automagically detected. A folder called MICROBIT will appear in your File Explorer. Then you can drag and drop the .hex file containing the code for the micro:bit onto this folder and the board will load the code in about 10s, merrily flashing a little LED. Details below on what hex file goes where.

If you need more detailed instructions on how to connect a micro:bit to a Windows machine and how to load code onto it, please look at my blog post: https://www.seismicmatt.com/2020/04/27/connecting-the-bbc-microbit-to-windows-and-adding-code-to-it/

Go to the GitHub site linked at the top of the page. You can download each of the files detailed in the following sections by right clicking and doing ‘save-as’ or you can download the whole repository as a single zip file and unpack it on to your machine by clicking on the green ‘Clone or download’ button then selecting ‘Download ZIP’. See the picture below.

Each micro:bit needs to be programmed using a .hex file.

If you are interested, the code used to generate the hex file can be viewed in the Python script files, which end with a ‘.py’ suffix. You can ignore these .py files if you are just looking to get up and running as quickly as possible. These are included to enable anybody interested to be able to check the code and improve on it.

Connect the transmitter micro:bit to your computer.

The hex file for the transmitter micro:bit is called transmit.hex. This can be found in the transmit sub-directory on the GitHub site. I include the Python script (the .py file) used to generate the .hex file so anybody else can improve on it. You can ignore this .py file unless you are interested in looking at the code. Simply drag and drop the hex file onto the MICROBIT folder and it will load in about 10s, during which you will see an LED on the back of the micro:bit flashing.

Disconnect the transmitter micro:bit and connect the receiver micro:bit.

The code for the receiver micro:bit is called receive.hex. This can be downloaded by navigating to the receive sub-directory in hand_shake on the GitHub site, then right-clicking on the file and selecting ‘save as’. Drag and drop this onto the MICROBIT folder created when you connect the receiver micro:bit to the computer.

Program each of the micro:bits separately – only have one at a time plugged into your computer. Otherwise, the World will end. Probably.

The software that goes onto your computer is in the base folder of the GitHub directory. This stands for base station. I couldn’t think of a better name. This software monitors the attached receiver microbit for a trigger and then simulates pressing the F1 key on your keyboard. You can adjust the keystroke that is sent out when a shake is detected if you do not want to use F1. Details on how to do this are below.

Windows

The file you need is called base.exe which is in the base directory of the GitHub repository. This is an executable. To have this automatically run when the computer starts, it needs to be placed in Windows startup folder. To go to this folder, type shell:startup in the File Explorer, as shown in the screenshot below.

Place the base.exe file into the folder that shell:startup took you to. This file will automatically run when you start Windows.

Just double click on the base.exe program in a File Explorer to kick it off, or run it through a console.

The receiver micro:bit can be plugged and unplugged without crashing the base.exe program when it is running. You can start the base.exe program with the receiver micro:bit plugged in or not plugged in. If the receiver is not plugged in, the program will wait for it to be plugged in and then continue. This is called being ‘hot-swappable’ and nobody is more surprised than me that I got this to work.

Generating other keystrokes

By default, F1 key presses are generated by the base.exe program. Other keystrokes can be sent instead.

By starting the program by typing e.g.

base.exe -k "1"

when the system is triggered, a keystroke 1 will be sent instead of the default F1.

To see the help for the command line options, from a console in the same directory as base.exe is stored, type:

base.exe --help

This will display help for the command line options:

Usage: base.exe [OPTIONS]
 
Options:
  -k, --keystroke TEXT  Keystroke to send. Default is "F1". e.g.
                        --keystroke="1" or -k "1"
  --help                Show this message and exit.

As you move the transmitter microbit, you will see bright LEDs light and turn off. The harder you shake the board, the more LEDs will light up. The LEDs go off as the motion of the board slows down. See the picture below. If you look closely at the transmitter board, you will also see some faint LEDs. The number of faint LEDs stays the same as you move the board around. The number of faint LEDs lit shows the sensitivity of the board. The more faint LEDs there are, the lower the sensitivity, so the harder the board has to be shaken to cause a trigger to be sent to the computer.

The micro:bit has two buttons, labelled ‘a’ and ‘b’. You can alter the sensitivity of the system by using the buttons on either the transmitter or the receiver. Or both. This means that the transmitter can be in use and you can alter the shake detection threshold without having to interfere with whoever is using it.

Pushing the button labelled ‘a’ causes a ‘-‘ symbol to appear briefly on the transmitter’s LEDs. This makes it easier for a gentle shake to be detected. Each time you press the button a single faint LED will turn off and remain off and the sensitivity to a shake is increased.

Pushing the button labelled ‘b’ will make a ‘+’ symbol appear on the LED. This will make it harder for a gentle shake to be detected. Each time you press the button, a single faint LED will be lit and remain lit. You will need to shake the board harder to get it to trigger.

The micro:bit radio is set to use one of the 65,000 channel and group combinations available to it. Two micro:bit handshake systems could interfere. Fixing this interference requires changing a couple of lines of code in the transmitter and receiver scripts for one of the systems, to have it use a different channel or group. If you are using multiple handshake systems in the same area, send me an email and I will send out some code with a different channel and group configuration. Or, as the microbit is deployed to year 7 in the UK – ask a friendly 12-year old to do this! All of the code is on the GitHub site.