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