Getting started with ffx

This doc will guide you through some of the features of ffx. For an overview of the design and components of ffx, see the ffx overview.

Warning: ffx is currently in alpha. Its APIs, command-line surface, and documentation are subject to change.

Contacting the ffx team

If you discover possible bugs or have questions or suggestions, file a bug.

Prerequisites

To follow the examples in this doc, you’ll need a Fuchsia device running. If you don’t have a physical device connected, you can use an emulator with networking enabled (-N).

Tip: To start a headless emulator, run fx emu --headless --software-gpu -N.

Your device must be running a core product configuration or a product configuration that extends core (such as workstation).

Optionally, you can run fx log, which will provide some additional information about the interactions between ffx and your Fuchsia target device.

Introduction

After following all the prerequisites, run the following in a terminal:

  1. fx ffx help

This will list all of the available ffx subcommands. You’ll see something like:

  1. Usage: ffx [-c <config>] [-e <env>] [-t <target>] [<command>] [<args>]
  3. Fuchsia's developer tool
  5. Options:
  6.   -c, --config      override default configuration
  7.   -e, --env         override default environment settings
  8.   -t, --target      apply operations across single or multiple targets
  9.   --help            display usage information
  11. Commands:
  12.   component         Discover and manage components
  13.   config            View and switch default and user configurations
  14.   daemon            Interact with/control the ffx daemon
  15.   diagnostic        Run diagnostic tests on Fuchsia targets
  16.   docs              View suite of docs for ffx and for Fuchsia
  17.   doctor            Run common checks for the ffx tool and host environment
  18.   emulator          Start and manage Fuchsia emulators
  19.   overnet           Interact with the Overnet mesh
  20.   package           Create and publish Fuchsia packages
  21.   sdk               Modify or query the installed SDKs
  22.   target            Interact with a target device or emulator
  23.   vendor            Run partner plugins
  24.   version           Print out ffx tool and daemon versions

You can use fx ffx help <subcommand> or fx ffx <subcommand> --help to see more about any subcommand.

Interacting with target devices

In a terminal, run the following:

  1. fx ffx target list

You’ll see a list of devices that ffx has discovered. For example, with a single emulator running, output looks like:

  1. NAME                    TYPE       STATE      ADDRS/IP                       AGE     CS
  2. fuchsia-5254-0063-5e7a  Unknown    Unknown    [fe80::5054:ff:fe63:5e7a%4]    0m0s    N

NOTE: Ignore the TYPE and STATE columns - they have no values besides UNKNOWN right now.

A couple of columns are worth explanation:

  • AGE: This is the time since ffx was last able to reach the device.
  • RCS: Indicates whether there is a reachable instance of the Remote Control Service (RCS) running on the device.

In order to get ffx to automatically connect to a device, you must either have set the target’s nodename to be the default target, or attempt to interact with the device.

To set the target to be the default, run:

  1. fx ffx target default set $NODENAME

If the default target has been set prior to starting the daemon, waiting a few seconds should yield a change to the RCS status to show Y.

If the default target has been set after starting the daemon, attempting to interact with the target should be sufficient to kick off a connection, like the following

  1. fx ffx component list

NOTE: if the default target has been set, and you are unable to run that command against the target, reach out to the ffx team.

Then the next time you list targets you should see that an RCS connection isn’t active.

  1. $ fx ffx target list
  2. NAME                    TYPE       STATE      ADDRS/IP                       AGE     RCS
  3. fuchsia-5254-0063-5e7a  Unknown    Unknown    [fe80::5054:ff:fe63:5e7a%4]    0m6s    Y

If a target has been set as default there will be a * next to it.

If you had fx log running, you should also see something like the following in the logs:

  1. [00009.776170][28540][28542][remote-control, remote_control_bin] INFO: published remote control service to overnet

NOTE: if the RCS column remains N for an extended amount of time and you have already set this target’s nodename to target.default before initially starting ffx, reach out to the ffx team.

On Default Targets

Above we covered setting the default target using the command

  1. fx ffx target default set

It is also possible to set the default target on a per-command basis using the --target flag like so.

  1. fx ffx --target $NODENAME component list

Interacting with multiple devices

TODO: fill this out.

Controlling the state of target devices

You can use the target off and target reboot subcommands to power-off or reboot a device, respectively.

Configuration

See documentation for the config command.

Interacting with Components

Selectors

Many ffx commands that use components take selectors as a parameter. You can read more about selectors and their syntax in component selector documentation.

Inspecting the component topology

You can use the component select command to

