Skip to content

How to setup your own dongle

Jump to bottom
Timo Walraven edited this page Jan 25, 2024 · 3 revisions

Introduction

This is an explainer on how to set up the STEP dongle for yourself. Although it was intended to be easy to follow, some proficiency in command line interfaces would be recommended. It is mainly focussed on Windows users, but should be followable from other operating systems as well. For any questions, feel free to contact the STEP team or open an issue.

Requirements

To start this guide, please make sure your preparation meet these requirements:

shopping list 🛒

software 💾

other 🛜

  • Make sure you have access to a Wi-Fi network that both your machine and the Pi can connect to and that you can access the router's admin panel.

Setting up the dongles operating system

STEP uses a headless setup for the dongle. This means that there is no graphical interface. This makes the first setup a bit more tricky, but is more efficient during usage of the dongle.

1. Flashing the image

✅ checklist

  • The Micro-SD card is inserted in your computer.
  • The Micro-SD card is formatted and has no partitions. (you can check this with the Disk Management utility on Windows)
  • You have installed and opened the Raspberry Pi Imager.
  • You have internet access

Select the following options in the Raspberry Pi Imager:

  • Choose device: Raspberry Pi Zero (2)W
  • Choose OS: Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit)
  • Choose Storage: select your empty drive (for example: Drive (:E))

Now click next, you are now prompted if you would like to change the configuration. Change the following:

  • Fill the login details to your liking
  • Fill the network credentials for the network your computer is connected to.
  • Enable SSH

Now click on save and install the image.

2. Setting up serial mode

The Pi Zero (2)w can work in different modes. For STEP, the serial mode was chosen. To set this up, we need to make some minor changes to files on the Micro-SD card we just flashed. More on the modes can be found here.

Open up the drive in your file explorer and:

  • In the config.txt, append the following:
dtoverlay=dwc2
enable_uart=1
  • In the cmdline.txt, append the following directly after rootwait: 
modules-load=dwc2,g_serial
  • Make sure you saved and closed both files
  • Now safely remove the drive and insert it into the Pi
  • Insert the micro-usb cable to the Pi in the inner micro-USB port on the Pi. This is important because the other one is for power only.
  • Connect the Pi to your computer. The green light on the Pi should now indicate it's alive and should be rapidly blinking, indicating drive activity. One problem we encountered during development is that the light would stay solid green and the Pi would not boot. It turned out that the PNY micro-sd card was a low quality card, this was fixed by changing it for a Sandisk one.

Setting up STEP on the operating system

We now have a basic operating system running on the Pi. In order to run the STEP script, a few programs need to be installed and the script that sends the data to your computer need to be set up to run automatically when the Pi boots. We'll do this by creating an SSH connection to the Pi, so we can execute commands on the Pi.

1. Finding the dongle's IP and opening an SSH connection

In order to make the SSH connection, the dongle's assigned IP address must be found. This can be done in multiple ways. One of them is by logging in to your router/modem and check the connected devices:

  • Open CMD (win + r → cmd → enter, or search for 'command prompt' in the windows search menu)
  • Use the ipconfig command to search for the default gateway of your network. (e.g. 192.168.0.254)
  • Copy the address and paste it in your browser, you should now see a login screen of your router. ⚠️ following steps are highly manufacturer/model specific, experience could vary ⚠️
  • login to your router, default login details are often on the back of the router or can be found online.
  • navigate to a connected devices page and look for the IP address of a device with raspberrypi in its name. Copy/write down the address. ⚠️ if you cannot find the device, it's probably not booted correctly or Wi-Fi credentials aren't correct. You're now ready to connect to the Pi over SSH, please recall the username you configured earlier and the IP address.
  • re-open CMD (win + r → cmd → enter, or search for 'command prompt' in the windows search menu)
  • Execute the following command, where and need to be replaced by your username and IP respectively: 
ssh <USERNAME>@<IP>
  • enter the password you set earlier. If everything was done correctly, you should now be greeted by the home screen of the raspbian operating system. We will call this the terminal from now on.

2. Updating the Pi's software

You first need to update the Pi's default software. To do so, run the following commands sequentially. You can copy them and paste them in the terminal with a right click.

  • Check for updates:
    sudo apt-get update
  • Execute the updates: (you may be prompted if you'd wish to continue: type 'y' and press enter)
    sudo apt-get upgrade

⚠️ This can take a few moments

3. Installing and setting up Python

The STEP script uses Python. To set it up, run the following commands sequentially:

  • Install python3-venv: (virtual environment)
sudo apt install python3-venv
  • Install python3-dev: (development)
sudo apt install python3-dev
  • Make sure you're in the user's home directory:
cd ~
  • Create a new virtual environment:
python3 -m venv STEPenv
  • Activate the virtual environment:
source STEPenv/bin/activate
  • Update pip and install evdev package
pip install --upgrade pip
  • Install evdev:
pip install evdev
  • install pyserial:
pip install pyserial
  • Deactivate the virtual environment:
deactivate

4. Setting up serial connection:

To allow data being sent over serial to the computer, we need to give permissions to the port.

  • Execute this command to do so:
sudo chmod 666 /dev/ttyGS0

5. Getting the STEP files

To download the STEP script, GIT is used. Install git and clone the STEP repository:

  • Install git:
sudo apt-get install git
  • navigate to user's home directory:
cd ~
  • Clone the STEP repository:
git clone https://github.com/TimoWalraven/STEP

6. Automatically running the script.

To make the program start automatically once the USB cable is plugged in, we have to enable it as a 'service'.

  • Create an empty file for the service:
sudo nano /etc/systemd/system/step.service
  • copy this code into the file
[Unit]
Description=step execution
After=multi-user.target

[Service]
Type=simple
ExecStart=/home/pi/STEPenv/bin/python /home/pi/STEP/PI/step_pi_sender.py
Restart=always
RestartSec=1

[Install]
WantedBy=multi-user.target
  • Save the file with ctrl+x
  • Reload available services:
sudo systemctl daemon-reload
  • Enable the service:
sudo systemctl enable step.service
  • Start the service:
sudo systemctl start step.service
  • (optional) stop the service
sudo systemctl stop step.service

7. Connecting and pairing the WBB

Now that you have everything set up, connecting the Wii balance board only remains. We will use the Bluetootctl package for this. Please note that this step is a bit tricky, and won't always succeed in the first try. This is probably because of timing, which is explained further when relevant.

  • open bluetoothctl 
sudo bluetoothctl
  • Start searching for devices:
scan on

Now the Pi will continuously search for devices and they will be printed in the terminal.

  • Click the WBB sync button (tiny red button next to batteries) It will show up in the list and has a name that looks something like: Nintendo-RL-
  • Write down the MAC adress of the balance board. (e.g. 00:1F:C5:9E:F9:F5) ⚠️ This part will be the tricky part, sometimes the balance board asks for a pin. This is a bug which we suspect to be time dependent. You need to manage to execute the following three commands within one 'cycle' of syncing. To further elaborate: once you press the sync button the balance board opens itself for a few seconds to pair and connect. If you fail to connect within this cycle, it asks for a pin. If it does you need to remove the wbb with the remove <MAC> command. Good practice is to note the commands with MAC adresses so you can easily copy-paste them. ⚠️
  • Click the sync button
  • pair the WBB
pair <mac-adress>
  • trust the WBB
trust <mac-adress>
  • connect the WBB
connect <mac-adress>

The front button of the WBB should be solid blue, indicated it is connected.

  • turn off bluetooth scanning (does not turn off Bluethooth)
scan off
  • Exit out of bluetoothctl 
exit
Clone this wiki locally