From a3f634b688d6b00d5dd4d5e5ba4b48b026e613ff Mon Sep 17 00:00:00 2001 From: ALGOTITAN agents Date: Mon, 19 Oct 2026 05:07:17 +0000 Subject: [PATCH 1/3] Rewrite the README to the house sections and add an MIT licence (ALG-83) Adds the Status line (the 2024 code does not build as committed; the three-cast fix is documented), fixes the flags (-microbitName1/2) and the build steps (no bin/ folder, no go.mod), keeps a single MakeCode link. Co-Authored-By: Claude Opus 5.5 --- LICENSE | 21 +++++++++++++ README.md | 92 +++++++++++++++++++++++++++---------------------------- 2 files changed, 66 insertions(+), 47 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..4cedf43 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020-2024 storagebits + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 586e31c..e5134fd 100644 --- a/README.md +++ b/README.md @@ -1,75 +1,73 @@ # board-explorer -board-explorer is an experimental interactive board project. The aim is to learn mixing electronic components with gaming in mind. Code is provived as is mostly for educational purpose. +An experimental interactive game board: arcade joysticks plugged into a Raspberry Pi drive micro:bit robots over Bluetooth Low Energy. Made to learn how to mix electronics with gaming. -Base components are **Raspberry Pi, micro:bit, arcade controllers and an IR frame** (optional) for localisation. +![board-explorer: an arcade joystick in front of a board where two micro:bit robots face each other](images/board-explorer.jpg) -## MakeCode - There's a dedicated repository for the MakeCode associated with this project: +## What it does - micro:bit Direct link : https://makecode.microbit.org/_frdR5xctm0Rt +`board-explorer` is a small Go program for the Raspberry Pi. It connects over BLE to one or two micro:bits (one per player), reads one USB arcade joystick per player, and sends each move to that player's micro:bit as a one-letter command on the micro:bit's BLE UART. The micro:bit runs the companion MakeCode program, [board-explorer-makecode](https://github.com/storagebits/board-explorer-makecode), which drives a ring:bit car and its LEDs. - Code : https://github.com/storagebits/board-explorer-makecode +| Joystick | Command sent | On the micro:bit | +|---|---|---| +| Up | `z` | forward | +| Down | `s` | back | +| Left | `q` | turn left | +| Right | `d` | turn right | +| Button pressed | `o` | LEDs blink | +| Button released | `p` | LEDs back to green | +## Status -**WARNING:** this project is at early stage and is subject to change often. +Prototype, not developed since 2024. The code is provided as is, mostly for educational use. -![board-explorer](https://github.com/storagebits/board-explorer/blob/master/images/board-explorer.jpg?raw=true) +- Worked in 2020 (as the original README reported; not re-tested on hardware since): BLE connection to up to two micro:bits, USB arcade joysticks, the commands above. +- Does not build as committed: the 2024 rewrite fails to compile against the current `golang-evdev` (`cannot use ev.Code (variable of type uint16) as int value in map index`, three times in `formatEvent`). Writing `int(ev.Code)` in those three places makes it build again. The repository also has no `go.mod` yet; see Getting started. +- Not done: the IR frame for locating pieces on the board (the touch-input reader is in the code but not wired in), RFID, scoring, LED strips and the board's furniture. ## Getting started -### Setting up your micro:bit +Requirements: a Raspberry Pi with Bluetooth (or any Linux machine with a BLE adapter), a recent Go (tested with 1.23) and a C compiler (the evdev package uses cgo), one or two micro:bits, and one USB joystick per player. -board-explorer communicate with micro:bit(s) component(s) via BLE (Bluetooth Low Energy). It sends commands on the BLE UART which are then interpreted localy on the micro:bit. So we need first to flash our micro:bit(s) with the following makecode project : +1. **Flash the micro:bits** with the companion program: open https://makecode.microbit.org/_frdR5xctm0Rt and download it to each micro:bit, or import the [board-explorer-makecode](https://github.com/storagebits/board-explorer-makecode) repository in MakeCode. Note each micro:bit's name (the five letters shown by the micro:bit app on Android or iOS). +2. **Build** (after the `int(ev.Code)` fix above): -#### Direct link to makecode project + ```sh + git clone https://github.com/storagebits/board-explorer.git && cd board-explorer + go mod init board-explorer && go mod tidy + go build -o bin/board-explorer . + ``` -This is the easier way to get started, you can open the makecode project with following link and flash your micro:bit : -https://makecode.microbit.org/_5up1Y89u5J5X +3. **Plug in the joysticks** (the first one is player 1), power the micro:bits, then run: -#### Repository of the makecode project + ```sh + sudo ./bin/board-explorer -microbitName1 [-microbitName2 ] + ``` -If you need more infos you can check the corresponding repository here : -https://github.com/storagebits/board-explorer-makecode + BLE needs raw network access. To run without `sudo`, give the binary the capabilities once: -### Setting up your USB joystick + ```sh + sudo setcap 'cap_net_raw,cap_net_admin=eip' ./bin/board-explorer + ``` -In the best way it should just work plug'n'play ! just plug it before launching board-explorer. +## Configuration -## Build board-explorer +Command-line flags only; there is no configuration file. -In the bin folder you'll find a binary compiled on a Raspberry Pi with GOARM=5 build option. +| Flag | Purpose | +|---|---| +| `-microbitName1` | Name of player 1's micro:bit (required). The program connects to the BLE device advertised as `BBC micro:bit []`. | +| `-microbitName2` | Name of player 2's micro:bit (optional). Player 2 uses the second joystick. | -If you're running on a Rapsberry Pi you can run this one (see Run paragraph below) or build your own with following command : +## Project layout -```console -foo@bar:~/board-explorer $ go build board-explorer.go -o bin/board-explorer ``` - -## Run board-explorer - -Now it's time to powerup your flashed micro:bit(s) and launch board-explorer : - -```console -foo@bar:~/board-explorer/bin $ sudo ./board-explorer -player1 microbit1name [-player2 microbit2name] -``` - -_note:_ You can retrieve your micro:bit name in your Android or IOS micro:bit app - -_note:_ to avoid sudo you could set following setcap rights to board-explorer binary : -```console -foo@bar:~$ sudo setcap 'cap_net_raw,cap_net_admin=eip' ./board-explorer +board-explorer.go the whole program: BLE connections, joystick polling every 40 ms, command sending +images/ photo of the board ``` -## What's done ? What's in progress ? What's next ? - -| What's done ? | What's in progress ? | What's next ? | -|-----------------------------|-----------------------|---------------------| -| Bluetooth LE support | IR frame support | LEDs | -| USB arcade joystick support | RFID support | Scoring | -| micro:bit support | | Furnitures / Design | - +## Licence and credits -## Educational purpose +Released under the [MIT licence](LICENSE). It is meant to be reused in other educational projects, classrooms or experimental electronic boards. -This code is provided as is. It is mean to be-reused in other educational projects, classrooms or in any experimental electronic board experience. +Built on [go-ble/ble](https://github.com/go-ble/ble) (BSD 3-Clause), [simulatedsimian/joystick](https://github.com/simulatedsimian/joystick) (MIT) and [gvalkov/golang-evdev](https://github.com/gvalkov/golang-evdev), fetched by `go mod tidy`, not vendored here. From eb9f6ad7fbdc79453ac14048476ffeede93fe841 Mon Sep 17 00:00:00 2001 From: ALGOTITAN agents Date: Mon, 19 Oct 2026 05:07:53 +0000 Subject: [PATCH 2/3] README: the p command does not stop blinking (ALG-83) Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e5134fd..1c96019 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ An experimental interactive game board: arcade joysticks plugged into a Raspberr | Left | `q` | turn left | | Right | `d` | turn right | | Button pressed | `o` | LEDs blink | -| Button released | `p` | LEDs back to green | +| Button released | `p` | LEDs green (blinking does not stop: see the companion repo's Status) | ## Status From 3afc35b134733aed81f950fd9c81f191482d64b7 Mon Sep 17 00:00:00 2001 From: ALGOTITAN agents Date: Mon, 19 Oct 2026 05:13:56 +0000 Subject: [PATCH 3/3] README: review fixes (ALG-83) Co-Authored-By: Claude Opus 5.5 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 1c96019..66acf19 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,8 @@ Prototype, not developed since 2024. The code is provided as is, mostly for educ - Worked in 2020 (as the original README reported; not re-tested on hardware since): BLE connection to up to two micro:bits, USB arcade joysticks, the commands above. - Does not build as committed: the 2024 rewrite fails to compile against the current `golang-evdev` (`cannot use ev.Code (variable of type uint16) as int value in map index`, three times in `formatEvent`). Writing `int(ev.Code)` in those three places makes it build again. The repository also has no `go.mod` yet; see Getting started. +- Commands repeat: every 40 ms the program sends `o` or `p` for the button and a letter for a pushed direction. A centred stick sends nothing (never `w`, brake), so the car keeps its last move. +- The GitHub Actions workflow (`.github/workflows/go.yml`, Go 1.13, `go get` without `go.mod`) dates from 2020; expect it to fail. - Not done: the IR frame for locating pieces on the board (the touch-input reader is in the code but not wired in), RFID, scoring, LED strips and the board's furniture. ## Getting started