COMING SOON - BillyGate 0.2.*

User manual

BillyGate is a little bluetooth-low-energy (BLE) gadget that connects chess e-boards to third party apps. It originated to rescue my Square Off Pro rollable e-board after Square Off went bust (sorry, was acquired by Miko) and ceased to support game play on sites like chess.com and lichess.org. BillyGate enables Square Off Pro and Square Off Neo owners to again enjoy over-the-board (OTB)/online chess on these excellent e-boards, and I intend to extend BillyGate to other e-boards and chess apps in future releases.

IMPORTANT: BillyGate supports the e-boards and client apps listed in the Introduction.

Introduction

The Square Off app was never as well engineered as their e-boards, and the Miko app has yet to significantly improve upon it. So the idea behind BillyGate is to enable Square Off owners to use their e-boards via other apps.

BillyGate is software (firmware) running on a tiny, low-cost and widely available Bluetooth Low Energy (BLE) electronics board (Raspberry Pi Pico 2 W). After connecting to supported e-boards it ‘pretends’ to be a Chessnut e-board, enabling the e-board user to play OTB/online games on chess.com and lichess.org using the freely available and excellent Chessnut app, or other third party apps that support Chessnut e-boards!

Supported e-boards and apps

E-boards:

Square Off Pro - rollable LED e-board
Square Off Neo - robotic e-board

E-board apps:

Chessnut (leading e-board manufacturer)

Third party apps (that support Chessnut), including:

Jörn Gehring’s Chessconnect Chrome extension and apps.
Gerhard Kalab’s Chess PGN Master and Chess Dojo apps.
Khadim Fall’s WhitePawn app.

Set-up

There are quite a few set-up steps to do before you can start playing chess (the easy bit :), some of which are a little technical, but if you work through the checklist below you will get there.

Check/update your e-board firmware
Buy a Raspberry Pi Pico 2 W
Powering BillyGate
Install/update BillyGate firmware
BillyGate 'admin' mode (firmware authentication and enabling WiFi)

Check/update your e-board firmware

E-boards have their own firmware and BillyGate requires specific versions:

Square Off Pro - version 3.0.5
Square Off Neo - version 3.0.7

For reasons known only to Miko (the new owner of Square Off) you have to contact their customer support, to update firmware from the Square Off or Miko apps. See Q: How do I update my Square Off firmware?

Buy a Raspberry Pi Pico 2 W

Purchase a Raspberry Pi Pico 2 W from a local online vendor (globally available for around $10 USD). Make sure you buy a PICO 2 W as there are other Picos with similar names, but BillyGate only works on a Pico 2 W.

Powering BillyGate

BillyGate (Pico2W) can be powered from any 5V USB power adapter, any computer USB port that supplies power or some 5V battery power banks (the kind of things you use to charge your phone on the move).

IMPORTANT: The Pico2W consumes so little power that many power banks stop charging after a while, thinking no current is being drawn. The solution is usually to put your power bank into its trickle charge mode (if it has one), but this does not always work. Test your power bank overnight (checking that the Pico2W LED keeps flashing) before playing online games, because loss of power mid-game will mean loss of rating points!

Install/update BillyGate firmware

The ‘brains’ behind BillyGate is low-level software called firmware that runs on the Pico2W board. When you purchase BillyGate you will be sent a link to its latest firmware. To install or update BillyGate firmware on the Pico2W:

