Arduino Library

The moddoMOUSE Arduino Library provides a simple API for communicating with the moddoMOUSE Main Board over I2C/TWI, handling all the low-level register reads and writes for you.

Installation

The library is officially listed in the Arduino Library Manager. To install it:

Open the Arduino IDE
Go to Sketch → Include Library → Manage Libraries
Search for moddoMOUSE
Select latest version and click Install

My image

Alternatively, you can install it manually by downloading the ZIP from the GitHub repository and going to:

Sketch → Include Library → Add .ZIP Library

Getting Started

Include the library and create a moddoMOUSE object at the top of your sketch:

#include <moddoMOUSE.h>

moddoMOUSE mouse;

Then call begin() in your setup() to initialise the connection:

if (mouse.begin() != 0) {
    Serial.println("Failed to connect to moddoMOUSE");
}

begin() verifies the product ID of the Main Board and clears any previously set interrupts. It accepts optional parameters if you need to specify a custom I2C address or TwoWire instance:

mouse.begin(MODDOMOUSE_I2C_ADDRESS, Wire);

Error Handling

All library methods return an int8_t. A return value of 0 indicates success. Negative values indicate an error:

Return Value	Meaning
`0`	Success
`-EIO (–5)`	I2C communication error
`-EINVAL (–22)`	Invalid argument (e.g. value out of range)

Low Power

Since the expansion board is powered by the mouse battery, keeping power consumption low is important. The library provides suspend() and resume() to release and re-acquire the I2C bus around sleep periods:

mouse.suspend();
LowPower.sleep(); // e.g. using ArduinoLowPower library
mouse.resume();

All the included examples support low power mode when running on a SAMD-based Arduino (e.g., Arduino MKR Zero and Seeed XIAO M0). To enable it, set USE_LOW_POWER_IF_SUPPORTED to 1 at the top of the sketch and it is enabled by default. Without low power support, idle power consumption can be approximately 200x higher, which will drain the mouse battery significantly faster.

💡 Low power mode disables Serial output and USB. If you are debugging, set USE_LOW_POWER_IF_SUPPORTED to 0 to keep Serial and USB active.

API Reference

Initialization

Method	Description
`begin(address, wirePort)`	Initialise I2C connection to the Main Board. `address` defaults to `0x0A`, `wirePort` defaults to `Wire`. Returns `0` on success.
`suspend()`	Release the I2C bus. Call before putting the microcontroller to sleep to save power.
`resume()`	Re-acquire the I2C bus. Call after waking from sleep.

Device Info

Method	Description
`getProductID(value)`	Reads the product ID into `*value`. Always `0x01` for moddoMOUSE.
`getDeviceID(value)`	Reads the unique 16-bit device ID into `*value`.

Motion

Method	Description
`getMotion(x, y)`	Reads accumulated X/Y motion deltas into `x` and `y`. Resets the accumulator on read. Either pointer can be `NULL` to ignore that axis.

Buttons

Method	Description
`getMainButtons(left, right, middle, back, forward)`	Reads the current state of the five main mouse buttons. Any pointer can be `NULL` to ignore that button.
`setButtons(button_bits)`	Writes a 32-bit bitmask of expansion board button states to the Main Board. Each bit represents one button: set to `1` when pressed, `0` when released.

Battery

Method	Description
`getBatteryStatus(status)`	Reads battery and charger status into a `batteryStatus` struct.

Scroll Wheels

Method	Description
`setVerticalWheel(delta)`	Sends a vertical scroll delta to the Main Board.
`getVerticalWheel(delta)`	Reads the current accumulated vertical scroll delta into `*delta`.
`setHorizontalWheel(delta)`	Sends a horizontal scroll delta to the Main Board.
`getHorizontalWheel(delta)`	Reads the current accumulated horizontal scroll delta into `*delta`.

Settings

