XMouseD.guide

@database XMouseD.guide
@author "Vincent Buzzano"
@$VER: 1.0

@node main "XMouseD"
@next basicusage
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                               @{b}XMouseD v1.0@{ub}
                        SAGA eXtended Mouse Driver
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{fg highlight}XMouseD@{fg text} is a lightweight background daemon that enables mouse wheel scrolling
and extra buttons (4/5) support on Vampire/@{b}Apollo@{ub} @{b}SAGA@{ub} systems.

It monitors USB mouse hardware directly from @{b}SAGA@{ub} chipset registers and
injects standard NewMouse-compatible events into the Amiga input system.

@{b}Result:@{ub} Your mouse wheel works everywhere - no app modifications needed!

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}TABLE OF CONTENTS@{ub}

  @{" Basic Usage          " link basicusage} - Commands and controls
  @{" Polling Modes        " link pollingmodes} - Adaptive vs Normal modes
  @{" Configuration        " link configuration} - Detailed settings
  @{" Compatibility        " link compatibility} - Supported hardware/OS
  @{" Troubleshooting      " link troubleshooting} - Common issues
  @{" Technical Details    " link technical} - How it works
  @{" License & Credits    " link license} - MIT License, author info

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node basicusage "Basic Usage"
@prev main
@next pollingmodes
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                              @{b}BASIC USAGE@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Command Line Syntax@{ub}

  XMouseD                  - Toggle (start/stop)
  XMouseD START            - Start with default config
  XMouseD STOP             - Stop daemon
  XMouseD 0x<byte>         - Start/update with config byte

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Common Commands@{ub}

  XMouseD 0x13             - BALANCED mode (default, recommended)
  XMouseD 0x03             - COMFORT mode (low CPU usage)
  XMouseD 0x23             - REACTIVE mode (instant response)
  XMouseD 0x53             - ACTIVE normal mode (constant 10ms)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Hot Configuration Update@{ub}

You can change settings @{b}without restarting@{ub} the daemon!

Example:
  XMouseD 0x13             - Start in BALANCED mode
  XMouseD 0x23             - Switch to REACTIVE mode (instant!)
  XMouseD 0x53             - Switch to ACTIVE mode

XMouseD detects the running daemon and sends a configuration message
instead of starting a new instance.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

See @{" Polling Modes " link pollingmodes} to understand adaptive vs normal modes.
See @{" Configuration " link configuration} for detailed config byte format.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node pollingmodes "Polling Modes"
@prev basicusage
@next configuration
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                             @{b}POLLING MODES@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

XMouseD offers two polling strategies: @{b}Adaptive@{ub} and @{b}Normal@{ub}.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}ADAPTIVE vs NORMAL - What is the difference?@{ub}

  @{b}Adaptive@{ub}: polling speed changes automatically based on your activity.
    - Slow when idle  (saves CPU, mouse "asleep")
    - Speeds up when you start scrolling
    - Returns to slow after a pause
    Result: best of both worlds - efficient at rest, reactive when needed.

  @{b}Normal@{ub}: polling speed is constant, never changes.
    - Always polls at the same fixed interval
    - No transitions, fully predictable behaviour
    - Slightly higher average CPU usage than adaptive idle
    Result: consistent feel, good if you dislike any variation.

  @{fg shine}In practice most users will not notice the difference.@{fg text}
  Adaptive BALANCED (0x13) is the recommended starting point.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}ADAPTIVE MODES - ranked slowest to fastest burst speed@{ub}

The name describes the @{b}character@{ub} of the mode, not a ranking.
Burst speed (peak reactivity when actively scrolling) is what matters most.

  @{b}ECO@{ub}        (0x33) - @{fg shine}Slowest burst: 40ms@{fg text}
                    Idle 200ms -> Active 80ms -> Burst 40ms
                    Minimal CPU. For light users or low-power setups.
                    Scroll feel: slightly sluggish under fast movements.

  @{b}COMFORT@{ub}    (0x03) - @{fg shine}Burst: 20ms@{fg text}
                    Idle 150ms -> Active 60ms -> Burst 20ms
                    Relaxed. Good for occasional, unhurried scrolling.

  @{b}BALANCED@{ub}   (0x13) - @{fg shine}Burst: 10ms@{fg text} @{b}[DEFAULT]@{ub}
                    Idle 100ms -> Active 30ms -> Burst 10ms
                    Best for most users. Responsive without wasting CPU.

  @{b}REACTIVE@{ub}   (0x23) - @{fg shine}Fastest burst: 5ms@{fg text}
                    Idle 50ms -> Active 15ms -> Burst 5ms
                    Instant response. For power users and fast scrolling.
                    Higher CPU usage when scrolling.

  Summary: ECO < COMFORT < BALANCED < REACTIVE (burst reactivity)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}NORMAL MODES - constant polling, ranked slowest to fastest@{ub}

  @{b}PASSIVE@{ub}     (0x73) - Constant 40ms  - minimal CPU, slow detection
  @{b}MODERATE@{ub}    (0x43) - Constant 20ms  - light use
  @{b}ACTIVE@{ub}      (0x53) - Constant 10ms  - equivalent to BALANCED burst
  @{b}INTENSIVE@{ub}   (0x63) - Constant  5ms  - equivalent to REACTIVE burst
                               always-on, highest CPU usage

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Which Mode Should I Choose?@{ub}

  - @{b}Most users@{ub}:       BALANCED (0x13) adaptive - best balance
  - @{b}Low-power/quiet@{ub}:  ECO (0x33) adaptive or PASSIVE (0x73) normal
  - @{b}Fast scrolling@{ub}:   REACTIVE (0x23) adaptive
  - @{b}Predictable feel@{ub}: ACTIVE (0x53) normal (same speed as BALANCED burst)

