<stránka
	xmlns="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/strana"
	xmlns:m="https://trac.frantovo.cz/xml-web-generator/wiki/xmlns/makro">
	
	<nadpis>cadMousePro</nadpis>
	<perex>CLI tool, D-Bus service and a GUI application for configuring the CadMouse Pro.</perex>
	<pořadí>020</pořadí>

	<text xmlns="http://www.w3.org/1999/xhtml">
		<p>
			The cadMousePro is an independent free tool for configuring 3DConnexion CadMouse Pro.
		</p>
		
		<h2>Architecture</h2>
		
		<p>
			The cadMousePro consists of two parts:
		</p>
		
		<p>
			The first one is a command line utility which sends configuration to the mouse as a USB HID message.
			This utility can also run in daemon mode and expose a D-Bus interface that could be called by other apllication.
			This tool must run under <code>root</code> or other user who has permissions to access the USB device.
		</p>
		
		<p>
			The second part is a simple GUI apllication which shows mouse status (name and battery level) and can configure the mouse.
			This GUI layer connects to the daemon using the D-Bus interface.
			Thus the GUI can run under any user (can be restricted using the D-Bus rules, if needed).
			The information about the battery level is provided by the UPower daemon (also over a D-Bus interface).
		</p>
		
		<m:diagram><![CDATA[
			node            [shape="box", fontname="Ubuntu,Sans"];
			
			usb             [label="USB HID"]
			daemon          [label="cadMousePro Daemon"]
			cli             [label="cadMousePro CLI"]
			gui             [label="cadMousePro GUI"]
			other           [label="Other D-Bus client"]
			upower          [label="UPower"]
			
			other -> daemon;
			gui -> daemon;
			gui -> upower;
			
			cli -> usb;
			daemon -> usb;
			upower -> usb;
		]]></m:diagram>
		
		<h2>Features</h2>
		
		<p>Mouse status:</p>
		<m:img src="img/cadMousePro-status-adwaita-v0.3.png"/>
		
		<p>Mouse configuration:</p>
		<m:img src="img/cadMousePro-configuration-adwaita-v0.3.png"/>
		
		<p>About:</p>
		<m:img src="img/cadMousePro-about-adwaita-v0.3.png"/>
		
		<h2>Disable Smart scrolling (free wheel)</h2>
		
		<p>
			The CadMouse Pro has a feature called „smart“ scrolling (also know as „free wheel“)
			which is actually not so smart and is rather an anti-feature and most users will probably want to disable it.
		</p>
		
		<p>
			This feature simulates the momentum – if you scroll bit faster, the mouse continue to send scroll events even if you have already stopped scrolling the wheel.
			So you scroll, stop scrolling, move cursor to another window… but the mouse still scrolls and you get angry 
			(especially it that another window was a taskbar and your windows are now fiercely switching).
		</p>
		
		<h2>Build and installation</h2>

		<p>We use the CMake build system, so the steps are basically:</p>
		
		<pre><![CDATA[mkdir build && cd build && cmake .. && make]]></pre>
		
		<p>Required libraries:</p>
		
		<ul>
			<li>hidapi-hidraw</li>
			<li>Qt</li>
		</ul>
		
		<p>
			Old version <code>v0.1</code> requires only <code>hidapi-hidraw</code> and has no GUI nor D-Bus interface.
		</p>
		
		<p>
			The daemon mode requires instalation of the D-Bus policy (in order to expose the service on the system bus and allow others to use it).
			Template for policy is in file: 
		</p>
		<pre>config/etc/dbus-1/system.d/info.globalcode.mouse.cadMousePro.conf</pre>
		
		<p>
			If we want to configure the mouse automatically when it is connected, we should install a udev rule.
			Template for udev rule is in file:
		</p>
		<pre>config/etc/udev/rules.d/99-cadMousePro.rules</pre>
		
		<h2>Usage</h2>

		<p>
			For ad-hoc configuration we just run:
		</p>
		
		<pre>sudo ./cadMousePro --frequency 250 --smart-scrolling false --lift-off-detection true</pre>
		
		<p>
			The daemon is started in this way:
		</p>
		
		<pre>sudo ./cadMousePro --daemon true</pre>
						
		<h2>3DConnexion CadMouse Pro Wireless</h2>
		<p>Our software works with this mouse:</p>
		<m:img src="img/3DConnexion-CadMouse-Pro-1.jpeg"/>
		<m:usb-id/>
		
	</text>

</stránka>