Method	Description
`setDpiSettings(x, y)`	Sets the DPI/CPI for X and Y axes independently. Valid range: 50–26,000.
`getDpiSettings(x, y)`	Reads the current DPI/CPI settings into `x` and `y`.
`setPollingRate(pollingRate)`	Sets the polling rate. One of: `POLLING_RATE_125`, `POLLING_RATE_250`, `POLLING_RATE_500`, `POLLING_RATE_1000`.
`getPollingRate(pollingRate)`	Reads the current polling rate into `*pollingRate`.
`setLiftDistance(liftDistance)`	Sets the lift-off distance. One of: `LIFT_DISTANCE_1MM`, `LIFT_DISTANCE_2MM`.
`getLiftDistance(liftDistance)`	Reads the current lift-off distance into `*liftDistance`.
`setInvertSwapSettings(invert_x, invert_y, swap_xy)`	Sets axis inversion and swap.
`getInvertSwapSettings(invert_x, invert_y, swap_xy)`	Reads current axis inversion and swap settings.
`setAngleTune(angle)`	Sets the angle tune offset in degrees. Valid range: –30 to +30.
`getAngleTune(angle)`	Reads the current angle tune offset into `*angle`.

Interrupts

Method	Description
`setMotionInterrupt(enable)`	Enables or disables the motion interrupt on the INT pin.
`setMainButtonsInterrupt(enable)`	Enables or disables the main buttons interrupt on the INT pin.
`setBatteryChangeInterrupt(enable)`	Enables or disables the battery change interrupt on the INT pin.
`disableAllInterrupts()`	Disables all interrupts and clears the INT pin state.

Data Types

`batteryStatus`

Field	Type	Description
`batteryVoltage`	`uint16_t`	Battery voltage in millivolts
`batteryCapacity`	`uint8_t`	Battery capacity in percent (0–100), or `255` (`MODDOMOUSE_BAT_CAPACITY_UNKNOWN`) if unknown
`batteryPresent`	`uint8_t` (1 bit)	`1` if a battery is connected
`batteryCharging`	`uint8_t` (1 bit)	`1` if charging, `0` if discharging
`health`	`uint8_t` (5 bits)	Charger health condition — see `charger_health` enum
`externalSupply`	`uint8_t` (1 bit)	`1` if USB power is connected

`charger_health` Enum

Value	Description
`CHARGER_HEALTH_UNKNOWN`	Health condition unknown
`CHARGER_HEALTH_GOOD`	Charger is healthy
`CHARGER_HEALTH_OVERHEAT`	Charger is overheated
`CHARGER_HEALTH_OVERVOLTAGE`	Battery voltage exceeded overvoltage threshold
`CHARGER_HEALTH_UNSPEC_FAILURE`	Unspecified failure
`CHARGER_HEALTH_COLD`	Battery temperature below cold threshold
`CHARGER_HEALTH_WATCHDOG_TIMER_EXPIRE`	Watchdog timer expired
`CHARGER_HEALTH_SAFETY_TIMER_EXPIRE`	Safety timer expired
`CHARGER_HEALTH_CALIBRATION_REQUIRED`	Calibration required
`CHARGER_HEALTH_WARM`	Battery temperature in warm range
`CHARGER_HEALTH_COOL`	Battery temperature in cool range
`CHARGER_HEALTH_HOT`	Battery temperature above hot threshold
`CHARGER_HEALTH_NO_BATTERY`	No battery detected

`pollingRateOptions` Enum

Value	Polling Rate
`POLLING_RATE_125`	125 Hz
`POLLING_RATE_250`	250 Hz
`POLLING_RATE_500`	500 Hz
`POLLING_RATE_1000`	1000 Hz

`liftDistanceOptions` Enum

Value	Lift Distance
`LIFT_DISTANCE_1MM`	1mm
`LIFT_DISTANCE_2MM`	2mm

Installation​

Getting Started​

Error Handling​

Low Power​

API Reference​

Initialization​

Device Info​

Motion​

Buttons​

Battery​

Scroll Wheels​

Settings​

Interrupts​

Data Types​

batteryStatus​

charger_health Enum​

pollingRateOptions Enum​

liftDistanceOptions Enum​