source: general/sysutils/usbutils.xml@ 3cf0475

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY usbutils-download-http "https://github.com/gregkh/usbutils/archive/v&usbutils-version;/usbutils-&usbutils-version;.tar.gz">
  <!ENTITY usbutils-download-ftp  " ">
  <!ENTITY usbutils-md5sum        "112eafa991e55229b9f48b90c290a0e2">
  <!ENTITY usbutils-size          "120 KB">
  <!ENTITY usbutils-buildsize     "4.3 MB">
  <!ENTITY usbutils-time          "0.1 SBU">
]>

<sect1 id="usbutils" xreflabel="usbutils-&usbutils-version;">
  <?dbhtml filename="usbutils.html"?>


  <title>usbutils-&usbutils-version;</title>

  <indexterm zone="usbutils">
    <primary sortas="a-usbutils">usbutils</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to USB Utils</title>

    <para>
      The <application>USB Utils</application> package contains utilities
      used to display information about USB buses in the system and the
      devices connected to them.
    </para>

    &lfs113_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&usbutils-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&usbutils-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &usbutils-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &usbutils-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &usbutils-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &usbutils-time;
        </para>
      </listitem>
    </itemizedlist>
<!--
    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/usbutils-&usbutils-version;-lsusb_bugfixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>
-->
    <bridgehead renderas="sect3">USB Utils Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="libusb"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
<!-- git is required by autogen.sh. If using the tarball on kernel.org,
     autogen.sh does not need to be run. If using the github source,
     autogen.sh needs to be run, and git is used to pull the usbhid-dump
     submodule. -->
      <xref linkend="git"/> and
      <xref linkend="wget"/>
<!-- In the systemd book, a unit/timer is installed to update the
     usb.ids file automatically. wget is used in the instructions below. -->
    </para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of USB Utils</title>

    <para>
      Install <application>USB Utils</application> by
      running the following commands:
    </para>

<screen><userinput>autoreconf -fiv &amp;&amp;

./configure --prefix=/usr --datadir=/usr/share/hwdata &amp;&amp;
make</userinput></screen>

    <para>
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install</userinput></screen>

    <para>
      To install the <filename>usb.ids</filename> data file, using
      <xref linkend="wget"/>, run, as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>install -dm755 /usr/share/hwdata/ &amp;&amp;
wget http://www.linux-usb.org/usb.ids -O /usr/share/hwdata/usb.ids</userinput></screen>

    <para>
      The script <command>lsusb.py</command> displays information in a more
      easily readable form than <command>lsusb</command>. To find the options,
      use <command>lsusb.py -h</command>. One form of use recommended by the
      developer is <command>lsusb.py -ciu</command>.
    </para>

  </sect2>
<!-- No longer needed
  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed ... lsusb.py</command>: Instructs lsusb.py where to search
      <filename>usb.ids</filename>.
    </para>

  </sect2>
-->
  <sect2 role="configuration">
    <title>Configuring USB Utils</title>

    <para revision="sysv">
      The <filename>usb.ids</filename> data file is constantly being updated.
      To get a current version of this file, using <xref linkend="wget"/>,
      periodically run again, as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root" revision="sysv"><userinput>wget http://www.linux-usb.org/usb.ids -O /usr/share/hwdata/usb.ids</userinput></screen>

    <para>
      You should update the <filename>/usr/share/hwdata/usb.ids</filename> file
      periodically. <phrase revision="sysv">If you've installed
      <xref linkend="fcron"/> and completed the section on periodic jobs,
      execute</phrase><phrase revision="systemd">Execute</phrase> the following       commands, as the  <systemitem class="username">root</systemitem> user,
      to create a <phrase revision="sysv">weekly cron job:</phrase>
      <phrase revision="systemd">systemd timer to update it weekly on Sundays
      at 2:30 A.M. (local time):</phrase>
    </para>

<screen role="nodump" revision="sysv"><userinput>cat &gt; /etc/cron.weekly/update-usbids.sh &lt;&lt; "EOF" &amp;&amp;
<literal>#!/bin/bash
/usr/bin/wget http://www.linux-usb.org/usb.ids -O /usr/share/hwdata/usb.ids</literal>
EOF
chmod 754 /etc/cron.weekly/update-usbids.sh</userinput></screen>

<screen role="root" revision="systemd"><userinput>cat &gt; /usr/lib/systemd/system/update-usbids.service &lt;&lt; "EOF" &amp;&amp;
<literal>[Unit]
Description=Update usb.ids file
Documentation=man:lsusb(8)
DefaultDependencies=no
After=local-fs.target network-online.target
Before=shutdown.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/bin/wget http://www.linux-usb.org/usb.ids -O /usr/share/hwdata/usb.ids</literal>
EOF
cat &gt; /usr/lib/systemd/system/update-usbids.timer &lt;&lt; "EOF" &amp;&amp;
<literal>[Unit]
Description=Update usb.ids file weekly

[Timer]
OnCalendar=Sun 03:00:00
Persistent=true

[Install]
WantedBy=timers.target</literal>
EOF
systemctl enable update-usbids.timer</userinput></screen>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          lsusb, lsusb.py, usb-devices, and usbhid-dump
        </seg>
        <seg>
          None
        </seg>
        <seg>
          None
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="lsusb">
        <term><command>lsusb</command></term>
        <listitem>
          <para>
            is a utility for displaying information about all USB buses
            in the system and all devices connected to them, but not in human
            friendly form
          </para>
          <indexterm zone="usbutils lsusb">
            <primary sortas="b-lsusb">lsusb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lsusb.py">
        <term><command>lsusb.py</command></term>
        <listitem>
          <para>
            displays information about all USB buses in the system and all
            devices connected to them in reasonable human friendly form
          </para>
          <indexterm zone="usbutils lsusb.py">
            <primary sortas="b-lsusb.py">lsusb.py</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="usb-devices">
        <term><command>usb-devices</command></term>
        <listitem>
          <para>
            is a shell script that displays details of USB buses and devices
            connected to them. It is designed to be used if /proc/bus/usb/devices
            is not available on your system
          </para>
          <indexterm zone="usbutils usb-devices">
            <primary sortas="b-usb-devices">usb-devices</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="usbhid-dump">
        <term><command>usbhid-dump</command></term>
        <listitem>
          <para>
            is used to dump report descriptors and streams from HID
            (human interface device) interfaces of USB devices
          </para>
          <indexterm zone="usbutils usbhid-dump">
            <primary sortas="b-usbhid-dump">usbhid-dump</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>