Contributing

OpenLogi is experimental and testing help is especially valuable; support is limited by the devices contributors can test against. Device reports are as useful as patches: the repository has an issue template for them.

• Source: github.com/AprilNEA/OpenLogi
• Build from source: DEVELOPMENT.md — including openlogi-agent-mock, which lets you work on the GUI with no hardware attached
• Translations: Crowdin

Contribute a device fixture

OpenLogi v0.8.4 added a guided way to contribute a sanitized device profile and, for HID++ devices, replayable read cases. Work from a clone of the OpenLogi repository and read the full recording workflow before capturing.

Choose a synthetic specimen ID—never a serial number or other hardware ID—and use a new output directory whose basename exactly matches --id. --name is a human-readable synthetic name. --device must be either a case-insensitive exact display name or an exact rendered route; omit it only when there is one candidate. Ambiguous selection is rejected.

With the real agent for that device running, and with OPENLOGI_PROFILE set to the same profile as the agent when you use a non-default profile, run:

openlogi fixture contribute \
  --id mx-master-3s-001 \
  --name "MX Master 3S" \
  --device "MX Master 3S" \
  --output fixtures/devices/mx-master-3s-001

The first phase reads semantic state through the agent; it does not fall back to direct hardware access. For an HID++ fixture, follow the command's prompt: stop that same agent and competing hardware clients such as Options+ or Solaar, then rerun the identical command with the same physical device and route. The CLI holds the selected profile's agent lock during direct capture and refuses an active or unhealthy agent endpoint. Do not delete locks or switch profiles to bypass that check. Receiver discovery may enable notification flags and request arrival reports, so the direct phase is not a zero-write session, even though the eight recorded operations do not change settings or pairings.

Use --profile-only when direct CLI hardware access is not authorized; raw-HID standalone devices select this mode automatically. Finally, verify the result offline:

openlogi fixture verify fixtures/devices/mx-master-3s-001

This checks the schema, privacy ledger, relationships, and replay framing. It does not access hardware or prove that the captured semantic values are correct.

Develop with a mock profile

openlogi-agent-mock can load a fixture's semantic profile.json and serve the normal agent IPC contract without opening hardware:

cargo run -p openlogi-agent --bin openlogi-agent-mock -- \
  --fixture fixtures/devices/mx-master-3s-001/profile.json

Fixture mode keeps battery, camera, foreground-app, and pairing state frozen for repeatable UI work. Running the mock without --fixture uses its animated built-in demo instead. See the openlogi-agent-mock source for the current behavior and launch examples.

Acknowledgments

• Windows port by @davidbudnick — the input hook, MSI in-app updates, tray and settings parity
• Linux port by @cserby — the evdev/uinput hook, D-Bus actions, .deb / .rpm packaging
• hidpp by @lus — vendored as openlogi-hidpp
• Solaar by @pwr — the most complete open-source HID++ implementation, and OpenLogi's protocol reference
• Mouser by @TomBadash — prior art for a local, account-free Options+ replacement

License

Dual-licensed under Apache-2.0 or MIT, at your option. The vendored openlogi-hidpp crate is 0BSD. The OpenLogi name, logo, and app icon are not covered by those licenses; see design/LICENSE.