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 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 l Ar level 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. 176Available pieces of 177information are: 178.Pp 179.Bl -tag -compact -width modelxxx 180.It Ar port 181Port (device file) name, i.e.\& 182.Pa /dev/cuaa0 , 183.Pa /dev/mse0 184and 185.Pa /dev/psm0 . 186.It Ar if 187Interface type: serial, bus, inport or ps/2. 188.It Ar type 189Protocol type. 190It is one of the types listed under the 191.Fl t 192option below or 193.Ar sysmouse 194if the driver supports the 195.Ar sysmouse 196data format standard. 197.It Ar model 198Mouse model. 199The 200.Nm 201utility may not always be able to identify the model. 202.It Ar all 203All of the above items. 204Print port, interface, type and model in this order 205in one line. 206.El 207.Pp 208If the 209.Nm 210utility cannot determine the requested information, it prints ``unknown'' 211or ``generic''. 212.It Fl l Ar level 213Specifies at which level 214.Nm 215should operate the mouse driver. 216Refer to 217.Em Operation Levels 218in 219.Xr psm 4 220for more information on this. 221.It Fl m Ar N=M 222Assign the physical button 223.Ar M 224to the logical button 225.Ar N . 226You may specify as many instances of this option as you like. 227More than one physical button may be assigned to a logical button at the 228same time. 229In this case the logical button will be down, 230if either of the assigned physical buttons is held down. 231Do not put space around `='. 232.It Fl p Ar port 233Use 234.Ar port 235to communicate with the mouse. 236.It Fl r Ar resolution 237Set the resolution of the device; in Dots Per Inch, or 238.Ar low , 239.Ar medium-low , 240.Ar medium-high 241or 242.Ar high . 243This option may not be supported by all the device. 244.It Fl s 245Select a baudrate of 9600 for the serial line. 246Not all serial mice support this option. 247.It Fl t Ar type 248Specify the protocol type of the mouse attached to the port. 249You may explicitly specify a type listed below, or use 250.Ar auto 251to let the 252.Nm 253utility automatically select an appropriate protocol for the given 254mouse. 255If you entirely omit this option in the command line, 256.Fl t Ar auto 257is assumed. 258Under normal circumstances, 259you need to use this option only if the 260.Nm 261utility is not able to detect the protocol automatically 262(see 263.Sx "Configuring Mouse Daemon" ) . 264.Pp 265Note that if a protocol type is specified with this option, the 266.Fl P 267option above is implied and Plug and Play COM device enumeration 268procedure will be disabled. 269.Pp 270Also note that if your mouse is attached to the PS/2 mouse port, you should 271always choose 272.Ar auto 273or 274.Ar ps/2 , 275regardless of the brand and model of the mouse. 276Likewise, if your 277mouse is attached to the bus mouse port, choose 278.Ar auto 279or 280.Ar busmouse . 281Serial mouse protocols will not work with these mice. 282.Pp 283For the USB mouse, the protocol must be 284.Ar auto . 285No other protocol will work with the USB mouse. 286.Pp 287Valid types for this option are 288listed below. 289.Pp 290For the serial mouse: 291.Bl -tag -compact -width mousesystemsxxx 292.It Ar microsoft 293Microsoft serial mouse protocol. 294Most 2-button serial mice use this protocol. 295.It Ar intellimouse 296Microsoft IntelliMouse protocol. 297Genius NetMouse, 298.Tn ASCII 299Mie Mouse, 300Logitech MouseMan+ and FirstMouse+ use this protocol too. 301Other mice with a roller/wheel may be compatible with this protocol. 302.It Ar mousesystems 303MouseSystems 5-byte protocol. 3043-button mice may use this protocol. 305.It Ar mmseries 306MM Series mouse protocol. 307.It Ar logitech 308Logitech mouse protocol. 309Note that this is for old Logitech models. 310.Ar mouseman 311or 312.Ar intellimouse 313should be specified for newer models. 314.It Ar mouseman 315Logitech MouseMan and TrackMan protocol. 316Some 3-button mice may be compatible 317with this protocol. 318Note that MouseMan+ and FirstMouse+ use 319.Ar intellimouse 320protocol rather than this one. 321.It Ar glidepoint 322ALPS GlidePoint protocol. 323.It Ar thinkingmouse 324Kensington ThinkingMouse protocol. 325.It Ar mmhitab 326Hitachi tablet protocol. 327.It Ar x10mouseremote 328X10 MouseRemote. 329.It Ar kidspad 330Genius Kidspad and Easypad protocol. 331.It Ar versapad 332Interlink VersaPad protocol. 333.El 334.Pp 335For the bus and InPort mouse: 336.Bl -tag -compact -width mousesystemsxxx 337.It Ar busmouse 338This is the only protocol type available for 339the bus and InPort mouse and should be specified for any bus mice 340and InPort mice, regardless of the brand. 341.El 342.Pp 343For the PS/2 mouse: 344.Bl -tag -compact -width mousesystemsxxx 345.It Ar ps/2 346This is the only protocol type available for the PS/2 mouse 347and should be specified for any PS/2 mice, regardless of the brand. 348.El 349.Pp 350For the USB mouse, 351.Ar auto 352is the only protocol type available for the USB mouse 353and should be specified for any USB mice, regardless of the brand. 354.It Fl w Ar N 355Make the physical button 356.Ar N 357act as the wheel mode button. 358While this button is pressed, X and Y axis movement is reported to be zero 359and the Y axis movement is mapped to Z axis. 360You may further map the Z axis movement to virtual buttons by the 361.Fl z 362option below. 363.It Fl z Ar target 364Map Z axis (roller/wheel) movement to another axis or to virtual buttons. 365Valid 366.Ar target 367maybe: 368.Bl -tag -compact -width x__ 369.It Ar x 370.It Ar y 371X or Y axis movement will be reported when the Z axis movement is detected. 372.It Ar N 373Report down events for the virtual buttons 374.Ar N 375and 376.Ar N+1 377respectively when negative and positive Z axis movement 378is detected. 379There do not need to be physical buttons 380.Ar N 381and 382.Ar N+1 . 383Note that mapping to logical buttons is carried out after mapping 384from the Z axis movement to the virtual buttons is done. 385.It Ar N1 N2 386Report down events for the virtual buttons 387.Ar N1 388and 389.Ar N2 390respectively when negative and positive Z axis movement 391is detected. 392.It Ar N1 N2 N3 N4 393This is useful for the mouse with two wheels of which 394the second wheel is used to generate horizontal scroll action, 395and for the mouse which has a knob or a stick which can detect 396the horizontal force applied by the user. 397.Pp 398The motion of the second wheel will be mapped to the buttons 399.Ar N3 , 400for the negative direction, and 401.Ar N4 , 402for the positive direction. 403If the buttons 404.Ar N3 405and 406.Ar N4 407actually exist in this mouse, their actions will not be detected. 408.Pp 409Note that horizontal movement or second roller/wheel movement may not 410always be detected, 411because there appears to be no accepted standard as to how it is encoded. 412.Pp 413Note also that some mice think left is the negative horizontal direction; 414others may think otherwise. 415Moreover, there are some mice whose two wheels are both mounted vertically, 416and the direction of the second vertical wheel does not match the 417first one. 418.El 419.El 420.Ss Configuring Mouse Daemon 421The first thing you need to know is the interface type 422of the mouse you are going to use. 423It can be determined by looking at the connector of the mouse. 424The serial mouse has a D-Sub female 9- or 25-pin connector. 425The bus and InPort mice have either a D-Sub male 9-pin connector 426or a round DIN 9-pin connector. 427The PS/2 mouse is equipped with a small, round DIN 6-pin connector. 428Some mice come with adapters with which the connector can 429be converted to another. 430If you are to use such an adapter, 431remember the connector at the very end of the mouse/adapter pair is 432what matters. 433The USB mouse has a flat rectangular connector. 434.Pp 435The next thing to decide is a port to use for the given interface. 436For the bus, InPort and PS/2 mice, there is little choice: 437the bus and InPort mice always use 438.Pa /dev/mse0 , 439and the PS/2 mouse is always at 440.Pa /dev/psm0 . 441There may be more than one serial port to which the serial 442mouse can be attached. 443Many people often assign the first, built-in 444serial port 445.Pa /dev/cuaa0 446to the mouse. 447You can attach multiple USB mice to your system or to your USB hub. 448They are accessible as 449.Pa /dev/ums0 , /dev/ums1 , 450and so on. 451.Pa 452You may want to create a symbolic link 453.Pa /dev/mouse 454pointing to the real port to which the mouse is connected, so that you 455can easily distinguish which is your ``mouse'' port later. 456.Pp 457The next step is to guess the appropriate protocol type for the mouse. 458The 459.Nm 460utility may be able to automatically determine the protocol type. 461Run the 462.Nm 463utility with the 464.Fl i 465option and see what it says. 466If the command can identify 467the protocol type, no further investigation is necessary on your part. 468You may start the daemon without explicitly specifying a protocol type 469(see 470.Sx EXAMPLES ) . 471.Pp 472The command may print 473.Ar sysmouse 474if the mouse driver supports this protocol type. 475.Pp 476Note that the 477.Dv type 478and 479.Dv model 480printed by the 481.Fl i 482option do not necessarily match the product name of the pointing device 483in question, but they may give the name of the device with which it is 484compatible. 485.Pp 486If the 487.Fl i 488option yields nothing, you need to specify a protocol type to the 489.Nm 490utility by the 491.Fl t 492option. 493You have to make a guess and try. 494There is rule of thumb: 495.Pp 496.Bl -enum -compact -width 1.X 497.It 498The bus and InPort mice always use 499.Ar busmouse 500protocol regardless of the brand of the mouse. 501.It 502The 503.Ar ps/2 504protocol should always be specified for the PS/2 mouse 505regardless of the brand of the mouse. 506.It 507You must specify the 508.Ar auto 509protocol for the USB mouse. 510.It 511Most 2-button serial mice support the 512.Ar microsoft 513protocol. 514.It 5153-button serial mice may work with the 516.Ar mousesystems 517protocol. 518If it does not, it may work with the 519.Ar microsoft 520protocol although 521the third (middle) button will not function. 5223-button serial mice may also work with the 523.Ar mouseman 524protocol under which the third button may function as expected. 525.It 5263-button serial mice may have a small switch to choose between ``MS'' 527and ``PC'', or ``2'' and ``3''. 528``MS'' or ``2'' usually mean the 529.Ar microsoft 530protocol. 531``PC'' or ``3'' will choose the 532.Ar mousesystems 533protocol. 534.It 535If the mouse has a roller or a wheel, it may be compatible with the 536.Ar intellimouse 537protocol. 538.El 539.Pp 540To test if the selected protocol type is correct for the given mouse, 541enable the mouse pointer in the current virtual console, 542.Pp 543.Dl vidcontrol -m on 544.Pp 545start the mouse daemon in the foreground mode, 546.Pp 547.Dl moused -f -p Ar _selected_port_ -t Ar _selected_protocol_ 548.Pp 549and see if the mouse pointer travels correctly 550according to the mouse movement. 551Then try cut & paste features by 552clicking the left, right and middle buttons. 553Type ^C to stop 554the command. 555.Ss Multiple Mice 556As many instances of the mouse daemon as the number of mice attached to 557the system may be run simultaneously; one 558instance for each mouse. 559This is useful if the user wants to use the built-in PS/2 pointing device 560of a laptop computer while on the road, but wants to use a serial 561mouse when s/he attaches the system to the docking station in the office. 562Run two mouse daemons and tell the application program 563(such as the 564.Tn "X\ Window System" ) 565to use 566.Xr sysmouse 4 , 567then the application program will always see mouse data from either mouse. 568When the serial mouse is not attached, the corresponding mouse daemon 569will not detect any movement or button state change and the application 570program will only see mouse data coming from the daemon for the 571PS/2 mouse. 572In contrast when both mice are attached and both of them 573are moved at the same time in this configuration, 574the mouse pointer will travel across the screen just as if movement of 575the mice is combined all together. 576.Sh FILES 577.Bl -tag -width /dev/consolectl -compact 578.It Pa /dev/consolectl 579device to control the console 580.It Pa /dev/mse%d 581bus and InPort mouse driver 582.It Pa /dev/psm%d 583PS/2 mouse driver 584.It Pa /dev/sysmouse 585virtualized mouse driver 586.It Pa /dev/ttyv%d 587virtual consoles 588.It Pa /dev/ums%d 589USB mouse driver 590.It Pa /var/run/moused.pid 591process id of the currently running 592.Nm 593utility 594.It Pa /var/run/MouseRemote 595UNIX-domain stream socket for X10 MouseRemote events 596.El 597.Sh EXAMPLES 598.Dl moused -p /dev/cuaa0 -i type 599.Pp 600Let the 601.Nm 602utility determine the protocol type of the mouse at the serial port 603.Pa /dev/cuaa0 . 604If successful, the command will print the type, otherwise it will say 605``unknown''. 606.Pp 607.Dl moused -p /dev/cuaa0 608.Dl vidcontrol -m on 609.Pp 610If the 611.Nm 612utility is able to identify the protocol type of the mouse at the specified 613port automatically, you can start the daemon without the 614.Fl t 615option and enable the mouse pointer in the text console as above. 616.Pp 617.Dl moused -p /dev/mouse -t microsoft 618.Dl vidcontrol -m on 619.Pp 620Start the mouse daemon on the serial port 621.Pa /dev/mouse . 622The protocol type 623.Ar microsoft 624is explicitly specified by the 625.Fl t 626option. 627.Pp 628.Dl moused -p /dev/mouse -m 1=3 -m 3=1 629.Pp 630Assign the physical button 3 (right button) to the logical button 1 631(logical left) and the physical button 1 (left) to the logical 632button 3 (logical right). 633This will effectively swap the left and right buttons. 634.Pp 635.Dl moused -p /dev/mouse -t intellimouse -z 4 636.Pp 637Report negative Z axis movement (i.e., mouse wheel) as the button 4 pressed 638and positive Z axis movement (i.e., mouse wheel) as the button 5 pressed. 639.Sh CAVEATS 640The 641.Nm 642utility does not currently work with the alternative console driver 643.Xr pcvt 4 . 644.Pp 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 mse 4 , 673.Xr pcvt 4 , 674.Xr psm 4 , 675.Xr screen 4 , 676.Xr sysmouse 4 , 677.Xr ums 4 678.Sh STANDARDS 679The 680.Nm 681utility partially supports 682.Dq Plug and Play External COM Device Specification 683in order to support PnP serial mice. 684However, due to various degrees of conformance to the specification by 685existing serial mice, it does not strictly follow the version 1.0 of the 686standard. 687Even with this less strict approach, 688it may not always determine an appropriate protocol type 689for the given serial mouse. 690.Sh AUTHORS 691.An -nosplit 692The 693.Nm 694utility was written by 695.An Michael Smith Aq msmith@FreeBSD.org . 696This manual page was written by 697.An Mike Pritchard Aq mpp@FreeBSD.org . 698The command and manual page have since been updated by 699.An Kazutaka Yokota Aq yokota@FreeBSD.org . 700.Sh HISTORY 701The 702.Nm 703utility first appeared in 704.Fx 2.2 . 705