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