繁體中文

Download the STL files for the QBIT enclosure from MakerWorld:

• MakerWorld: QBIT - Your IoT Desk Robot (ESP32-C3)

Default pin assignments for the ESP32-C3 Super Mini. All pins can be reassigned through the web dashboard at http://qbit.local and are stored in NVS (persistent across reboots; changes require a reboot to take effect).

Power connections:

The I2C bus runs at 400 kHz. No external pull-up resistors are needed if the OLED module has built-in pull-ups (most breakout boards do).

The easiest way to flash QBIT firmware is through the browser-based flasher. No toolchain installation is required.

1. Open the QBIT Firmware Flasher in Chrome or Edge (version 89+).
2. Connect your QBIT board via USB.
3. Click Connect & Flash and select the serial port.
4. The flasher will write the bootloader, partition table, firmware, and filesystem image automatically.

After flashing, if Wi-Fi is not yet configured, QBIT enters Wi-Fi setup mode:

1. The OLED shows a QR code (SSID and password) by default. Tap the touch sensor to switch to text: SSID QBIT and password (device MAC last 8 hex digits, e.g. 1A2B3C4D).
2. Connect your phone or computer to the QBIT Wi-Fi access point using the password shown on screen.
3. Once connected to the AP, a captive portal opens automatically (or open a browser manually to the setup page). Select your home Wi-Fi and enter its password.
4. Credentials are saved to NVS and the device reconnects to your home Wi-Fi; you can then access the dashboard at http://qbit.local.

If Wi-Fi is lost for about 30 seconds, QBIT automatically opens the AP again so you can reconfigure.

Once connected to Wi-Fi, the QBIT hosts a local web dashboard accessible at:

http://qbit.local

From the dashboard you can:

• View the unique device ID and set a custom display name
• Adjust display brightness, buzzer volume, and animation playback speed
• Upload and manage .qgif animation files
• Configure a local MQTT broker connection for home automation (see MQTT & Home Assistant)

The QBIT web platform can be self-hosted and provides a central interface for monitoring and interacting with all your online QBIT devices.

If you use the official firmware, your device will automatically connect to the official server: https://qbit.labxcloud.com

If you prefer, you can deploy your own web platform and backend on your own server, and configure the firmware to connect to your custom domain.

The Network page shows all currently connected QBIT devices as an interactive graph powered by vis-js/vis-network. Each node displays the device name. Devices that have been online longer are drawn closer to the central hub. The current number of online devices is displayed at the bottom.

Clicking a device node opens a poke dialog where logged-in users can:

• Poke -- send a text message (up to 25 characters) to the device. Both the sender name and message text are rendered as 1-bit bitmaps on the web to support multi-language display (including CJK and emoji) on the monochrome OLED. If the text exceeds the screen width, it scrolls horizontally.
• Claim -- bind a device to your account (see Device Claiming). Claimed devices show the owner's name and avatar on the graph node.
• Unclaim -- remove your ownership of a claimed device.

The Flash page embeds the browser-based firmware flasher, allowing users to flash their QBIT directly from the web platform without visiting a separate site.

The Library page is a community-driven repository of .qgif animation files.

QBIT uses a custom binary animation format (.qgif) optimized for the 128x64 monochrome OLED. The format stores 1-bit monochrome frames with per-frame delay values.

Use the included conversion tool to create .qgif files from standard GIF animations:

pip install Pillow
python tools/gif2qbit.py input.gif
python tools/gif2qbit.py input.gif --threshold 100 --invert --scale stretch
python tools/gif2qbit.py *.gif

Options:

To embed a .qgif animation into firmware as a PROGMEM constant (e.g. for idle or boot animations):

python tools/qgif2header.py firmware/include/sys_idle.qgif

This generates a C header file with the animation data as an AnimatedGIF struct, ready for #include in firmware source.

QBIT supports local MQTT integration with automatic Home Assistant discovery. Configure the MQTT broker connection from the device dashboard at http://qbit.local.

Once connected, the device publishes HA discovery payloads that automatically create the following entities in Home Assistant:

Logged-in users can claim a QBIT device to bind it to their account. Claimed devices display the owner's name and avatar on the Network graph.

Claiming flow:

1. Click a device on the Network page and select "Claim this device".
2. Enter the full 12-character device ID (printed on the device dashboard).
3. The web sends a claim request to the device via WebSocket.
4. The QBIT OLED displays the requester's name and prompts for a long-press confirmation.
5. Long-press the touch button on the device to confirm, or wait 30 seconds to reject.
6. On confirmation, the claim is stored on the server and the device shows the owner's avatar on the graph.

