1.\" Copyright (c) 1996 2.\" Mike Pritchard <mpp@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by Mike Pritchard. 15.\" 4. Neither the name of the author nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD: src/usr.sbin/moused/moused.8,v 1.47 2004/10/11 07:57:08 philip Exp $ 32.\" $DragonFly: src/usr.sbin/moused/moused.8,v 1.9 2008/02/08 10:17:40 matthias Exp $ 33.\" 34.Dd February 8, 2008 35.Dt MOUSED 8 36.Os 37.Sh NAME 38.Nm moused 39.Nd pass mouse data to the console driver 40.Sh SYNOPSIS 41.Nm 42.Op Fl DPRacdfs 43.Op Fl I Ar file 44.Op Fl F Ar rate 45.Op Fl r Ar resolution 46.Op Fl S Ar baudrate 47.Op Fl V Op Fl U Ar distance 48.Op Fl a Ar X Ns Op , Ns Ar Y 49.Op Fl C Ar threshold 50.Op Fl m Ar N=M 51.Op Fl w Ar N 52.Op Fl z Ar target 53.Op Fl t Ar mousetype 54.Op Fl l Ar level 55.Op Fl 3 Op Fl E Ar timeout 56.Fl p Ar port 57.Pp 58.Nm 59.Op Fl Pd 60.Fl p Ar port 61.Fl i Ar info 62.Sh DESCRIPTION 63The 64.Nm 65utility and the console driver work together to support 66mouse operation in the text console and user programs. 67They virtualize the mouse and provide user programs with mouse data 68in the standard format 69(see 70.Xr sysmouse 4 ) . 71.Pp 72The mouse daemon listens to the specified port for mouse data, 73interprets and then passes it via ioctls to the console driver. 74The mouse daemon 75reports translation movement, button press/release 76events and movement of the roller or the wheel if available. 77The roller/wheel movement is reported as ``Z'' axis movement. 78.Pp 79The console driver will display the mouse pointer on the screen 80and provide cut and paste functions if the mouse pointer is enabled 81in the virtual console via 82.Xr vidcontrol 1 . 83If 84.Xr sysmouse 4 85is opened by the user program, the console driver also passes the mouse 86data to the device so that the user program will see it. 87.Pp 88If the mouse daemon receives the signal 89.Dv SIGHUP , 90it will reopen the mouse port and reinitialize itself. 91Useful if 92the mouse is attached/detached while the system is suspended. 93.Pp 94The following options are available: 95.Bl -tag -width indent 96.It Fl 3 97Emulate the third (middle) button for 2-button mice. 98It is emulated 99by pressing the left and right physical buttons simultaneously. 100.It Fl C Ar threshold 101Set double click speed as the maximum interval in msec between button clicks. 102Without this option, the default value of 500 msec will be assumed. 103This option will have effect only on the cut and paste operations 104in the text mode console. 105The user program which is reading mouse data 106via 107.Xr sysmouse 4 108will not be affected. 109.It Fl D 110Lower DTR on the serial port. 111This option is valid only if 112.Ar mousesystems 113is selected as the protocol type. 114The DTR line may need to be dropped for a 3-button mouse 115to operate in the 116.Ar mousesystems 117mode. 118.It Fl E Ar timeout 119When the third button emulation is enabled 120(see above), 121the 122.Nm 123utility waits 124.Ar timeout 125msec at most before deciding whether two buttons are being pressed 126simultaneously. 127The default timeout is 100 msec. 128.It Fl F Ar rate 129Set the report rate (reports/sec) of the device if supported. 130.It Fl I Ar file 131Write the process id of the 132.Nm 133utility in the specified file. 134Without this option, the process id will be stored in 135.Pa /var/run/moused.pid . 136.It Fl P 137Do not start the Plug and Play COM device enumeration procedure 138when identifying the serial mouse. 139If this option is given together with the 140.Fl i 141option, the 142.Nm 143utility will not be able to print useful information for the serial mouse. 144.It Fl R 145Lower RTS on the serial port. 146This option is valid only if 147.Ar mousesystems 148is selected as the protocol type by the 149.Fl t 150option below. 151It is often used with the 152.Fl D 153option above. 154Both RTS and DTR lines may need to be dropped for 155a 3-button mouse to operate in the 156.Ar mousesystems 157mode. 158.It Fl S Ar baudrate 159Select the baudrate for the serial port (1200 to 9600). 160Not all serial mice support this option. 161.It Fl V 162Enable 163.Dq Virtual Scrolling . 164With this option set, holding the middle mouse 165button down will cause motion to be interpreted as scrolling. Use the 166.Fl U 167option to set the distance the mouse must move before the scrolling mode is 168activated. 169.It Fl a Ar X Ns Op , Ns Ar Y 170Accelerate or decelerate the mouse input. 171This is a linear acceleration only. 172Values less than 1.0 slow down movement, values greater than 1.0 speed it 173up. 174Specifying only one value sets the acceleration for both axes. 175.It Fl c 176Some mice report middle button down events 177as if the left and right buttons are being pressed. 178This option handles this. 179.It Fl d 180Enable debugging messages. 181.It Fl f 182Do not become a daemon and instead run as a foreground process. 183Useful for testing and debugging. 184.It Fl i Ar info 185Print specified information and quit. 186Available pieces of 187information are: 188.Pp 189.Bl -tag -compact -width modelxxx 190.It Ar port 191Port (device file) name, i.e.\& 192.Pa /dev/cuaa0 , 193.Pa /dev/mse0 194and 195.Pa /dev/psm0 . 196.It Ar if 197Interface type: serial, bus, inport or ps/2. 198.It Ar type 199Protocol type. 200It is one of the types listed under the 201.Fl t 202option below or 203.Ar sysmouse 204if the driver supports the 205.Ar sysmouse 206data format standard. 207.It Ar model 208Mouse model. 209The 210.Nm 211utility may not always be able to identify the model. 212.It Ar all 213All of the above items. 214Print port, interface, type and model in this order 215in one line. 216.El 217.Pp 218If the 219.Nm 220utility cannot determine the requested information, it prints ``unknown'' 221or ``generic''. 222.It Fl l Ar level 223Specifies at which level 224.Nm 225should operate the mouse driver. 226Refer to 227.Em Operation Levels 228in 229.Xr psm 4 230for more information on this. 231.It Fl m Ar N=M 232Assign the physical button 233.Ar M 234to the logical button 235.Ar N . 236You may specify as many instances of this option as you like. 237More than one physical button may be assigned to a logical button at the 238same time. 239In this case the logical button will be down, 240if either of the assigned physical buttons is held down. 241Do not put space around `='. 242.It Fl p Ar port 243Use 244.Ar port 245to communicate with the mouse. 246.It Fl r Ar resolution 247Set the resolution of the device; in Dots Per Inch, or 248.Ar low , 249.Ar medium-low , 250.Ar medium-high 251or 252.Ar high . 253This option may not be supported by all the device. 254.It Fl s 255Select a baudrate of 9600 for the serial line. 256Not all serial mice support this option. 257.It Fl t Ar type 258Specify the protocol type of the mouse attached to the port. 259You may explicitly specify a type listed below, or use 260.Ar auto 261to let the 262.Nm 263utility automatically select an appropriate protocol for the given 264mouse. 265If you entirely omit this option in the command line, 266.Fl t Ar auto 267is assumed. 268Under normal circumstances, 269you need to use this option only if the 270.Nm 271utility is not able to detect the protocol automatically 272(see 273.Sx "Configuring Mouse Daemon" ) . 274.Pp 275Note that if a protocol type is specified with this option, the 276.Fl P 277option above is implied and Plug and Play COM device enumeration 278procedure will be disabled. 279.Pp 280Also note that if your mouse is attached to the PS/2 mouse port, you should 281always choose 282.Ar auto 283or 284.Ar ps/2 , 285regardless of the brand and model of the mouse. 286Likewise, if your 287mouse is attached to the bus mouse port, choose 288.Ar auto 289or 290.Ar busmouse . 291Serial mouse protocols will not work with these mice. 292.Pp 293For the USB mouse, the protocol must be 294.Ar auto . 295No other protocol will work with the USB mouse. 296.Pp 297Valid types for this option are 298listed below. 299.Pp 300For the serial mouse: 301.Bl -tag -compact -width mousesystemsxxx 302.It Ar microsoft 303Microsoft serial mouse protocol. 304Most 2-button serial mice use this protocol. 305.It Ar intellimouse 306Microsoft IntelliMouse protocol. 307Genius NetMouse, 308.Tn ASCII 309Mie Mouse, 310Logitech MouseMan+ and FirstMouse+ use this protocol too. 311Other mice with a roller/wheel may be compatible with this protocol. 312.It Ar mousesystems 313MouseSystems 5-byte protocol. 3143-button mice may use this protocol. 315.It Ar mmseries 316MM Series mouse protocol. 317.It Ar logitech 318Logitech mouse protocol. 319Note that this is for old Logitech models. 320.Ar mouseman 321or 322.Ar intellimouse 323should be specified for newer models. 324.It Ar mouseman 325Logitech MouseMan and TrackMan protocol. 326Some 3-button mice may be compatible 327with this protocol. 328Note that MouseMan+ and FirstMouse+ use 329.Ar intellimouse 330protocol rather than this one. 331.It Ar glidepoint 332ALPS GlidePoint protocol. 333.It Ar thinkingmouse 334Kensington ThinkingMouse protocol. 335.It Ar mmhitab 336Hitachi tablet protocol. 337.It Ar x10mouseremote 338X10 MouseRemote. 339.It Ar kidspad 340Genius Kidspad and Easypad protocol. 341.It Ar versapad 342Interlink VersaPad protocol. 343.El 344.Pp 345For the bus and InPort mouse: 346.Bl -tag -compact -width mousesystemsxxx 347.It Ar busmouse 348This is the only protocol type available for 349the bus and InPort mouse and should be specified for any bus mice 350and InPort mice, regardless of the brand. 351.El 352.Pp 353For the PS/2 mouse: 354.Bl -tag -compact -width mousesystemsxxx 355.It Ar ps/2 356This is the only protocol type available for the PS/2 mouse 357and should be specified for any PS/2 mice, regardless of the brand. 358.El 359.Pp 360For the USB mouse, 361.Ar auto 362is the only protocol type available for the USB mouse 363and should be specified for any USB mice, regardless of the brand. 364.It Fl w Ar N 365Make the physical button 366.Ar N 367act as the wheel mode button. 368While this button is pressed, X and Y axis movement is reported to be zero 369and the Y axis movement is mapped to Z axis. 370You may further map the Z axis movement to virtual buttons by the 371.Fl z 372option below. 373.It Fl z Ar target 374Map Z axis (roller/wheel) movement to another axis or to virtual buttons. 375Valid 376.Ar target 377maybe: 378.Bl -tag -compact -width x__ 379.It Ar x 380.It Ar y 381X or Y axis movement will be reported when the Z axis movement is detected. 382.It Ar N 383Report down events for the virtual buttons 384.Ar N 385and 386.Ar N+1 387respectively when negative and positive Z axis movement 388is detected. 389There do not need to be physical buttons 390.Ar N 391and 392.Ar N+1 . 393Note that mapping to logical buttons is carried out after mapping 394from the Z axis movement to the virtual buttons is done. 395.It Ar N1 N2 396Report down events for the virtual buttons 397.Ar N1 398and 399.Ar N2 400respectively when negative and positive Z axis movement 401is detected. 402.It Ar N1 N2 N3 N4 403This is useful for the mouse with two wheels of which 404the second wheel is used to generate horizontal scroll action, 405and for the mouse which has a knob or a stick which can detect 406the horizontal force applied by the user. 407.Pp 408The motion of the second wheel will be mapped to the buttons 409.Ar N3 , 410for the negative direction, and 411.Ar N4 , 412for the positive direction. 413If the buttons 414.Ar N3 415and 416.Ar N4 417actually exist in this mouse, their actions will not be detected. 418.Pp 419Note that horizontal movement or second roller/wheel movement may not 420always be detected, 421because there appears to be no accepted standard as to how it is encoded. 422.Pp 423Note also that some mice think left is the negative horizontal direction; 424others may think otherwise. 425Moreover, there are some mice whose two wheels are both mounted vertically, 426and the direction of the second vertical wheel does not match the 427first one. 428.El 429.El 430.Ss Configuring Mouse Daemon 431The first thing you need to know is the interface type 432of the mouse you are going to use. 433It can be determined by looking at the connector of the mouse. 434The serial mouse has a D-Sub female 9- or 25-pin connector. 435The bus and InPort mice have either a D-Sub male 9-pin connector 436or a round DIN 9-pin connector. 437The PS/2 mouse is equipped with a small, round DIN 6-pin connector. 438Some mice come with adapters with which the connector can 439be converted to another. 440If you are to use such an adapter, 441remember the connector at the very end of the mouse/adapter pair is 442what matters. 443The USB mouse has a flat rectangular connector. 444.Pp 445The next thing to decide is a port to use for the given interface. 446For the bus, InPort and PS/2 mice, there is little choice: 447the bus and InPort mice always use 448.Pa /dev/mse0 , 449and the PS/2 mouse is always at 450.Pa /dev/psm0 . 451There may be more than one serial port to which the serial 452mouse can be attached. 453Many people often assign the first, built-in 454serial port 455.Pa /dev/cuaa0 456to the mouse. 457You can attach multiple USB mice to your system or to your USB hub. 458They are accessible as 459.Pa /dev/ums0 , /dev/ums1 , 460and so on. 461.Pp 462You may want to create a symbolic link 463.Pa /dev/mouse 464pointing to the real port to which the mouse is connected, so that you 465can easily distinguish which is your ``mouse'' port later. 466.Pp 467The next step is to guess the appropriate protocol type for the mouse. 468The 469.Nm 470utility may be able to automatically determine the protocol type. 471Run the 472.Nm 473utility with the 474.Fl i 475option and see what it says. 476If the command can identify 477the protocol type, no further investigation is necessary on your part. 478You may start the daemon without explicitly specifying a protocol type 479(see 480.Sx EXAMPLES ) . 481.Pp 482The command may print 483.Ar sysmouse 484if the mouse driver supports this protocol type. 485.Pp 486Note that the 487.Ar type 488and 489.Ar model 490printed by the 491.Fl i 492option do not necessarily match the product name of the pointing device 493in question, but they may give the name of the device with which it is 494compatible. 495.Pp 496If the 497.Fl i 498option yields nothing, you need to specify a protocol type to the 499.Nm 500utility by the 501.Fl t 502option. 503You have to make a guess and try. 504There is rule of thumb: 505.Pp 506.Bl -enum -compact -width 1.X 507.It 508The bus and InPort mice always use 509.Ar busmouse 510protocol regardless of the brand of the mouse. 511.It 512The 513.Ar ps/2 514protocol should always be specified for the PS/2 mouse 515regardless of the brand of the mouse. 516.It 517You must specify the 518.Ar auto 519protocol for the USB mouse. 520.It 521Most 2-button serial mice support the 522.Ar microsoft 523protocol. 524.It 5253-button serial mice may work with the 526.Ar mousesystems 527protocol. 528If it does not, it may work with the 529.Ar microsoft 530protocol although 531the third (middle) button will not function. 5323-button serial mice may also work with the 533.Ar mouseman 534protocol under which the third button may function as expected. 535.It 5363-button serial mice may have a small switch to choose between ``MS'' 537and ``PC'', or ``2'' and ``3''. 538``MS'' or ``2'' usually mean the 539.Ar microsoft 540protocol. 541``PC'' or ``3'' will choose the 542.Ar mousesystems 543protocol. 544.It 545If the mouse has a roller or a wheel, it may be compatible with the 546.Ar intellimouse 547protocol. 548.El 549.Pp 550To test if the selected protocol type is correct for the given mouse, 551enable the mouse pointer in the current virtual console, 552.Pp 553.Dl vidcontrol -m on 554.Pp 555start the mouse daemon in the foreground mode, 556.Pp 557.Dl moused -f -p Ar _selected_port_ -t Ar _selected_protocol_ 558.Pp 559and see if the mouse pointer travels correctly 560according to the mouse movement. 561Then try cut & paste features by 562clicking the left, right and middle buttons. 563Type ^C to stop 564the command. 565.Ss Multiple Mice 566As many instances of the mouse daemon as the number of mice attached to 567the system may be run simultaneously; one 568instance for each mouse. 569This is useful if the user wants to use the built-in PS/2 pointing device 570of a laptop computer while on the road, but wants to use a serial 571mouse when s/he attaches the system to the docking station in the office. 572Run two mouse daemons and tell the application program 573(such as the 574.Tn "X\ Window System" ) 575to use 576.Xr sysmouse 4 , 577then the application program will always see mouse data from either mouse. 578When the serial mouse is not attached, the corresponding mouse daemon 579will not detect any movement or button state change and the application 580program will only see mouse data coming from the daemon for the 581PS/2 mouse. 582In contrast when both mice are attached and both of them 583are moved at the same time in this configuration, 584the mouse pointer will travel across the screen just as if movement of 585the mice is combined all together. 586.Sh FILES 587.Bl -tag -width /dev/consolectl -compact 588.It Pa /dev/consolectl 589device to control the console 590.It Pa /dev/mse%d 591bus and InPort mouse driver 592.It Pa /dev/psm%d 593PS/2 mouse driver 594.It Pa /dev/sysmouse 595virtualized mouse driver 596.It Pa /dev/ttyv%d 597virtual consoles 598.It Pa /dev/ums%d 599USB mouse driver 600.It Pa /var/run/moused.pid 601process id of the currently running 602.Nm 603utility 604.It Pa /var/run/MouseRemote 605.Ux Ns -domain 606stream socket for X10 MouseRemote events 607.El 608.Sh EXAMPLES 609.Dl moused -p /dev/cuaa0 -i type 610.Pp 611Let the 612.Nm 613utility determine the protocol type of the mouse at the serial port 614.Pa /dev/cuaa0 . 615If successful, the command will print the type, otherwise it will say 616``unknown''. 617.Pp 618.Dl moused -p /dev/cuaa0 619.Dl vidcontrol -m on 620.Pp 621If the 622.Nm 623utility is able to identify the protocol type of the mouse at the specified 624port automatically, you can start the daemon without the 625.Fl t 626option and enable the mouse pointer in the text console as above. 627.Pp 628.Dl moused -p /dev/mouse -t microsoft 629.Dl vidcontrol -m on 630.Pp 631Start the mouse daemon on the serial port 632.Pa /dev/mouse . 633The protocol type 634.Ar microsoft 635is explicitly specified by the 636.Fl t 637option. 638.Pp 639.Dl moused -p /dev/mouse -m 1=3 -m 3=1 640.Pp 641Assign the physical button 3 (right button) to the logical button 1 642(logical left) and the physical button 1 (left) to the logical 643button 3 (logical right). 644This will effectively swap the left and right buttons. 645.Pp 646.Dl moused -p /dev/mouse -t intellimouse -z 4 647.Pp 648Report negative Z axis movement (i.e., mouse wheel) as the button 4 pressed 649and positive Z axis movement (i.e., mouse wheel) as the button 5 pressed. 650.Sh CAVEATS 651Many pad devices behave as if the first (left) button were pressed if 652the user `taps' the surface of the pad. 653In contrast, some ALPS GlidePoint and Interlink VersaPad models 654treat the tapping action 655as fourth button events. 656Use the option ``-m 1=4'' for these models 657to obtain the same effect as the other pad devices. 658.Pp 659Cut and paste functions in the virtual console assume that there 660are three buttons on the mouse. 661The logical button 1 (logical left) selects a region of text in the 662console and copies it to the cut buffer. 663The logical button 3 (logical right) extends the selected region. 664The logical button 2 (logical middle) pastes the selected text 665at the text cursor position. 666If the mouse has only two buttons, the middle, `paste' button 667is not available. 668To obtain the paste function, use the 669.Fl 3 670option to emulate the middle button, or use the 671.Fl m 672option to assign the physical right button to the logical middle button: 673``-m 2=3''. 674.Sh SEE ALSO 675.Xr kill 1 , 676.Xr vidcontrol 1 , 677.Xr keyboard 4 , 678.Xr mse 4 , 679.Xr psm 4 , 680.Xr screen 4 , 681.Xr sysmouse 4 , 682.Xr ums 4 683.Sh STANDARDS 684The 685.Nm 686utility partially supports 687.Dq Plug and Play External COM Device Specification 688in order to support PnP serial mice. 689However, due to various degrees of conformance to the specification by 690existing serial mice, it does not strictly follow the version 1.0 of the 691standard. 692Even with this less strict approach, 693it may not always determine an appropriate protocol type 694for the given serial mouse. 695.Sh HISTORY 696The 697.Nm 698utility first appeared in 699.Fx 2.2 . 700.Sh AUTHORS 701.An -nosplit 702The 703.Nm 704utility was written by 705.An Michael Smith Aq msmith@FreeBSD.org . 706This manual page was written by 707.An Mike Pritchard Aq mpp@FreeBSD.org . 708The command and manual page have since been updated by 709.An Kazutaka Yokota Aq yokota@FreeBSD.org . 710