.\" %FreeBSD: src/usr.bin/usbhidaction/usbhidaction.1,v 1.3 2003/05/30 21:27:29 ru Exp %
.\" $FreeBSD$
.\" $NetBSD: usbhidaction.1,v 1.8 2003/02/25 10:35:59 wiz Exp $
.\"
.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Lennart Augustsson (lennart@augustsson.net).
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd April 9, 2003
.Dt USBHIDACTION 1
.Os
.Sh 名称
.Nm usbhidaction
.Nd USB の HID コントロールにしたがってアクションを実行する
.Sh 書式
.Nm
.Op Fl diev
.Fl c Ar config-file
.Fl f Ar device
.Op Fl p Ar pidfile
.Ar arg ...
.Sh 解説
.Nm
ユーティリティは、特定の値が HID コントロールに現れた時に
コマンドを実行するのに使用されます。
このプログラムの通常の動作は、設定ファイルの読み込み後にデーモンとなり、
HID の項目に指定された通りにコマンドを実行します。
HID デバイスからの読み込みが失敗した場合、プログラムは終了します。
つまり USB デバイスが抜かれた場合にも、プログラムは終了するということです。
.Pp
オプションは以下の通りです:
.Bl -tag -width indent
.It Fl d
デーモンになるかどうかのフラグをトグルさせます。
.It Fl e
.Nm
がすぐ終了するように指示します。
これは、複数の冗長オプションをつけた時に、
どのようにファイルが解釈されるかを確認するのに便利です。
.It Fl i
設定ファイルに記述されているが、デバイスに存在しない HID 項目を無視します。
.It Fl v
出力を冗長にします。
デーモンにはなりません。
.It Fl c Ar config-file
設定ファイルのパス名を指定します。
.It Fl f Ar device
作動対象のデバイスのパス名を指定します。
.Ar device
が数字の場合は、USB HID デバイス番号とみなします。
相対パスの場合は、
.Pa /dev
以下のデバイスの名前とみなします。
絶対パスの場合は、そのままデバイスのパス名とみなします。
.It Fl p Ar pidfile
プロセス ID を格納する別のファイル名を指定します。
.El
.Pp
プロセスが
.Dv SIGHUP
シグナルを受け取とると、設定ファイルが再び読み込まれます。
.Sh 設定
設定ファイルは、非常に単純な形式をしています。
各行はアクションを記述しています。
空白で始まる行は、前の行からの継続とみなされます。
.Ql #
で始まる行は、コメントとみなされます。
.Pp
各行は 4 つの部分で構成されます。
それは USB HID の項目名、その項目の値、デバウンス値、アクションです。
それぞれの部分は、空白で区切られます。
.Pp
項目名は
.Xr usbhidctl 1
で用いられるものと同様のものですが、
それぞれの部分にはそのページ名が前につけられます。
.Pp
項目の値は、単なる数値です。
その項目がこの値を示した時に、アクションが実行されます。
この値が
.Ql *
の場合は、すべての値にマッチします。
.Pp
デバウンス値は、非負の整数です。
値 0 は、デバウンスしないことを示します。
値 1 は、状態が変化した時のみアクションを実行します。
値が 2 以上の場合は、項目の値がこの量だけ変化した時にのみ実行されます。
.Pp
アクションは、
.Xr system 3
で実行される通常のコマンドです。
コマンドが実行される前に、いくつかの置換が行われます。
.Ql $n
は、コマンドライン上の
.Ar n
番目の引数に置き換えられます。
.Ql $V
は、HID 項目の数値に置き換えられます。
.Ql $N
はコントロール名に置き換えられ、
.Ql $H
は HID デバイス名に置き換えられます。
.Sh 関連ファイル
.Bl -tag -width ".Pa /usr/share/misc/usb_hid_usages"
.It Pa /usr/share/misc/usb_hid_usages
HID の使用法テーブル
.It Pa /var/run/usbaction.pid
デフォルトの PID ファイルの場所
.El
.Sh 使用例
以下の設定ファイルは、スピーカに HID コントロールを持つ
1 組の Philips USB スピーカを制御するのに使われます。
.Bd -literal -offset indent
# 様々な Philips USB スピーカ用の設定
Consumer:Volume_Up			 1 0 mixer -f $1 vol +1
Consumer:Volume_Down			 1 0 mixer -f $1 vol -1
# mute は未サポート
#Consumer:Mute				 1 0 mixer -f $1 mute
Consumer:Channel_Top.Microsoft:Base_Up	 1 0 mixer -f $1 bass +1
Consumer:Channel_Top.Microsoft:Base_Down 1 0 mixer -f $1 bass -1
.Ed
.Pp
この設定を使用した起動例は次のようになります。
.Pp
.Dl "usbhidaction -f /dev/uhid1 -c conf /dev/mixer1"
.Pp
以下は、Logitech Wingman でミキサボリュームを制御する例です。
ボタンに対するデバウンス値は 1 で、スライダに対する値は 5 であることに
注意してください。
.Bd -literal -offset indent
Button:Button_1	  1 1	mixer vol +10
Button:Button_2	  1 1	mixer vol -10
Generic_Desktop:Z * 5	mixer vol `echo $V | awk '{print int($$1/255*100)}'`
.Ed
.Sh 関連項目
.Xr usbhidctl 1 ,
.Xr usbhid 3 ,
.Xr uhid 4 ,
.Xr usb 4
.Sh 歴史
.Nm
コマンドは
.Nx 1.6
ではじめて登場しました。
.Nm
コマンドは
.Fx 5.1
で登場しました。