Try different modes to find your preference! Change anytime with
hot config update (no restart needed).

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node configuration "Configuration Details"
@prev pollingmodes
@next compatibility
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                          @{b}CONFIGURATION DETAILS@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Config Byte Format@{ub}

XMouseD uses a single hex byte (0x00-0xFF) to configure all settings:

  @{b}Bit 0 (0x01)@{ub}  - Wheel enabled (scroll events)
  @{b}Bit 1 (0x02)@{ub}  - Extra buttons 4 & 5 enabled
  @{b}Bits 2-3@{ub}     - Reserved (must be 0)
  @{b}Bits 4-6@{ub}     - Polling mode selection (see below)
  @{b}Bit 7@{ub}        - Reserved (do not use)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Polling Mode Selection (Bits 4-6)@{ub}

  Bit 6 = 0: @{b}Adaptive Modes@{ub} (dynamic polling)
    Bits 4-5:
      00 = COMFORT   (0x03)
      01 = BALANCED  (0x13) [default]
      10 = REACTIVE  (0x23)
      11 = ECO       (0x33)

  Bit 6 = 1: @{b}Normal Modes@{ub} (constant polling)
    Bits 4-5:
      00 = MODERATE  (0x43) - 20ms
      01 = ACTIVE    (0x53) - 10ms
      10 = INTENSIVE (0x63) - 5ms
      11 = PASSIVE   (0x73) - 40ms

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Common Configuration Examples@{ub}

  @{b}0x13@{ub}  - Wheel ON, Buttons ON, BALANCED adaptive (DEFAULT)
  @{b}0x03@{ub}  - Wheel ON, Buttons ON, COMFORT adaptive
  @{b}0x23@{ub}  - Wheel ON, Buttons ON, REACTIVE adaptive
  @{b}0x33@{ub}  - Wheel ON, Buttons ON, ECO adaptive
  @{b}0x43@{ub}  - Wheel ON, Buttons ON, MODERATE normal (20ms)
  @{b}0x53@{ub}  - Wheel ON, Buttons ON, ACTIVE normal (10ms)
  @{b}0x63@{ub}  - Wheel ON, Buttons ON, INTENSIVE normal (5ms)
  @{b}0x73@{ub}  - Wheel ON, Buttons ON, PASSIVE normal (40ms)
  @{b}0x01@{ub}  - Wheel only, no buttons, COMFORT mode
  @{b}0x02@{ub}  - Buttons only, no wheel, COMFORT mode

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node compatibility "Hardware & OS Compatibility"
@prev configuration
@next troubleshooting
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                       @{b}HARDWARE & OS COMPATIBILITY@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

XMouseD requires @{b}Apollo@{ub} 68080 accelerators with @{b}SAGA@{ub} chipset.

@{fg shine}Confirmed Compatible:@{fg text}
  - Vampire V4 Standalone (Firebird)
  - A6000 Unicorn (untested but should work)

@{fg shine}Should Work (untested):@{fg text}
  - Vampire V4 Icedrake
  - Vampire V4 Manticore
  - Vampire V4 Salamander
  - Vampire V4 Phoenix

@{b}Requirements:@{ub}
  - USB mouse with scroll wheel connected to @{b}SAGA@{ub} USB port
  - Optional: Extra buttons 4 & 5 (if your mouse has them)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}SUPPORTED OPERATING SYSTEMS@{ub}

  - @{b}AmigaOS 3.x@{ub} (3.0, 3.1, 3.1.4, 3.2, 3.9 - all versions supported)
  - @{b}@{b}Apollo@{ub}OS 9.x@{ub} (AROS-based, fully compatible)
  - @{b}AROS@{ub} (should work, @{b}Apollo@{ub}OS is AROS-based)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}DOES NOT WORK ON@{ub}

XMouseD will @{b}NOT@{ub} function on these platforms:

  - Vampire V2 (has @{b}SAGA@{ub} but no USB mouse port)
  - Classic Amiga (A500, A1200, A4000, etc.)
  - Emulators (UAE, WinUAE, FS-UAE)
  - Other accelerators (Blizzard, @{b}Apollo@{ub} 1260, PiStorm)
  - AmigaOS 4.x, MorphOS, AROS x86

@{fg shine}Reason:@{fg text} XMouseD reads directly from @{b}SAGA@{ub} hardware registers
at $DFF212/$DFF213 which only exist on @{b}Apollo@{ub} @{b}SAGA@{ub} chipsets.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}COMPATIBILITY WITH OTHER SOFTWARE@{ub}

