Eku (Mouse)

Eku (eku is the Yoruba word for mouse) is a cross-platform desktop tool for detecting, monitoring, diagnosing and — where a device's protocol is proven, configuring computer mice. It is written primarily in C (C17) and targets Windows 10/11 and Linux.

The project is developed and owned by Yemeeverse Innovations LTD.

Development follows an internal specification, AGENT.md, which is not distributed; code and documentation cite it by section so that rules stay traceable. If you are reading this without access to it, see docs/specification.md for what it covers and where the equivalent detail lives in this repository.

Its guiding rule is that it never invents hardware data. If a mouse reports 73%, Eku shows 73%. If it reports nothing, Eku says so. If a capability has not been proven, it is shown as Unknown, not as a feature that might work.

The first target device is a developer-owned dual-wireless rechargeable mouse (USB 2.4 GHz receiver and Bluetooth, rechargeable battery). The architecture is written from the start so other mice and manufacturers can be added.

Features

Implemented in the current tree:

• HID device enumeration on Linux through sysfs, with no privilege required.
• Device identity: VID, PID, manufacturer, product, serial where available, interface list and connection classification with recorded evidence.
• HID report-descriptor parsing: report ids, collections, fields, bit offsets, logical ranges and per-report byte lengths.
• Structured HID report validation and mouse decoding (buttons, X/Y, wheel, tilt wheel), with bounds checking and malformed-input handling.
• A device model where capabilities are Supported / Unsupported / Unknown / Requires permission, never guessed from a product name.
• Connection/disconnection detection and periodic re-scan (hot-plug), without restarting.
• A bounded internal event bus with a dispatcher thread, used for low-rate events.
• A round-robin HID monitor thread with a raw-report capture ring.
• SQLite persistence (schema v3) with append-only migrations, battery history, charging sessions, connection sessions, polling tests, button events, device events, profiles and settings, plus crash repair and retention pruning.
• Battery monitoring on a configurable interval, charging-session tracking with edge-case handling, "last charge" and "last full charge", battery history and a consumption estimate that is explicitly labelled as an estimate.
• Diagnostics: an interactive button tester, a movement view, a polling-rate tester that reports a measured value (never the advertised one), a raw HID report monitor with capture export (txt/json/csv), diagnostic report export (txt/json), and battery and charging history export to CSV.
• A vendor driver architecture (MouseDriver, a registry and a generic driver) where a driver can only claim what it can prove.
• Software profiles with per-setting reporting of what the device actually accepted.
• Structured logging (TRACE…CRITICAL) and a key = value configuration file, with atomic saves and forward/backward-compatible preservation of unknown keys.
• A battery history graph drawn from the readings that were actually recorded.
• A system tray icon with a menu, desktop notifications for the battery thresholds, and a "start with the system" setting (XDG autostart on Linux, the Run key on Windows).
• A command-line front-end (eku) with 11 commands, and a GTK3 desktop front-end (eku-gui) with nine pages.
• Packaging through CPack: a portable .tar.gz and, on Debian-based systems, a .deb with the correct dependency list, shipping both front-ends, the documentation and the udev rule.
• Localisation-ready UI strings: user-visible text is looked up through a catalog (include/ui/strings.h) rather than written inline, so another language only needs another catalog.
• An application icon and a validated .desktop entry, installed into the standard icon theme and application directories.
• A minimal, dependency-free C test suite: 15 CTest executables (123 tests) covering string utilities, configuration, the event bus, capabilities, the device model, the platform backend, HID descriptor parsing, report decoding, the polling tester, the UI string catalog, the icon and desktop entry, the CSV exports, decoding of reports captured from real hardware, the database and end-to-end application wiring.

Using the command line

eku devices                      # list detected mice and their interfaces
eku info                         # details for the current device
eku capabilities                 # the full capability report, with evidence
eku battery                      # level, charge state, history and estimate
eku polling --window 2000        # measure the polling rate (MEASURED)
eku buttons --duration 10000     # live button tester
eku monitor --duration 5000 --export /tmp/cap.json --format json
eku diagnose --export /tmp/report.json --format json
eku doctor                       # environment and permission check
eku config list                  # inspect configuration
eku profiles list                # software profiles
eku export battery               # battery history as CSV
eku export charging              # charging history as CSV
eku help <command>               # usage for one command