blog/data/2015-12-20-isenkram.txt

   1 Title: Using appstream with isenkram to install hardware related packages in Debian
   2 Tags: english, debian, isenkram
   3 Date: 2015-12-20 12:20
   4
   5 <p>Around three years ago, I created
   6 <a href="http://packages.qa.debian.org/isenkram">the isenkram
   7 system</a> to get a more practical solution in Debian for handing
   8 hardware related packages.  A GUI system in the isenkram package will
   9 present a pop-up dialog when some hardware dongle supported by
  10 relevant packages in Debian is inserted into the machine.  The same
  11 lookup mechanism to detect packages is available as command line
  12 tools in the isenkram-cli package.  In addition to mapping hardware,
  13 it will also map kernel firmware files to packages and make it easy to
  14 install needed firmware packages automatically.  The key for this
  15 system to work is a good way to map hardware to packages, in other
  16 words, allow packages to announce what hardware they will work
  17 with.</p>
  18
  19 <p>I started by providing data files in the isenkram source, and
  20 adding code to download the latest version of these data files at run
  21 time, to ensure every user had the most up to date mapping available.
  22 I also added support for storing the mapping in the Packages file in
  23 the apt repositories, but did not push this approach because while I
  24 was trying to figure out how to best store hardware/package mappings,
  25 <a href="http://www.freedesktop.org/software/appstream/docs/">the
  26 appstream system</a> was announced.  I got in touch and suggested to
  27 add the hardware mapping into that data set to be able to use
  28 appstream as a data source, and this was accepted at least for the
  29 Debian version of appstream.</p>
  30
  31 <p>A few days ago using appstream in Debian for this became possible,
  32 and today I uploaded a new version 0.20 of isenkram adding support for
  33 appstream as a data source for mapping hardware to packages.  The only
  34 package so far using appstream to announce its hardware support is my
  35 pymissile package.  I got help from Matthias Klumpp with figuring out
  36 how do add the required
  37 <a href="https://appstream.debian.org/html/sid/main/metainfo/pymissile.html">metadata
  38 in pymissile</a>.  I added a file debian/pymissile.metainfo.xml with
  39 this content:</p>
  40
  41 <blockquote><pre>
  42 &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  43 &lt;component&gt;
  44   &lt;id&gt;pymissile&lt;/id&gt;
  45   &lt;metadata_license&gt;MIT&lt;/metadata_license&gt;
  46   &lt;name&gt;pymissile&lt;/name&gt;
  47   &lt;summary&gt;Control original Striker USB Missile Launcher&lt;/summary&gt;
  48   &lt;description&gt;
  49     &lt;p&gt;
  50       Pymissile provides a curses interface to control an original
  51       Marks and Spencer / Striker USB Missile Launcher, as well as a
  52       motion control script to allow a webcamera to control the
  53       launcher.
  54     &lt;/p&gt;
  55   &lt;/description&gt;
  56   &lt;provides&gt;
  57     &lt;modalias&gt;usb:v1130p0202d*&lt;/modalias&gt;
  58   &lt;/provides&gt;
  59 &lt;/component&gt;
  60 </pre></blockquote>
  61
  62 <p>The key for isenkram is the component/provides/modalias value,
  63 which is a glob style match rule for hardware specific strings
  64 (modalias strings) provided by the Linux kernel.  In this case, it
  65 will map to all USB devices with vendor code 1130 and product code
  66 0202.</p>
  67
  68 <p>Note, it is important that the license of all the metadata files
  69 are compatible to have permissions to aggregate them into archive wide
  70 appstream files.  Matthias suggested to use MIT or BSD licenses for
  71 these files.  A challenge is figuring out a good id for the data, as
  72 it is supposed to be globally unique and shared across distributions
  73 (in other words, best to coordinate with upstream what to use).  But
  74 it can be changed later or, so we went with the package name as
  75 upstream for this project is dormant.</p>
  76
  77 <p>To get the metadata file installed in the correct location for the
  78 mirror update scripts to pick it up and include its content the
  79 appstream data source, the file must be installed in the binary
  80 package under /usr/share/appdata/.  I did this by adding the following
  81 line to debian/pymissile.install:</p>
  82
  83 <blockquote><pre>
  84 debian/pymissile.metainfo.xml usr/share/appdata
  85 </pre></blockquote>
  86
  87 <p>With that in place, the command line tool isenkram-lookup will list
  88 all packages useful on the current computer automatically, and the GUI
  89 pop-up handler will propose to install the package not already
  90 installed if a hardware dongle is inserted into the machine in
  91 question.</p>
  92
  93 <p>Details of the modalias field in appstream is available from the
  94 <a href="https://wiki.debian.org/DEP-11">DEP-11</a> proposal.</p>
  95
  96 <p>To locate the modalias values of all hardware present in a machine,
  97 try running this command on the command line:</p>
  98
  99 <blockquote><pre>
 100 cat $(find /sys/devices/|grep modalias)
 101 </pre></blockquote>
 102
 103 <p>To learn more about the isenkram system, please check out
 104 <a href="http://www.hungry.com/~pere/blog/tags/isenkram/">my
 105 blog posts tagged isenkram</a>.</p>