Skip to content

Completely refactored to work with new PSMoveAPI Library #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
NatGrayYes wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Completely refactored to work with new PSMoveAPI Library #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
55347c2
oust2 for use with new psmove library
NatGrayYes Nov 29, 2025
95809a1
Upgraded for new PSMoveAPI and modern Pi OS
NatGrayYes Nov 30, 2025
7241f21
Revise Raspberry Pi OS installation steps
NatGrayYes Nov 30, 2025
9484cc5
clarified build step
NatGrayYes Nov 30, 2025
61a7b57
clarified dependencies step
NatGrayYes Nov 30, 2025
6bf962a
clarified instructions
NatGrayYes Nov 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
175 changes: 119 additions & 56 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,95 +1,158 @@
Oust
====
<sup>Also known as Candle Fight, Jonty Sebastian Joust, and "that game with the lights".</sup>
# Oust
Also known as Candle Fight, Jonty Sebastian Joust, and "that game with the lights"

A love letter to [Johann Sebastian Joust](http://www.jsjoust.com/), designed for playing outdoors at noisy festivals in the dark. All night long (all night).

## How It Works
The aim of the game is to keep your orb lit by holding it steady. If you move it too fast, the light goes out and you lose.

Hold yours steady while trying to make other players move their orbs too fast. You could:

* Make them flinch.
* Hit their controller.
* Wait for them to do something silly.

The winner is the last person whose orb stays alight


![Rpi Oust Setup](sandwich_box.jpg)


A long time ago on a boat far far away
--------------------------------------
## A long time ago on a boat far far away
When organising [Electromagnetic Wave](https://www.emfcamp.org/wave) in early 2013 we asked some of the [Wild Rumpus](http://thewildrumpus.co.uk/) organisers to run evening games on the boat. A very beta version of Joust was run on the deck to rave reviews.

Fast forward to 2015. We've taken Joust (in both beta and final versions) to [OHM](https://en.wikipedia.org/wiki/Observe._Hack._Make.) in 2013 and [EMF](https://www.emfcamp.org) in 2014. Every time the game runs all night with almost no supervision.

By this point the game has developed a bit of a following and people are actively seeking us out to play. But there are problems. Joust requires a laptop to run (meaning we need to be near a power supply and can't leave it alone), it needs speakers for the music (which we never have), and people have trouble understanding the gameplay without announcements and cues.

I went to [CCC](https://events.ccc.de/camp/2015/wiki/Main_Page) in 2015 prepared. We had 11 move controllers, three Raspberry Pi's, 46 Ah of portable batteries, and more bluetooth adapters than there are bluetooth channels.
I went to [CCC](https://events.ccc.de/camp/2015/wiki/Main_Page) in 2015 prepared. We had 11 move controllers, three Raspberry Pis, 46 Ah of portable batteries, and more bluetooth adapters than there are bluetooth channels.

Oust is the result. It runs on a Raspberry Pi 2/3, can run up to 8 controllers (maybe more), and is specifically designed for environments so loud sign language is required.
Oust is the result. It runs on a Raspberry Pi, can run up to 8 controllers (maybe more), and is specifically designed for environments so loud sign language is required.

It was playtested and tweaked extensively at CCC - at one point with a circle of approximately 150 people playing & watching. The longest game I recorded finished after 9 hours of continuous play.

How to Oust
-----------

## How to Oust
1. Turn the Raspberry Pi on.
2. Turn the controllers on.
3. Play!

No really how does one Oust
---------------------------
## No really how does one Oust
The game is designed to run on a Raspberry Pi hooked up to a honking great battery pack. There is no interface other than the controllers themselves.

If you were starting out from scratch this is what it would look like:

1. Install Oust on the Raspberry Pi, including the nasty bluetooth hacks (See below).
1. Install Oust on the Raspberry Pi.
2. Plug the Pi into your battery pack.
3. Connect each controller to the Pi in turn using a MiniUSB cable. When the controller goes white it has been paired.
3. Connect each controller to the Pi in turn using a MiniUSB cable. When the orb goes white it has been paired.
4. Turn on as many controllers as you want to play with.
5. Each player presses the trigger, and the game begins.
6. Optionally put the Pi & battery in a plastic sandwich box.

But what does the game look like?
---------------------------------
1. All the controllers are dark. As the players press the squishy trigger their controller lights up white.
2. When all the controllers are white (or someone presses Triangle) the controllers will vibrate, then flash red/yellow/green as a "get ready" signal.
3. Every controller turns a different colour and the game has begun.
4. The aim of the game is to force all the other players to move their controllers too fast, either by hitting the controller, making them flinch, or the other player doing something stupid.
5. If your controller is going too fast it'll flicker as a warning.
6. If you are knocked out, your controller goes dark and vibrates.
7. The last player standing has their controller flash a beautiful rainbow sequence, and all controllers vibrate to indicate the end of the game.
8. The game resets, people hand their controllers to other people to play. GOTO 1.

Amazing Features
----------------

## What does the game look like?
1. All the controllers' orbs glow dark orange to show that they're connected.
1. Each player pulls the squishy trigger to join the game, and their controller lights up white to show they're ready to play.
1. When all the controllers are white (or when someone presses START) the controllers will vibrate, then flash red/yellow/green as a "get ready" signal.
1. Every controller turns a different colour and the game has begun.
1. The aim of the game is to force all the other players to move their controllers too fast, either by hitting the controller, making them flinch, or the other player doing something stupid.
1. If your controller is going too fast it'll flicker as a warning.
1. If you are knocked out, your controller goes dark and vibrates.
1. The last player standing is the winner! And their controller flashes a beautiful rainbow sequence, and all controllers vibrate to indicate the end of the game.
1. The game resets, people hand their controllers to other people to play. GOTO 1.

## Amazing Features
* Instant setup
* Easy pairing
* Add/remove controllers to the game on the fly
* Battery checking button (Press circle)
* Secret goddamn-it-start-the-game button (Press the START button)
* Turn off controller button before game start (Press the SELECT button)
* Add/remove controllers to/from the game on the fly
* Battery checking button (Press ⭕️ CIRCLE)
* Secret "goddamn it start the game" button (Press START)
* Turn off controller before the game starts (Press SELECT or PS)
* "Ready, Steady, Go" start sequence to get players attention
* Going-too-fast warning
* Support for as many controllers as bluetooth interference will allow

How to install Oust from an image
---------------------------------
[@hdsjulian](https://twitter.com/hdsjulian/status/733990403075104768) has built a Raspbian image with Oust preinstalled and preconfigured, flash it in the same way you'd flash any other Raspberry Pi image: http://phinn.de/oustpi.img.zip (sha256sum: 7db3147ba2c7a2d8910a16c02eb7ed84424a5bdd39686bc30ea61b7820f99a8b)

How to install Oust Manually
----------------------------
1. Get a Raspberry Pi 2
2. Install Raspbian on the SD card
3. Checkout PSMoveAPI to the pi user's home directory (https://github.com/thp/psmoveapi)
4. Merge in this patch to fix compilation on the Rpi https://github.com/thp/psmoveapi/pull/184
5. `apt-get install swig python-dev bluez`
6. Build PSMoveAPI standalone (5.b here https://github.com/thp/psmoveapi/blob/master/README.ubuntu)
7. Copy [oust.py](oust.py) to /home/pi/psmoveapi/build/
8. `apt-get install supervisor`
9. Replace /etc/supervisor with the contents of [supervisor](supervisor)
10. Copy [scan_enable.sh](scan_enable.sh) to /home/pi/
11. Reboot the pi and pair your controllers!
## Setup and Installation
### Essentials
* Raspberry Pi 3B
* MicroSD Card
* 4x PS3 Move Controller (1st generation) [🛍️ CEX](https://uk.webuy.com/product-detail/?id=SP3MCON001)
* 1+ Mini USB cable for pairing the PSMove controllers * 1x Micro USB cable for powering Raspberry Pi
* 1x USB Power Supply >=2.5A (12.5W+)

**Beware: The PSMove controllers will only charge over USB when connected to a USB Data Port!** They should however charge ok on a PSMove controller dock that uses the two metal contacts instead of USB.

### Install Software on Raspberry Pi

1. Install the operating system on an SD Card, using the official [Raspberry Pi Imager](https://www.raspberrypi.com/software/) with these settings:
* **OS**: Raspberry Pi OS Other / Raspberry Pi OS Lite (64-bit)
* **Hostname**: oust
* **Username/Password**: oust/oust
* **Wifi**: connect to local network for setup
* **Remote Access**: SSH enabled
* **Raspberry Pi Connect**: Disabled
1. Boot Pi
1. SSH in `ssh oust@oust` or connect KVM to install stuff:

```
sudo apt update
sudo apt install git vim bluez
```
1. Install PSMove API
1. Download Current PSMove API and install dependencies

```
git clone https://github.com/thp/psmoveapi.git
cd psmoveapi
git submodule update --init
bash -e -x scripts/install_dependencies.sh
```
* This took surprisingly long.
* In theory a load of these dependencies can probably be removed, as we're not building all the products.
1. Build PSMove API.

```
mkdir build
cd build
cmake .. -DPSMOVE_BUILD_TRACKER=OFF
make
```
* If the above doesnt build, this is the script that comes with PSMoveAPI, but it builds loads more stuff than Oust uses. `bash -e -x scripts/linux/build-debian`
1. Change Bluetooth input settings to allow it to pair to PSMove controller.

```
echo -e "\n# Setting for PSMove to connect\nClassicBondedOnly=false" | sudo tee -a /etc/bluetooth/input.conf > /dev/null
tail -n16 /etc/bluetooth/input.conf
```

1. Install Oust

```
cd ~
git clone https://github.com/MattGrayYes/Oust.git
cd Oust
```

1. Check that Oust runs `sudo python oust.py`
* Pair at least one controller at this point to test it all works with bluetooth.
* Press `CTRL + C` to exit

1. Set up Oust in SystemD, so it auto-runs on boot.
1. Install the config file `sudo cp oust.service /etc/systemd/system/`
1. Start the service: `sudo systemctl start oust.service`
1. Take a sneak peek at the service `systemctl status oust.service`
* If Oust is running, the paired controller should pair and glow orange when turned on.
* You can also monitor the service live as it runs `journalctl --follow --unit=oust.service --lines=20`
* `CTRL + C` to exit.
1. If it all seems fine, enable the service `sudo systemctl enable oust.service`
1. Reboot `sudo reboot`
1. When it reboots, Oust should be running:
1. If you turn on a paired controller, it should glow orange
1. If you plug in a new controller, it should pair
1. To double check, log back in and look at the service status `systemctl status oust.service`
* It should be enabled and active/running


Things You Should Know
----------------------
* The Playstation Move controllers actually implement the USB 1.2 standard, which means they NEED a data connection to charge. Essentially, you must connect them to a computer to charge them, a wall wart won't do.
* Building PSMoveAPI is horrid. I'll publish debian packages soon.
* The Raspberry Pi has a number of problems. The main one is that the current kernel (or bluez) shipped in Raspbian is broken - as soon as one controller is paired and has an active data link, the bluetooth adapter receives a command telling it to disable connecting to any other devices. Fortunately I was camping with [ms7821](https://twitter.com/marksteward) and [gavan](https://twitter.com/gavanfantom) who are terrifying bluetooth experts and spent a happy afternoon with HCI packet dumps debugging this. [scan_enable.sh](scan_enable.sh) is the hilarious solution they came up with - once a second it pokes all the bluetooth devices and tells them to accept connections again.

Future Things I May Do
----------------------
* A pre-built bootable image for the Raspberry Pi (possibly USB bootable)
* Debian packages of PSMoveAPI for the pi
* A script that does all the install things
* Better support for more than 8 controllers
Loading