For example, the following command will display all services offered by v1 components:

  1. $ fx ffx component select moniker 'core/appmgr:out:*'`
  3. core/appmgr
  4. |
  5. --out
  6.    |
  7.    --chromium.cast.ApplicationConfigManager
  8.    --fuchsia.bluetooth.avrcp.PeerManager
  9.    --fuchsia.bluetooth.avrcp.test.PeerManagerExt
  10.    --fuchsia.bluetooth.bredr.Profile
  11.    --fuchsia.bluetooth.control.Control
  12.    --fuchsia.bluetooth.gatt.Server
  13.    --fuchsia.bluetooth.le.Central
  14.    --fuchsia.bluetooth.le.Peripheral
  15.    --fuchsia.bluetooth.snoop.Snoop
  16.    --fuchsia.bluetooth.sys.Access
  17.    --fuchsia.bluetooth.sys.HostWatcher
  18.    --fuchsia.boot.Arguments
  19.    --fuchsia.boot.FactoryItems
  20.    --fuchsia.boot.Items
  21.    --fuchsia.boot.ReadOnlyLog
  22.    --fuchsia.boot.RootJobForInspect
  23.    --fuchsia.boot.RootResource
  24.    [truncated]

Note: this command can be slow (~10-15s), especially for selectors that match a large number of services.

The following command will display all components that expose diagnostics:

  1. $ fx ffx component select capability diagnostics
  3. ./bootstrap/archivist
  4. ./bootstrap/driver_manager
  5. ./bootstrap/fshost
  6. ./bootstrap/power_manager
  7. ./core/appmgr
  8. ./core/detect
  9. ./core/last_reboot
  10. ./core/log-stats
  11. ./core/pkg-cache
  12. ./core/sampler
  13. ./core/system-update-committer

Verifying a service is up

You can use the component knock command to verify that a service starts successfully: knock will open a channel to the service and return success if and only if the channel isn’t closed.

The component framework will start the component that provides the service on-demand.

Note: the selector you pass to knock may contain a wildcard but must match exactly one service. You cannot knock on multiple services at once.

For example:

  1. $ fx ffx component knock 'core/appmgr:out:fuchsia.hwinfo.P*'
  2. Success: service is up. Connected to 'core/appmgr:out:fuchsia.hwinfo.Product'.
  4. $ fx ffx component knock 'core/appmgr:out:not.a.real.service'
  5. Failed to connect to service: NoMatchingServices

Running a component

ffx can run components on a device given their package URL and arguments. stdout and stderr will be streamed to the corresponding descriptor on the host terminal.

Only v1 components can be run: v2 components are only started on-demand by the framework. Learn more about the component lifecycle here.

Note: fx serve must be running in order to component run a package that is not in base or cached.

Here’s an example of running the Rust hello-world component. First, you’ll need the hello-world package in your universe:

  1. $ fx set <product>.<board> --with //examples/hello_world/rust:hello-world-rust && fx build
  2. ...
  3. $ fx ffx component run fuchsia-pkg://fuchsia.com/hello-world-rust#meta/hello-world-rust.cmx
  4. Hello, world!

Resolving connectivity issues

If you’re experiencing problems communicating with a target device using ffx, you can use the doctor command to diagnose and attempt to resolve them. If you file a bug that involves a target device, we’ll typically ask for the output from ffx doctor to provide information about where the problem is.

doctor will attempt to communicate with the ffx daemon, killing and restarting it if needed. If this is successful, it will attempt to SSH into a target device and start the Remote Control Service.

If you try running ffx doctor under normal circumstances, you should see:

  1. $ fx ffx doctor
  2. Checking for a running daemon...none running.
  3. Attempting to kill any zombie daemons...killed at least one daemon.
  4. Starting a new daemon instance...success
  5. Attempting to connect to the daemon. This may take a couple seconds...success
  6. Attempting to communicate with the daemon...success
  7. Attempting to list targets...success
  8. Attempting to get an RCS connection...success
  9. Attempting to communicate with RCS...success
  12. SUCCESS. You should be able to run ffx commands now.

If doctor fails, it will try to suggest a resolution to the problem. It will also provide a link to the Monorail component in which you can file a bug if you persistently have problems. For example, if doctor is unable to start the RCS, you would see the following:

  1. $ fx ffx doctor
  2. Checking for a running daemon...found
  3. Attempting to connect to the daemon. This may take a couple seconds...success
  4. Attempting to communicate with the daemon...success
  5. Attempting to list targets...success
  6. Attempting to get an RCS connection...success
  7. Attempting to communicate with RCS...FAILED. Timed out.
  10. Attempt 2 of 3
  11. Attempting to list targets...success
  12. Attempting to get an RCS connection...success
  13. Attempting to communicate with RCS...FAILED. Timed out.
  16. Attempt 3 of 3
  17. Attempting to list targets...success
  18. Attempting to get an RCS connection...success
  19. Attempting to communicate with RCS...FAILED. Timed out.
  22. Connecting to RCS failed after maximum attempts. To resolve this issue, try
  23. rebooting your device. If this persists, please file a bug at the link below
  24. and include 1) all output
  25. above and 2) device syslog if available.Bug link: ...

Next steps