# Firmware

## Introduction

Device firmware can be accompanied by AppStream upstream metadata, to be incorporated by a distribution. Tools like fwupd make use of this metadata to automatically update firmware of devices found in the machine.

Firmware can ship one or more files in `/usr/share/appdata/%{id}.metainfo.xml`.

## Example file

A firmware meta-info file should look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <!-- Copyright 2015 Richard Hughes <richard@hughsie.com> -->
    <component type="firmware">
      <id>84f40464-9272-4ef7-9399-cd95f12da696</id>
      <name>ColorHugALS Firmware</name>
      <summary>Firmware for the ColorHugALS Ambient Light Sensor</summary>
      <description>
        <p>
          Updating the firmware on your ColorHugALS device improves performance and
          adds new features.
        </p>
      </description>
      <url type="homepage">http://www.hughski.com/</url>
      <metadata_license>CC0-1.0</metadata_license>
      <project_license>GPL-2.0+</project_license>
      <developer_name>Hughski Limited</developer_name>
      <releases>
        <release version="3.0.2" timestamp="1424116753">
          <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
          <description>
            <p>This stable release fixes the following bugs:</p>
            <ul>
              <li>Fix the return code from GetHardwareVersion</li>
              <li>Scale the output of TakeReadingRaw by the datasheet values</li>
            </ul>
          </description>
        </release>
      </releases>
    </component>

You can find additional information on how to create a complete firmware package upstream in the README document of fwupd.

## File specification

Note that the XML root must have the `type` property set to `firmware`. This clearly identified this metainfo document as describing firmware.

<id/>

  For firmware, the value of the `<id/>` tag must be the GUID of the device the firmware is written for.

<releases/>

  This tag is almost identical to the generic tag. Additional to the generic tag, for each `<release/>` child a `<location/>` tag is allowed.

  The `<location/>` tag specifies a remote location where the firmware `.cab` can be downloaded from. The download location needs to be accessibly via `HTTP`, `HTTPS` or `FTP`.

  Example:

      <releases>
        <release version="3.0.2" timestamp="1424116753">
          <location>http://www.hughski.com/downloads/colorhug-als/firmware/colorhug-als-3.0.2.cab</location>
          <description>
            <p>This stable release fixes bugs.</p>
          </description>
        </release>
      </releases>

  The `<location/>` tag is currently only allowed to be specified once.

For a component of type `firmware`, the following tags are required and must be present for a valid document: , , , .