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