2 .\" Mike Pritchard <mpp@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
38 .Nd pass mouse data to the console driver
44 .Op Fl r Ar resolution
46 .Op Fl V Op Fl U Ar distance
47 .Op Fl a Ar X Ns Op , Ns Ar Y
54 .Op Fl 3 Op Fl E Ar timeout
64 utility and the console driver work together to support
65 mouse operation in the text console and user programs.
66 They virtualize the mouse and provide user programs with mouse data
67 in the standard format
71 The mouse daemon listens to the specified port for mouse data,
72 interprets and then passes it via ioctls to the console driver.
74 reports translation movement, button press/release
75 events and movement of the roller or the wheel if available.
76 The roller/wheel movement is reported as
80 The console driver will display the mouse pointer on the screen
81 and provide cut and paste functions if the mouse pointer is enabled
82 in the virtual console via
86 is opened by the user program, the console driver also passes the mouse
87 data to the device so that the user program will see it.
89 If the mouse daemon receives the signal
91 it will reopen the mouse port and reinitialize itself.
93 the mouse is attached/detached while the system is suspended.
95 The following options are available:
96 .Bl -tag -width indent
98 Emulate the third (middle) button for 2-button mice.
100 by pressing the left and right physical buttons simultaneously.
101 .It Fl C Ar threshold
102 Set double click speed as the maximum interval in msec between button clicks.
103 Without this option, the default value of 500 msec will be assumed.
104 This option will have effect only on the cut and paste operations
105 in the text mode console.
106 The user program which is reading mouse data
109 will not be affected.
111 Lower DTR on the serial port.
112 This option is valid only if
114 is selected as the protocol type.
115 The DTR line may need to be dropped for a 3-button mouse
120 When the third button emulation is enabled
126 msec at most before deciding whether two buttons are being pressed
128 The default timeout is 100 msec.
130 Set the report rate (reports/sec) of the device if supported.
132 Write the process id of the
134 utility in the specified file.
135 Without this option, the process id will be stored in
136 .Pa /var/run/moused.pid .
138 Do not start the Plug and Play COM device enumeration procedure
139 when identifying the serial mouse.
140 If this option is given together with the
144 utility will not be able to print useful information for the serial mouse.
146 Lower RTS on the serial port.
147 This option is valid only if
149 is selected as the protocol type by the
152 It is often used with the
155 Both RTS and DTR lines may need to be dropped for
156 a 3-button mouse to operate in the
160 Select the baudrate for the serial port (1200 to 9600).
161 Not all serial mice support this option.
164 .Dq Virtual Scrolling .
165 With this option set, holding the middle mouse
166 button down will cause motion to be interpreted as scrolling.
169 option to set the distance the mouse must move before the scrolling mode is
173 .Dq Virtual Scrolling
176 option can be used to set the
178 (in pixels) that the mouse must move before the scrolling
183 .It Fl a Ar X Ns Op , Ns Ar Y
184 Accelerate or decelerate the mouse input.
185 This is a linear acceleration only.
186 Values less than 1.0 slow down movement, values greater than 1.0 speed it
188 Specifying only one value sets the acceleration for both axes.
190 Some mice report middle button down events
191 as if the left and right buttons are being pressed.
192 This option handles this.
194 Enable debugging messages.
196 Do not become a daemon and instead run as a foreground process.
197 Useful for testing and debugging.
199 Print specified information and quit.
203 .Bl -tag -compact -width modelxxx
205 Port (device file) name, i.e.\&
211 Interface type: serial, bus, inport or ps/2.
214 It is one of the types listed under the
218 if the driver supports the
220 data format standard.
225 utility may not always be able to identify the model.
227 All of the above items.
228 Print port, interface, type and model in this order
234 utility cannot determine the requested information, it prints
239 Specifies at which level
241 should operate the mouse driver.
246 for more information on this.
248 Assign the physical button
250 to the logical button
252 You may specify as many instances of this option as you like.
253 More than one physical button may be assigned to a logical button at the
255 In this case the logical button will be down,
256 if either of the assigned physical buttons is held down.
257 Do not put space around
262 to communicate with the mouse.
263 .It Fl r Ar resolution
264 Set the resolution of the device; in Dots Per Inch, or
270 This option may not be supported by all the device.
272 Select a baudrate of 9600 for the serial line.
273 Not all serial mice support this option.
275 Specify the protocol type of the mouse attached to the port.
276 You may explicitly specify a type listed below, or use
280 utility automatically select an appropriate protocol for the given
282 If you entirely omit this option in the command line,
285 Under normal circumstances,
286 you need to use this option only if the
288 utility is not able to detect the protocol automatically
290 .Sx "Configuring Mouse Daemon" ) .
292 Note that if a protocol type is specified with this option, the
294 option above is implied and Plug and Play COM device enumeration
295 procedure will be disabled.
297 Also note that if your mouse is attached to the PS/2 mouse port, you should
302 regardless of the brand and model of the mouse.
304 mouse is attached to the bus mouse port, choose
308 Serial mouse protocols will not work with these mice.
310 For the USB mouse, the protocol must be
312 No other protocol will work with the USB mouse.
314 Valid types for this option are
317 For the serial mouse:
318 .Bl -tag -compact -width mousesystemsxxx
320 Microsoft serial mouse protocol.
321 Most 2-button serial mice use this protocol.
323 Microsoft IntelliMouse protocol.
327 Logitech MouseMan+ and FirstMouse+ use this protocol too.
328 Other mice with a roller/wheel may be compatible with this protocol.
330 MouseSystems 5-byte protocol.
331 3-button mice may use this protocol.
333 MM Series mouse protocol.
335 Logitech mouse protocol.
336 Note that this is for old Logitech models.
340 should be specified for newer models.
342 Logitech MouseMan and TrackMan protocol.
343 Some 3-button mice may be compatible
345 Note that MouseMan+ and FirstMouse+ use
347 protocol rather than this one.
349 ALPS GlidePoint protocol.
351 Kensington ThinkingMouse protocol.
353 Hitachi tablet protocol.
354 .It Ar x10mouseremote
357 Genius Kidspad and Easypad protocol.
359 Interlink VersaPad protocol.
362 GTCO Digipad protocol.
364 For the bus and InPort mouse:
365 .Bl -tag -compact -width mousesystemsxxx
367 This is the only protocol type available for
368 the bus and InPort mouse and should be specified for any bus mice
369 and InPort mice, regardless of the brand.
373 .Bl -tag -compact -width mousesystemsxxx
375 This is the only protocol type available for the PS/2 mouse
376 and should be specified for any PS/2 mice, regardless of the brand.
381 is the only protocol type available for the USB mouse
382 and should be specified for any USB mice, regardless of the brand.
384 Make the physical button
386 act as the wheel mode button.
387 While this button is pressed, X and Y axis movement is reported to be zero
388 and the Y axis movement is mapped to Z axis.
389 You may further map the Z axis movement to virtual buttons by the
393 Map Z axis (roller/wheel) movement to another axis or to virtual buttons.
397 .Bl -tag -compact -width x__
400 X or Y axis movement will be reported when the Z axis movement is detected.
402 Report down events for the virtual buttons
406 respectively when negative and positive Z axis movement
408 There do not need to be physical buttons
412 Note that mapping to logical buttons is carried out after mapping
413 from the Z axis movement to the virtual buttons is done.
415 Report down events for the virtual buttons
419 respectively when negative and positive Z axis movement
422 This is useful for the mouse with two wheels of which
423 the second wheel is used to generate horizontal scroll action,
424 and for the mouse which has a knob or a stick which can detect
425 the horizontal force applied by the user.
427 The motion of the second wheel will be mapped to the buttons
429 for the negative direction, and
431 for the positive direction.
436 actually exist in this mouse, their actions will not be detected.
438 Note that horizontal movement or second roller/wheel movement may not
440 because there appears to be no accepted standard as to how it is encoded.
442 Note also that some mice think left is the negative horizontal direction;
443 others may think otherwise.
444 Moreover, there are some mice whose two wheels are both mounted vertically,
445 and the direction of the second vertical wheel does not match the
449 .Ss Configuring Mouse Daemon
450 The first thing you need to know is the interface type
451 of the mouse you are going to use.
452 It can be determined by looking at the connector of the mouse.
453 The serial mouse has a D-Sub female 9- or 25-pin connector.
454 The bus and InPort mice have either a D-Sub male 9-pin connector
455 or a round DIN 9-pin connector.
456 The PS/2 mouse is equipped with a small, round DIN 6-pin connector.
457 Some mice come with adapters with which the connector can
458 be converted to another.
459 If you are to use such an adapter,
460 remember the connector at the very end of the mouse/adapter pair is
462 The USB mouse has a flat rectangular connector.
464 The next thing to decide is a port to use for the given interface.
465 For the bus, InPort and PS/2 mice, there is little choice:
466 the bus and InPort mice always use
468 and the PS/2 mouse is always at
470 There may be more than one serial port to which the serial
471 mouse can be attached.
472 Many people often assign the first, built-in
476 You can attach multiple USB mice to your system or to your USB hub.
477 They are accessible as
478 .Pa /dev/ums0 , /dev/ums1 ,
481 You may want to create a symbolic link
483 pointing to the real port to which the mouse is connected, so that you
484 can easily distinguish which is your
488 The next step is to guess the appropriate protocol type for the mouse.
491 utility may be able to automatically determine the protocol type.
496 option and see what it says.
497 If the command can identify
498 the protocol type, no further investigation is necessary on your part.
499 You may start the daemon without explicitly specifying a protocol type
503 The command may print
505 if the mouse driver supports this protocol type.
513 option do not necessarily match the product name of the pointing device
514 in question, but they may give the name of the device with which it is
519 option yields nothing, you need to specify a protocol type to the
524 You have to make a guess and try.
525 There is rule of thumb:
527 .Bl -enum -compact -width 1.X
529 The bus and InPort mice always use
531 protocol regardless of the brand of the mouse.
535 protocol should always be specified for the PS/2 mouse
536 regardless of the brand of the mouse.
540 protocol for the USB mouse.
542 Most 2-button serial mice support the
546 3-button serial mice may work with the
549 If it does not, it may work with the
552 the third (middle) button will not function.
553 3-button serial mice may also work with the
555 protocol under which the third button may function as expected.
557 3-button serial mice may have a small switch to choose between
578 If the mouse has a roller or a wheel, it may be compatible with the
583 To test if the selected protocol type is correct for the given mouse,
584 enable the mouse pointer in the current virtual console,
588 start the mouse daemon in the foreground mode,
590 .Dl moused -f -p Ar _selected_port_ -t Ar _selected_protocol_
592 and see if the mouse pointer travels correctly
593 according to the mouse movement.
594 Then try cut & paste features by
595 clicking the left, right and middle buttons.
599 As many instances of the mouse daemon as the number of mice attached to
600 the system may be run simultaneously; one
601 instance for each mouse.
602 This is useful if the user wants to use the built-in PS/2 pointing device
603 of a laptop computer while on the road, but wants to use a serial
604 mouse when s/he attaches the system to the docking station in the office.
605 Run two mouse daemons and tell the application program
607 .Tn "X\ Window System" )
610 then the application program will always see mouse data from either mouse.
611 When the serial mouse is not attached, the corresponding mouse daemon
612 will not detect any movement or button state change and the application
613 program will only see mouse data coming from the daemon for the
615 In contrast when both mice are attached and both of them
616 are moved at the same time in this configuration,
617 the mouse pointer will travel across the screen just as if movement of
618 the mice is combined all together.
620 .Bl -tag -width /dev/consolectl -compact
621 .It Pa /dev/consolectl
622 device to control the console
624 bus and InPort mouse driver
628 virtualized mouse driver
633 .It Pa /var/run/moused.pid
634 process id of the currently running
637 .It Pa /var/run/MouseRemote
638 UNIX-domain stream socket for X10 MouseRemote events
641 .Dl moused -p /dev/cuad0 -i type
645 utility determine the protocol type of the mouse at the serial port
647 If successful, the command will print the type, otherwise it will say
650 .Dl moused -p /dev/cuad0
655 utility is able to identify the protocol type of the mouse at the specified
656 port automatically, you can start the daemon without the
658 option and enable the mouse pointer in the text console as above.
660 .Dl moused -p /dev/mouse -t microsoft
663 Start the mouse daemon on the serial port
667 is explicitly specified by the
671 .Dl moused -p /dev/mouse -m 1=3 -m 3=1
673 Assign the physical button 3 (right button) to the logical button 1
674 (logical left) and the physical button 1 (left) to the logical
675 button 3 (logical right).
676 This will effectively swap the left and right buttons.
678 .Dl moused -p /dev/mouse -t intellimouse -z 4
680 Report negative Z axis movement (i.e., mouse wheel) as the button 4 pressed
681 and positive Z axis movement (i.e., mouse wheel) as the button 5 pressed.
685 utility does not currently work with the alternative console driver
688 Many pad devices behave as if the first (left) button were pressed if
691 the surface of the pad.
692 In contrast, some ALPS GlidePoint and Interlink VersaPad models
693 treat the tapping action
694 as fourth button events.
698 to obtain the same effect as the other pad devices.
700 Cut and paste functions in the virtual console assume that there
701 are three buttons on the mouse.
702 The logical button 1 (logical left) selects a region of text in the
703 console and copies it to the cut buffer.
704 The logical button 3 (logical right) extends the selected region.
705 The logical button 2 (logical middle) pastes the selected text
706 at the text cursor position.
707 If the mouse has only two buttons, the middle, `paste' button
709 To obtain the paste function, use the
711 option to emulate the middle button, or use the
713 option to assign the physical right button to the logical middle button:
728 utility partially supports
729 .Dq Plug and Play External COM Device Specification
730 in order to support PnP serial mice.
731 However, due to various degrees of conformance to the specification by
732 existing serial mice, it does not strictly follow the version 1.0 of the
734 Even with this less strict approach,
735 it may not always determine an appropriate protocol type
736 for the given serial mouse.
740 utility first appeared in
746 utility was written by
747 .An Michael Smith Aq msmith@FreeBSD.org .
748 This manual page was written by
749 .An Mike Pritchard Aq mpp@FreeBSD.org .
750 The command and manual page have since been updated by
751 .An Kazutaka Yokota Aq yokota@FreeBSD.org .