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