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