Shell Car

Reverse‑engineered controllers for Bluetooth Low Energy (BLE) toy cars — most notably the Shell / QCAR promotional RC cars (BMW M Hybrid V8 and Ferrari F1‑75 models) built on the Brandbase BLE platform, with partial support for Bburago BLE cars.

The project ships three independent ways to drive the same car, all speaking the car's native BLE protocol:

Implementation	Location	Runs on	Best for
ESP32 firmware	shellcar.ino	An ESP32 dev board with physical buttons	A standalone hardware remote
Python backend	backend/	A computer with a BLE adapter (Bleak)	Keyboard / gamepad control, scripted routines, a local HTTP API
Web app (PWA)	gui/ + shellcar.html	A Web Bluetooth–capable browser	Phone / desktop control with no install

How it works

The car exposes a BLE GATT service. Depending on the model, commands are sent one of two ways:

• Brandbase / QCAR cars — commands are AES‑encrypted (ECB, no padding) and written to a control characteristic. Two approaches appear in this repo:
  • The web app and shellcar.html build a 16‑byte command frame in the browser and encrypt it on the fly with CryptoJS using the key 34522a5b7a6e492c08090a9d8d2a23f8.
  • The ESP32 firmware and Python backend skip live encryption and instead replay a fixed table of pre‑captured encrypted command frames (idle, forward, backward, left/right, and their turbo variants) — see backend/commands.py.
• Bburago cars — commands are sent as an unencrypted 8‑byte frame where each byte toggles a direction / turbo / lamp flag.

Key BLE identifiers (see backend/uuids.py):

Purpose	UUID
Control service	0000fff0-0000-1000-8000-00805f9b34fb
Brandbase control characteristic	d44bc439-abfd-45a2-b575-925416129600
Battery characteristic	d44bc439-abfd-45a2-b575-925416129601
Bburago control characteristic	0000fff1-0000-1000-8000-00805f9b34fb

The web app discovers cars by the BLE name prefix QCAR-.

Note: The AES key and command frames in this repository were obtained by reverse engineering the stock car firmware, for interoperability and hobby use. There is no affiliation with Shell, BMW, Ferrari, Brandbase, or Bburago.

---

1. ESP32 firmware — shellcar.ino

An Arduino sketch that turns an ESP32 into a physical BLE remote. It scans for the car, connects, and continuously streams the command matching the currently pressed buttons.

Wiring (default pins, configurable at the top of the sketch):

Function	GPIO
Forward	4
Backward	5
Right	14
Left	27
Turbo (toggle)	26
Turbo LED	25

Holding the turbo button at boot switches the firmware into Bburago mode.

Build & flash

1. Install the Arduino IDE and the ESP32 board support package.
2. Open shellcar.ino, select your ESP32 board, and upload.
3. Open the Serial Monitor at 115200 baud to watch the connection log.

---

2. Python backend — backend/

BLE control from a computer using Bleak, with keyboard and gamepad input, scripted routines, and a Flask HTTP API.

Files

File	Description
shellcar.py	ShellCar class — BLE scan / connect / send command / run routine
commands.py	Pre‑captured encrypted Brandbase command frames
uuids.py	BLE service and characteristic UUIDs
routines.py	CarCommand model, command builders, and an example routine
controller.py	Keyboard (WASD + T) and Pygame gamepad listeners
shellcar_ps4.py	Standalone PS4 / gamepad driver
shell_app.py	Tkinter desktop app wiring the car, controller, and a GUI together
server.py	Flask HTTP API (/connect, /send_command, /battery_level, …)
gui.py	Tkinter status GUI
requirements.txt	Python dependencies

Setup

cd backend
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt flask-cors

Dependencies: flask, bleak, keyboard, pygame (plus flask-cors for the server). BLE and global keyboard hooks may require elevated privileges on some platforms.

Run

# Desktop app (Tkinter GUI + keyboard/gamepad listeners)
python3 shell_app.py

# HTTP API server on http://localhost:5000
python3 server.py

# Gamepad-only driver
python3 shellcar_ps4.py

Keyboard controls: W forward · S backward · A left · D right · T turbo.

HTTP API (server.py)

Method	Route	Description
POST	/connect	Scan and connect to the car
POST	/send_command	Run a routine: {"commands": [{"forward":true,"backward":false,"left":false,"right":false,"turbo":true}, …]}
GET	/battery_level	Last reported battery level
POST	/start_listeners	Start the gamepad listener

CORS is open (*) so the web app can call it directly.

---

3. Web app — gui/ and shellcar.html

Two browser-based clients that talk to the car directly over Web Bluetooth (no backend required). They run entirely in the browser and encrypt commands client‑side.

Web Bluetooth requires a supported browser (Chrome / Edge / Chrome Android) served over https:// or localhost.

shellcar.html — single-file prototype

A zero‑build, standalone HTML page. Open it in a supported browser, click Connect to device, and drive with the arrow keys. Includes turbo, lights, and live battery readout. Good for a quick test with nothing installed.

gui/ — Next.js PWA

A polished T3 / Next.js progressive web app with:

• Connect / disconnect and live connection status
• Keyboard (arrow keys + Shift turbo) and Gamepad API control
• A routine editor — build, reorder, and replay sequences of commands
• BMW / Ferrari theme switcher (persisted to localStorage)
• Battery display, PWA manifest, and an optional Electron desktop wrapper

Develop

cd gui
npm install
npm run dev          # http://localhost:3000

Other scripts

npm run build        # production build
npm run start        # serve the production build
npm run check        # lint + typecheck
npm run electron-dev # run inside Electron (desktop)

---

Repository layout

shell_car/
├── shellcar.ino      # ESP32 Arduino firmware
├── shellcar.html     # Standalone Web Bluetooth prototype
├── backend/          # Python (Bleak) control, routines, and Flask API
└── gui/              # Next.js PWA + Electron web app

Compatible cars

• Shell / QCAR promotional RC cars (BMW M Hybrid V8, Ferrari F1‑75) on the Brandbase BLE platform — advertised with a QCAR- name prefix.
• Bburago BLE cars (partial support in the ESP32 firmware and Python builders).

Disclaimer

This is an unofficial, community reverse‑engineering project for interoperability and hobby use. It is not affiliated with or endorsed by Shell, BMW, Ferrari, Brandbase, or Bburago. Use at your own risk.