Unclaiming:

Click a claimed device on the Network page and select "Unclaim this device". Only the owner can unclaim.

• A Linux server (VPS) with Docker and Docker Compose installed
• A domain name with DNS managed by Cloudflare (or any reverse proxy that provides TLS)
• A Google Cloud project with OAuth 2.0 credentials

Internet
 |
 +-- Cloudflare Tunnel / Reverse Proxy (TLS termination)
 |
 +-- frontend (Nginx, port 80)
 | |-- Serves React SPA
 | |-- Proxies /api/, /auth/, /socket.io/, /device to backend
 |
 +-- backend (Node.js, port 3001 + 3002)
 |-- REST API (devices, poke, library, claims)
 |-- Google OAuth (Passport.js)
 |-- Socket.io (real-time frontend updates)
 |-- WebSocket /device (ESP32 device connections)
 |-- Admin UI on port 3002 (sessions, users, devices, bans)
 |-- SQLite DB + files in /data (volume)

Copy the example and fill in your values:

cd web
cp .env.example .env

Optional (auto-generated and stored in /data/secrets.json if not set): SESSION_SECRET, ADMIN_SESSION_SECRET, HEALTH_SECRET.

Generate secure random values (e.g. for DEVICE_API_KEY):

openssl rand -hex 32

Passwords with special characters: Use the .env file and wrap values in double quotes. Escape \ and " inside (e.g. ADMIN_PASSWORD="my\"pass").

For CI builds, set the QBIT_WS_API_KEY repository secret to the same value as DEVICE_API_KEY; it is injected into the firmware at build time.

cd web
docker compose -f docker-compose.dev.yml up --build

For Google OAuth locally, add http://localhost:3000/auth/google/callback to Authorized Redirect URIs in Google Cloud Console.

cd web
docker compose up --build -d

This starts the frontend (exposed on port 3000) and backend (internal only) containers. Point your reverse proxy or Cloudflare Tunnel to the frontend service on port 3000. The frontend Nginx configuration handles proxying all API, auth, WebSocket, and Socket.io traffic to the backend internally. Only port 3000 is intended for external access; the backend is not exposed to the internet.

Verify the deployment:

docker compose ps # both containers should be running
docker compose logs backend # should show "QBIT backend listening on port 3001"

All persistent data is in the qbit-data volume (path /data inside the backend container): SQLite database qbit.db (sessions, users, claims, bans, library metadata), uploaded library files in files/, and secrets.json for auto-generated secrets.

The backend logs to stdout (pino, JSON in production). View with docker compose logs -f backend. No log files are written.

GET /health returns server status (uptime, devices, claims, online users, library count). Use ?format=json for JSON. From the server: docker exec qbit-frontend curl -s http://backend:3001/health.

Two workflows are included:

Build and Release (build-and-release.yml) -- triggered on version tags (v*):

• Compiles firmware with PlatformIO
• Builds the LittleFS filesystem image from firmware/data/
• Injects WS_HOST and WS_API_KEY from repository secrets (QBIT_WS_HOST, QBIT_WS_API_KEY)
• Creates a GitHub Release with firmware.bin, littlefs.bin, bootloader.bin, and partitions.bin

Deploy Flasher (deploy-gh-pages.yml) -- triggered after a successful build or on push to main:

• Downloads the latest release artifacts
• Generates manifest.json for esp-web-tools with partition offsets matching firmware/partitions.csv
• Deploys the flasher tool to GitHub Pages

To set up CI/CD, add these repository secrets in GitHub (Settings > Secrets and variables > Actions > Repository secrets):

Requirements: PlatformIO CLI

cd firmware
pio run --target upload # compile and flash firmware
pio run --target uploadfs # upload LittleFS filesystem (animations, web dashboard)
pio device monitor # open serial monitor (115200 baud)

The firmware connects to the backend WebSocket server using the WS_HOST, WS_PORT, and WS_API_KEY defines in firmware/src/main.cpp. For local development, the defaults point to localhost:3001. For production builds via GitHub Actions, these values are injected from repository secrets at compile time.

Custom partition table (firmware/partitions.csv)

License: CC BY-NC-SA 4.0

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).

Commercial use of this project or any derivative works is not permitted without explicit permission from the author. For commercial licensing, contact: scx@gapp.nthu.edu.tw