XMouseD is compatible with:
  - @{b}IControl@{ub} (AmigaOS 3.2 preferences)
  - @{b}FreeWheel@{ub} (Aminet commodity)
  - @{b}Other NewMouse-compatible tools@{ub}

XMouseD injects standard NewMouse events (IECLASS_NEWMOUSE with
NM_WHEEL_UP/DOWN codes), so any software supporting NewMouse
protocol will recognize the wheel.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node troubleshooting "Troubleshooting"
@prev compatibility
@next technical
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                           @{b}TROUBLESHOOTING@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Wheel Not Working@{ub}

  1. Verify your hardware:
     - Do you have a Vampire V4/A6000 with @{b}SAGA@{ub} chipset?
     - Is your USB mouse connected to the @{b}SAGA@{ub} USB port?
     - Does your mouse have a scroll wheel?

  2. Check if XMouseD is running:
     - Run: @{b}XMouseD@{ub} (should say "already running" or start)

  3. Test with a different application
     - Some apps may not support NewMouse wheel events

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Cannot Stop Daemon@{ub}

  - Run: @{b}XMouseD STOP@{ub}
  - If that fails, find the process and send CTRL+C signal
  - Last resort: reboot (daemon stops automatically)

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Extra Buttons 4/5 Not Working@{ub}

  1. Verify your mouse supports buttons 4 & 5
  2. Ensure bit 1 is enabled in config (0x02)
     - Example: @{b}XMouseD 0x13@{ub} has buttons enabled
     - @{b}XMouseD 0x11@{ub} would disable buttons

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Still Having Issues?@{ub}

  - Report bugs on GitHub with detailed description
  - Check @{b}SAGA@{ub} register $DFF212 for hardware values

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node technical "Technical Details"
@prev troubleshooting
@next license
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                           @{b}TECHNICAL DETAILS@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}How XMouseD Works@{ub}

1. @{b}Background Daemon@{ub}
   XMouseD runs as a detached background process with public port
   "XMouseD" for external control.

2. @{b}Hardware Polling@{ub}
   Timer-based polling (UNIT_VBLANK timer device):
   - Reads @{b}SAGA@{ub} register $DFF213 (wheel counter, 8-bit signed)
   - Reads @{b}SAGA@{ub} register $DFF212 bits 8-9 (buttons 4 & 5)

3. @{b}Delta Calculation@{ub}
   Tracks last wheel position and calculates signed delta:
   - Handles 8-bit wrap-around (255->0, 0->255)
   - Clamps to +/- 256 range

4. @{b}Event Injection@{ub}
   Sends input events via input.device:
   - IECLASS_RAWKEY with NM_WHEEL_UP/DOWN codes
   - IECLASS_NEWMOUSE with NM_WHEEL_UP/DOWN codes
   - Both events sent for maximum compatibility

5. @{b}Adaptive Polling@{ub}
   Dynamically adjusts polling interval based on activity:
   - IDLE state: slow polling (100-200ms)
   - ACTIVE state: medium polling (30-80ms)
   - BURST state: fast polling (10-40ms)
   - Smooth transitions with configurable thresholds

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Public Port Protocol@{ub}

XMouseD listens on port "XMouseD_Port" for control messages:

  @{b}XMSG_CMD_QUIT@{ub} (0)         - Stop daemon
  @{b}XMSG_CMD_SET_CONFIG@{ub} (1)   - Update config byte
  @{b}XMSG_CMD_GET_STATUS@{ub} (2)   - Query current status

This allows external tools (future XMouseCtrl GUI) to control
the daemon without restarting it.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode

@node license "License & Credits"
@prev technical
@toc main
@{fg highlight}------------------------------------------------------------------------------@{fg text}
@{fg highlight}
                           @{b}LICENSE & CREDITS@{ub}
@{fg text}
@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}MIT License@{ub}

Copyright (c) 2025 Vincent Buzzano

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject
to the following conditions:

The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Credits@{ub}

  @{b}Author@{ub}:        Vincent Buzzano
  @{b}Version@{ub}:       1.0
  @{b}Date@{ub}:          2025-12-18
  @{b}Toolchain@{ub}:     VBCC m68k-amigaos compiler
  @{b}Target@{ub}:        Vampire/@{b}Apollo@{ub} @{b}SAGA@{ub} 68080

@{b}Special Thanks@{ub}:
  - @{b}Apollo@{ub} Team for @{b}SAGA@{ub} chipset documentation
  - Amiga community for NewMouse protocol
  - VBCC developers for excellent m68k compiler

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@{b}Support & Feedback@{ub}

  @{b}GitHub@{ub}:  https://github.com/vbuzzano/XMouseD-SAGA/issues
  @{b}Issues@{ub}:  Report bugs or request features on GitHub
  @{b}Discord@{ub}: Join the @{b}Apollo@{ub} community for support

@{fg highlight}------------------------------------------------------------------------------@{fg text}

                @{fg shine}Thank you for using XMouseD!@{fg text}

@{fg highlight}------------------------------------------------------------------------------@{fg text}

@endnode