{% import ‘fuchsia-src/_common/_doc_widgets.md’ as widgets %}
This guide shows you ways to test the hardware subsystems of a physical Fuchsia device.
Experimental: All of the tools and workflows mentioned in this guide are experimental and can change at anytime.
This guide assumes that you're familiar with hardware and low-level software development.
All of the Fuchsia hardware testing workflows in this guide assume that your Fuchsia device is connected to a test host. The test host is a laptop or desktop running Linux or Windows. To test a hardware subsystem of your Fuchsia device you run a command like adb shell gpioutil list on the test host. The first part of the command, adb shell, is the transport system that handles communication between your test host and Fuchsia device. The second part of the command, gpioutil list, is the testing tool that actually exercises or queries a hardware subsystem on your Fuchsia device.
The OS of your test host determines what transport systems you can use. For example, currently only adb is supported on Windows. The following table shows what combinations of test host OS and transport system are supported:
The transport system determines what kind of physical connection you can use between your test host and target device. For example, adb requires a USB connection between the test host and Fuchsia device. The hardware layout of your Fuchsia device also determines what transport system you can use. For example, if your Fuchsia device doesn‘t expose GND, TX, and RX pins, then you can’t use UART.
This section provides guidance for people who need to build a Fuchsia image with hardware testing tools enabled from source. If you already have a Fuchsia image with the tools you need then you can skip this section.
If you've never built Fuchsia from source and need help with the basic workflows, see the following tutorials:
If you try running a hardware testing tool (like gpioutil for example) and get a not found error, it probably means that the hardware testing tool was not enabled when your Fuchsia image was built. Example:
-v: 1: gpioutil: not found
To fix this, try adding --with-base //bundles/tools to your fx set call:
fx set {{"<var>"}}PRODUCT{{"</var>"}}.{{"<var>"}}BOARD{{"</var>"}} --with-base '//bundles/tools'
The --with-base option adds all of the dependencies listed in //bundles/tools/BUILD.gn as base packages in your Fuchsia image. Most of Fuchsia's hardware testing tools are in this bundle.
Caution: {{“”}}PRODUCT{{“”}} and {{“”}}BOARD{{“”}} are placeholder values. You need to replace them with real product and board names. Run fx list-products and fx list-boards to see which products and boards are available in your Fuchsia checkout. You should also double-check that you are using the correct product and board. If you're using the wrong product or board, that could also explain why a hardware testing tool is missing.
If the hardware testing tool you need is not listed in //bundles/tools/BUILD.gn try setting the --with-base value to the path to the hardware testing tool's BUILD.gn file. For example, the gpioutil build file is located at //src/devices/gpio/bin/gpioutil/BUILD.gn. You can directly include gpioutil as a base package with the following fx set command:
fx set {{"<var>"}}PRODUCT{{"</var>"}}.{{"<var>"}}BOARD{{"</var>"}} --with-base '//src/devices/gpio/bin/gpioutil'
You can repeat the --with-base option as many times as needed:
fx set {{"<var>"}}PRODUCT{{"</var>"}}.{{"<var>"}}BOARD{{"</var>"}} \ --with-base '//src/devices/gpio/bin/gpioutil' \ --with-base '//src/media/audio/tools/audio-driver-ctl'
To enable adb in your Fuchsia image, you will need to include the adb function driver and a daemon. The daemon can be the Fuchsia adb daemon or any other daemon that speaks to the function driver.
As explained in Overview, you send commands from your test host to your Fuchsia device over a transport system like ffx, adb, or UART. This section provides more detail about how to run commands with each transport system.
The underlying {{ widgets.glossary_simple (‘component’, ‘component’)}} that powers each transport system affects what features are available to you. Different components expose different {{ widgets.glossary_simple (‘capability’, ‘capabilities’)}}.
The capabilities available in ffx are determined by the component you're exploring. The capabilities available in adb and UART are determined by console-launcher, which is the underlying component that powers those shells.
ffx is Fuchsia's main tool for host-target interactions.
To start an interactive shell:
ffx component explore {{"<var>"}}COMPONENT{{"</var>"}} -l namespace
Caution: {{“”}}COMPONENT{{“”}} is a placeholder value. You need to replace it with the name of a real diagnostic component.
To run single commands (gpioutil list for example):
ffx component explore {{"<var>"}}COMPONENT{{"</var>"}} -l namespace -c 'gpioutil list'
Most Fuchsia {{ widgets.glossary_simple (‘board’, ‘boards’)}} support 3-pin (TX, RX, GND) UART communication. They usually expect the typical 115200 8N1 UART configuration. To send commands from your test host to your Fuchsia device you'll need a serial console like minicom or fx serial.
If your Fuchsia image included adb then you can send commands from your test host to your Fuchsia device with adb.
To start an interactive shell:
adb shell
To run single commands (gpioutil list for example):
adb shell 'gpioutil list'
Fuchsia only has partial support for adb by design. See RFC-0200 for details on what‘s supported and what’s not. See //src/developer/adb/bin/README.md for more guidance on using adb with Fuchsia.
The following table points you to the specific tools that you can use to test out the various hardware subsystems on your Fuchsia device.