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