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