Firmware v9.6

Binesse Clock Documentation

Everything you need to set up, configure, and hack your Binesse binary clock.

First-Time Setup

When you power on your Binesse clock for the first time, it will automatically enter setup mode. Here's what happens:

1. Plug in your clock using the included USB-C cable. The LEDs will play a white sweep animation, then begin blinking blue — this means it's in AP (Access Point) mode and ready to configure.
2. On your phone or laptop, connect to the "Binesse Clock" WiFi network. A branded setup portal will open automatically. If it doesn't, open a browser and go to 192.168.4.1.
3. Select your WiFi network from the list, enter the password, and choose your timezone. Hit save.
4. The clock will connect to WiFi, sync time via NTP (you'll see 3 green flashes), and start displaying time. You're done.

WiFi Configuration

The clock uses WiFi for two things: syncing time via NTP (internet time servers) and serving the settings web interface. WiFi is optional — the clock works without it using manual time or the onboard RTC.

Can I Always Connect?

Yes — the web interface is always available in some form:

• WiFi connected: Access settings at the clock's IP address (e.g. http://192.168.1.42) from any device on your network.
• WiFi fails on boot: The clock automatically creates an AP network called "Binesse Clock" and runs the web server at 192.168.4.1. You can set time and change settings from there.
• No WiFi ever configured: Same as above — AP mode with full web access at 192.168.4.1.

How WiFi Works

• First boot (no saved credentials): The clock creates its own WiFi network called "Binesse Clock" and opens a setup portal. LEDs blink blue.
• Subsequent boots: The clock silently connects to your saved WiFi (30-second timeout to handle slow routers). If it can't connect, it falls back to AP mode and continues without WiFi (red 3x flash).
• Reconnection: If WiFi drops or isn't available on boot, the clock retries after 2 minutes (catches the "router still booting" case), then every 30 minutes after that. When it reconnects, the web server restarts and if the clock has no good time source, it immediately syncs NTP.

Changing WiFi Networks

Go to the clock's IP address in your browser and click "Reset WiFi Network" at the bottom of the settings page. You'll get a confirmation dialog. This clears only the WiFi credentials — all your other settings (timezone, brightness, color mode) are preserved. The clock will restart in AP mode (blue blinking) so you can connect to a new network.

Note: The clock only supports 2.4GHz WiFi networks. 5GHz networks will not appear in the scan list. This is a hardware limitation of the ESP32-C3.

Accessing Your Clock

The clock runs a web server at its IP address. Every page shows a live status bar at the top with two indicators:

• WiFi pill: Green dot + your SSID when connected, red dot + "Offline" when disconnected
• Time pill: Green dot for RTC/NTP, gold for manual time, red for internal fallback

Below the status bar, the IP address is displayed as a bookmarkable link.

Clock Settings

All settings are configured via the web interface at the clock's IP address and saved to flash memory (they persist across reboots).

Color Modes

• Circadian: Automatically shifts color throughout the day — warm white during the day (6 AM – 6 PM), deep amber at sunset (6 PM – 9 PM), and ember/red at night (9 PM – 6 AM). Zero blue light at night to protect your sleep.
• Single: All LEDs display the same color (white by default).
• Section: Hours are red, minutes are green, seconds are blue — useful for learning which columns represent what.

Time Sources

The clock uses a priority chain to determine the best available time source:

In practice: if you have WiFi, the clock syncs via NTP on every boot and writes the time to the RTC. The RTC keeps time even when unplugged. NTP re-syncs daily at 3 AM.

What Happens with No Time Source?

If the clock boots with no WiFi, no RTC, and no saved manual time, it falls back to millis() mode. The display starts at 00:00:00 and counts up — the clock is always visibly running, never frozen. You'll see red 10x flash on boot to indicate no real time source.

Automatic Time Recovery

If your router boots slower than the clock (common scenario), here's what happens automatically:

1. Boot → WiFi fails (router not ready) → blue 5x flash → red 10x flash (no time source)
2. Clock displays 00:00:00 counting up
3. After 2 minutes, the clock retries WiFi → router is up now → connects
4. Immediately syncs NTP → green 3x flash → clock jumps to the correct time

No user intervention needed. The first WiFi retry happens after 2 minutes (to catch the "router still booting" case), then every 30 minutes after that. When WiFi reconnects and the clock has no good time source, it immediately attempts NTP sync.

Web Interface: Settings

The main settings page is available at the root URL. From here you can change timezone, time format, color mode, brightness, and more. Changes take effect immediately — no reboot needed.

Tip: Replace [IP] with your clock's actual IP address (e.g. 192.168.1.42). Find it on the status banner, serial monitor, or your router's device list.

Web Interface: Manual Time

If you don't have WiFi or an RTC, you can set the time manually at /time. Two options:

• Manual entry: Pick a date and time using the form fields.
• "Sync From This Device": One tap — uses your phone/laptop's current time. This is the fastest way.

Manual time is saved to flash and counts forward using the internal clock. It will drift slightly over time (a few seconds per day) since it relies on millis().

Web Interface: Diagnostics

The diagnostics page at /diag auto-refreshes every 5 seconds and shows:

• Current time and active time source
• Firmware version and uptime
• RTC status and temperature (from the DS3231's built-in sensor)
• WiFi status, SSID, IP address, and signal strength (RSSI)
• All active settings

JSON API

For automation and home assistant integration, the clock exposes a JSON endpoint:

GET http://[IP]/api/status

Response:

{
  "time": "2025-03-15T14:30:45",
  "source": "RTC",
  "uptime": 86400,
  "firmware": "9.2",
  "rtc": true,
  "rtcBattery": "ok",
  "wifi": true,
  "rssi": -42,
  "brightness": 74
}

Other API endpoints:

Development Setup

The Binesse clock runs on a Seeed XIAO ESP32-C3 microcontroller. The firmware is standard C++ / Arduino, and the source is fully open. We recommend PlatformIO (VS Code) for development — it's faster, has better tooling, and caches builds. Arduino IDE is also supported if you prefer it.

Hardware Requirements

• USB-C cable (data-capable, not charge-only)
• Seeed XIAO ESP32-C3 (already installed in your clock)

Required Libraries

Built-in libraries (no install needed): WiFi, WebServer, Wire, Preferences, Update, esp_wifi

Arduino IDE (Alternative)

Arduino IDE works but is significantly slower for ESP32 — it recompiles everything from scratch each time. Use this if you prefer simplicity over speed.

1. Install Arduino IDE from arduino.cc.
2. Add ESP32 board support. Go to File → Preferences and add this URL to "Additional Board Manager URLs":

   https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

   Then go to Tools → Board → Boards Manager, search "esp32", and install esp32 by Espressif Systems.
3. Select the board. Go to Tools → Board → esp32 and select "XIAO_ESP32C3".
4. Install the required libraries. Go to Tools → Manage Libraries and install: WiFiManager, NeoPixelBus (by Makuna), and RTClib.
5. Open the firmware file (binesse_clock.ino), select the correct COM port under Tools → Port, and click Upload.

Note: Set the serial monitor to 115200 baud to see boot diagnostics and debug output.

PlatformIO (VS Code) — Recommended

PlatformIO caches build artifacts, so your second compile is nearly instant if you only changed a few lines. You also get better error messages, autocomplete, and a real code editor. This is what we use to develop the Binesse firmware.

1. Install VS Code from code.visualstudio.com if you don't have it already.
2. Install PlatformIO extension. Open VS Code → Extensions (left sidebar, square icon) → search "PlatformIO IDE" → Install. Wait for it to finish downloading toolchains (takes about a minute).
3. Create the project. Click the PlatformIO alien icon in the left sidebar → "New Project". Name: binesse-clock. Board: Seeed Studio XIAO ESP32C3. Framework: Arduino. Click Finish.
4. Replace the config file. In your project folder, replace platformio.ini with:

   [env:xiao_esp32c3]
   platform = espressif32
   board = seeed_xiao_esp32c3
   framework = arduino
   lib_deps =
     tzapu/WiFiManager
     makuna/NeoPixelBus
     adafruit/RTClib
   monitor_speed = 115200

5. Add your firmware. Copy binesse_clock_v9.6.ino into the src/ folder and rename it to main.cpp. The code already has #include <Arduino.h> so it works as-is.
6. Build & Upload. Look for the icons in the bottom toolbar of VS Code: checkmark for build, arrow for upload, plug icon for serial monitor.

First build takes 1–2 minutes (compiling the ESP32 framework). After that, rebuilds only compile what changed — usually 3–5 seconds.

Project Folder Structure

binesse-clock/
├── platformio.ini          ← config file
├── src/
│   └── main.cpp            ← your firmware (renamed .ino)
└── lib/                    ← auto-managed by PlatformIO

Keyboard Shortcuts

upload_before_reset = usb_reset

OTA (Over-the-Air) Updates

You can update the firmware without physically connecting a USB cable. This is useful once the clock is installed and hard to reach.

1. Compile your firmware to a .bin file. In PlatformIO: run pio run and find the binary in .pio/build/xiao_esp32c3/firmware.bin. In Arduino IDE: Sketch → Export Compiled Binary.
2. Open http://[IP]/update in your browser.
3. Select the .bin file and click "Upload & Install".
4. Wait for the upload to complete. The clock will restart automatically with the new firmware.

Warning: Do not unplug the clock during an OTA update. A failed update can brick the firmware, requiring a USB re-flash.

Hardware Specifications

Pinout & Pixel Map

The 20 LEDs are arranged in a 6-column × 4-row BCD (Binary Coded Decimal) grid. Columns represent the digits of HH:MM:SS.

GPIO Assignments

Pixel Map (LED Index → Grid Position)

The pixelMap[6][4] array maps each column/row to an LED index. -1 means no LED exists at that position (the tens-digit columns for hours, minutes, and seconds only need 2–3 rows).

// pixelMap[column][row] — row 0 = bottom (2^0), row 3 = top (2^3)
//              Col 0    Col 1    Col 2    Col 3    Col 4    Col 5
// Row 3 (8):    0        2        —       9        —       16
// Row 2 (4):    1        3        8       10       15      17
// Row 1 (2):   —         4        7       11       14      18
// Row 0 (1):   —         5        6       12       13      19

int pixelMap[6][4] = {
  { 0, 1,-1,-1},  // Col 0: H tens (0-2, only needs rows 0-1)
  { 5, 4, 3, 2},  // Col 1: H ones (0-9)
  { 6, 7, 8,-1},  // Col 2: M tens (0-5)
  {12,11,10, 9},  // Col 3: M ones (0-9)
  {13,14,15,-1},  // Col 4: S tens (0-5)
  {19,18,17,16}   // Col 5: S ones (0-9)
};

I2C Expansion Port

The PCB has a broken-out I2C header (J1) so you can add sensors and peripherals without soldering. The bus is shared with the DS3231 RTC.

Ideas for I2C peripherals:

• BME280 / BME680: Temperature, humidity, air quality — display readings in binary
• SCD40: CO2 monitor — flash a warning color when levels are high
• Piezo buzzer: Hourly chime or alarm

Tip: The DS3231 RTC has a built-in temperature sensor you can query in code: float tempC = rtc.getTemperature(); — no extra hardware needed.

LED Status Codes

During boot and runtime, the clock communicates its status through LED patterns:

Factory Reset

A factory reset clears all saved data — WiFi credentials, settings, and manual time.

1. Unplug the clock.
2. Hold the boot button (GPIO9 — the small button on the XIAO board).
3. While holding the button, plug in the USB-C cable.
4. Keep holding for 3 seconds. You'll see 5 yellow blinks confirming the reset.
5. The clock will restart in first-time setup mode (blue blinking, AP mode).

Note: Factory reset only clears software settings. It does not erase the firmware — your code stays intact. To re-flash the firmware itself, use USB or OTA.

Debugging

The firmware outputs detailed diagnostics over the serial port at 115200 baud. Connect via USB and open a serial monitor to see:

╔══════════════════════════╗
║   BINESSE CLOCK v9.6     ║
╚══════════════════════════╝

TZ: EST5EDT,M3.2.0,M11.1.0 | Bright: 74 | 24h: 1 | Sec: 1 | Mode: 0

--- WiFi ---
Connecting to saved WiFi... OK!
✓ WiFi connected: 192.168.1.42
✓ Web server started on port 80

--- RTC ---
✓ RTC: 2025-03-15 14:30:45

--- NTP ---
  ✓ NTP: 2025-03-15 14:30:46
Time source: RTC

--- Clock Running ---

Common Issues

Serial Monitor Tips

• PlatformIO: Click the plug icon in the bottom toolbar, or run pio device monitor.
• Arduino IDE: Tools → Serial Monitor, set baud to 115200.
• Web-based: Visit http://[IP]/diag for real-time diagnostics without a USB connection.

Binesse Clock Firmware v9.6 · GitHub · Labs & Cookbook · binesse.com