Download the BillyGate firmware to a Windows, MacOS or Linux PC.
Obtain a data-capable micro-b USB cable that you will use to connect BillyGate to your PC (and later to a power supply). NOTE: some cheap USB cables only carry power, not data.
Connect the cable to the Pico2W but not to the PC.
Locate the little white BOOTSEL button on the Pico2W.
While holding down the BOOTSEL button, plug the Pico2W into the PC and release the BOOTSEL button.
A new disk drive should appear on the PC - just like plugging in a USB thumb drive. It should have a name like RP**** and be empty, apart from a couple of informational files.
Drag and drop (or copy) the BillyGate firmware file onto this RP**** drive.
On some PCs you may see a warning message that the installer may contain harmful content. Make sure you are copying the firmware to the RP**** drive and ignore the warning.
If the firmware installation/update is successful the Pico2W restarts, the RP**** drive disappears and the green Pico2W LED starts flashing (see Appendix A).
The procedure for updating BillyGate firmware to a newer version is exactly the same (and preserves ayour set-up. so you don't need to do it again).

BillyGate 'admin' mode (firmware authentication and enabling WiFi)

To finish setting up BillyGate you have to put it into a special 'admin' mode. This enables you to connect to BillyGate from a PC or mobile device, to authenticate the firmware (mandatory) and connect BillyGate to your home WiFi network (optional but recommended).

Entering 'admin' mode

You can enter 'admin' mode whenever BillyGate is flashing its LED (Appendix A) by long-pressing its white BOOTSEL button for more than 5 seconds (say BillyGate One, BillyGate Two, ... BillyGate Five) then releasing it. When BillyGate is in 'admin' mode it flashes twice every 4 seconds and generates a temporary ble-gate-ap WiFi network (different from your home WiFi network) to which you can connect a PC or mobile device.

IMPORTANT: While your PC or mobile device is connected to BillyGate's temporary ble-gate-ap WiFi network you will not be able to access the Internet (on the connected PC or mobile device) so keep this page open in a browser tab on the PC or mobile device so you can refer to it and click on relevant links.

Connecting to BillyGate in 'admin' mode

On your PC or mobile device scan for, and connect to, the ble-gate-ap WiFi network (if you cannot connect, try connecting from another less fussy device).
The password for the ble-gate-ap WiFi network is billyg123.
Once you are connected to ble-gate-ap, open a web browser on your PC or mobile device and browse to http://192.168.4.1/.
You should see the BillyGate 'admin' web page.

Firmware authentication

IMPORTANT: You must complete this firmware authentication step to use BillyGate. See Q: Why do I need to authenticate BillyGate firmware?

The 'admin' page displays a unique ID for your Pico2W (for example, 5b28c11557da6292 in the image above). Send this to BillyGate customer support. One of our support goats will return a long token string. Copy and past this into the Authentication token input field (being very careful to copy the token exactly, without any spaces) and click the Authenticate button. If accepted you should see a 'token stored' popup message. This enables BillyGate firmware to run on your Pico2W.

If you want to connect BillyGate to your home WiFi (recommended, to avoid having to use 'admin' mode again and for advanced features) proceed to Enabling WiFi below. If not, restart BillyGate by either long-pressing the white BOOTSEL button for more than 1 second (but less than 5) or removing and reconnecting power.

Enabling WiFi

Connecting BillyGate to your home WiFi is optional, but recommended. It provides a helpful web user interface and access to advanced features. On the 'admin' web page:

Enter the network name and password of your home WiFi network (user the show password button if present and be careful to avoid typos, otherwise you will have to repeat this procedure).
Clicking Connect encrypts and stores your WiFi credentials and restarts BillyGate (exiting 'admin' mode).
When BillyGate restarts it should automatically connect to your home WiFi.
Browse to http://ble-gate and add this URL to your browser favourites. This is your BillyGate web user interface, now available on your home WiFi network. If your browser cannot open http://ble-gate see Q: Why can't I open the BillyGate web user interface in my browser?
Your browser may also complain about http://ble-gate being insecure (it is, as it does not use SSL) but unless your chess games are a state secret you can ignore the warnings.

Game play

Connect BillyGate to your e-board

If you have installed and authenticated the BillyGate firmware and powered up the Pico2W it should start signalling via its LED (Appendix A) that it is scanning for supported e-boards.

Set the pieces on the e-board to their default starting positions. Note that the e-board has printed square coordinates and the white and black pieces must be on their correct sides.
Switch on the e-board. Square Off e-boards should show a circling on-board LED pattern as they wait for a BLE client connection.
After a few seconds BillyGate should discover the e-board.
When BillyGate discovers a supported e-board it will immediately attempt to connect to it and its LED will flash a different pattern. A successful connection results in the e-board emitting its ‘connected’ beep and BillyGate flashing the e-board LEDs in a ‘goat horns’ pattern.
If BillyGate fails to connect, check the Square Off firmware version.

IMPORTANT: The BillyGate firmware is somewhat sensitive to the order in which you prepare to play a game. Please try and follow the order described in this document.

Connect Chessnut client app to BillyGate

When BillyGate has connected to the Square Off Pro it begins transmitting BLE ‘advertisements’, pretending to be a Chessnut Go e-board (see LED flashes).

Install the Chessnut app on your mobile device from the Google Play Store or Apple App Store. If there are two Chessnut apps available make sure to install the newer one.
Follow the Chessnut installation instructions, which includes creating a Chessnut account.
Enable Bluetooth on your mobile device.
Run the Chessnut app and follow its instructions to discover and connect to the Chessnut Go board being advertised by BillyGate.
There are three signals that the Chessnut app has connected to BillyGate:
- The d- and e-file LEDs flash on the Square Off Pro e-board.
- A little Bluetooth logo on the Chessnut app changes to show the connection.
- The BillyGate (Pico2W) LED shows solid green.
If you have reached this point you are ready to play!

Playing games

Try a bot match first in the Chessnut client app. Game play will vary slightly, depending on whether your e-board is an LED or robotic e-board:

LED e-board (Square Off Pro): The client app highlights squares for opponent moves using the e-board LEDs and you make moves for both yourself and your opponent. BillyGate also uses e-board LEDs to highlight things like out-of-position pieces and incomplete moves.
Robotic e-board (Square Off Neo): The client app makes opponent moves on the-board, using its robotic actuators, and you make your moves. BillyGate also uses e-board LEDs to highlight things like out-of-position pieces and incomplete moves.

The one non-obvious aspect of game play is pawn promotion, so please read about BillyGate's Promotion/under-promotion feature. But, if a pawn reaches a promotion square and you forget what the pulsing LEDs mean, just wait 5 seconds and it will default to a Q promotion. Alternatively, you can configure BillyGate settings to always promote to a Q without any pulsing LED action :)

When you have bot matches working you're ready to play human opponents on chess.com and lichess.org!

Starting/restarting games

When you have finished one game and want to start another you need to reset the pieces to their start position before starting the new game. While you reset the pieces you will probably see lots of LEDs lighting up on the e-board (on squares that differ from the final position of the finished game) but when you have returned the e-board to its default start position these LEDs should disappear and BillyGate should flash the startup ‘goat horns’ LED pattern. If you do not reposition the pieces before starting another game BillyGate will be stuck on the final position of the finished game.

IMPORTANT: When this all works as described it is simple. But things can go wrong, so please read the Avoiding/fixing common problems section below.

BillyGate also supports starting games from custom positions, using its web UI.

Avoiding game play problems

If you have a simple mental model of what BillyGate is doing ‘under the hood’ you will be better able to anticipate problems and, if you encounter them, correct them quickly.

Square Off e-boards report square occupancy, which means they only know if a square is occupied or not. But the Chessnut app expects full piece recognition, i.e. which piece/colour is on a given square. So as you move pieces on the Square Off Pro, BillyGate has to translate changes in square occupancy to piece recognition updates, using the rules of chess to convert square 'ups' and 'downs' to legal chess moves (think about castling, promotion, en passant, knocked over pieces, etc.).

Accidental ‘wrong’ move (opponent)

This only applies to LED (and not robotic) e-boards.

Imagine your opponent is playing white, it’s their move and the Chessnut client app sets the on-board LEDs to say they moved e2-e3 ... but you accidentally move e2-e4. Even though this is a legal chess move, BillyGate will not accept it as it does not agree with the LEDs set by the Chessnut app. In this situation BillyGate will set the e-board LEDs to show a combination of the desired move and the pieces that are out of position (in this example the e2, e3 and e4 squares). Simply move the piece(s) again until they agree with the Chessnut app.

Board LEDs that persist after your last opponent move is usually a sign that you have either accidentally made the 'wrong' move, i.e. one that differs from the LED-indicated move, or other pieces are out of position.

Accidental ‘wrong’ move (player)

This applies to both LED and robotic e-boards.

When it’s your turn, you may occasionally make the wrong move (the finger equivalent of a mouse slip in online chess) or make the right move but (to your horror) see a different move registered by the Chessnut client app (mis-registration).

Finger slip
Unless your client app supports takebacks you’re stuck. If takebacks are supported, try following the client app takeback procedure in conjunction with BillyGate's Undo feature.
Mis-registration
This was a common (and very frustrating) problem with the Square Off app. If you slide pieces across the board (as you often do on a regular chess board) the app/firmware might decide the move is complete before it actually is, registering the wrong final square and therefore the wrong move. For example, a bishop sliding too slowly from f1 to c4 could register as having being moved to e2 or d3. BillyGate improves on this by waiting a short time for the position to settle before registering moves, but it is still highly recommended to get into the habit of lifting and placing pieces and not sliding them, because if the delay is insufficient and there is a mis-registration you are in the same unhappy position as for a finger slip.

Features

Promotion/under-promotion

Square Off e-boards only report square occupancy (without piece recognition), so you have to tell the client app whether promotion is to a Queen, Knight, Rook or Bishop.

You have to do this for your promotions and your opponent's promotions, because to continue the game correctly BillyGate needs to know what kind of piece is now on the promotion square.

When you or your opponent promotes a pawn BillyGate pulses board LEDs to highlight the promotion square and to select the promotion piece. Queen promotion remains the default, but you now have a short time window to cycle through under-promotion types by lifting and replacing the pawn (or piece) on its promotion square. When the pulsing LEDs show your desired promotion type simply wait for 5 seconds and that promotion type will be sent to the client app.

If you move a pawn to its promotion square and do nothing more, after 5 seconds it will default to a Queen promotion. If you want to under-promote, you have 5 seconds to cycle to the next under-promotion option by lifting and replacing the pawn (or piece) on its promotion square. Each time you lift and replace the promotion pawn (or piece) it resets the 5 second timer.

Practise this by connecting BillyGate to your Square Off e-board (no need to connect a client app) and setting a custom promotion position (e.g. 8/3KP3/5k2/2B3p1/6Pp/7P/5b2/8 w - - 0 1).

See BillyGate settings and Appendix B: Promotion LEDs for details.

Undo

Undo moves from BillyGate’s internal game position, usually to help recover sync with the internal game position of the chess client app - see Accidental ‘wrong’ move (opponent) or Accidental ‘wrong’ move (player).

There are two ways to undo the last move:

Physically undo the last move on the e-board. Undoing multiple moves requires physically undoing them one-by-one in reverse order.
Click the Undo button on the web UI. Click n times to undo n moves (although this should rarely be required).

Virtual LEDs

Virtual LEDs is a technical BillyGate feature that interprets the e-board LEDs set by client apps to improve its move detection logic, to avoid registering legal chess moves that do not agree with client app LED signals. This makes it harder for e-board players to make the wrong opponent move and easier to correct them if they do. As of BillyGate v0.2.* this feature can no longer be disabled from BillyGate settings.

Reset

It may sometimes be useful to reset the BillyGate (Pico2W) gadget. Resetting BillyGate is like switching a PC off and on again: it clears out all the internal state, restarts the firmware and can solve all sorts of problems. Don’t do this in the middle of a game though! You can reset BillyGate (Pico2W) by either:

Disconnecting/reconnecting it from/to power.
Holding down the white BOOTSEL button on the Pico2W board for more than 1 second (but less than 5, see BillyGate 'admin' mode) and then releasing it.

Page updated

Google Sites

Report abuse