# Scripting remote interaction with a Fuchsia device

This guide contains a tutorial for writing a script to remotely interact with a
Fuchsia device, various other example scripted interactions, and a primer on
implementing a FIDL server in Python on a host.

The methods on this page were originally developed for end-to-end testing, but
you may also find them useful for scripting simple device interactions without
having to write an `ffx` plugin in Rust.

## Background

The following technologies enable scripting remote interactions with a Fuchsia
device:

- [Python FIDL bindings][python-fidl-bindings]
- [Fuchsia Controller][fuchsia-controller]
- [Overnet][overnet]

Together, Fuchsia Controller and Overnet provide a transport between the host
running a Python script and the target Fuchsia device. And the Python FIDL
bindings, like FIDL bindings in other languages, facilitate sending and
receiving messages from components on the target device.

You generally only need to interact with Python FIDL bindings after connecting
to your target device. Connecting to the target device, as you will see, is
done with the `Context` class from the `fuchsia_controller_py` module.

Setting Overnet aside, the `libfuchsia_controller_internal.so` shared library
(which includes the ABI [header][fuchsia-controller-header-file]) is the core
library that drives scripted remote interactions.

## The Context object

The `Context` object is the main entry point for all Fuchsia controller
interactions. It is responsible for creating and managing connections to Fuchsia
devices and is the primary method for getting access to FIDL handles.

When constructed, the `Context` object can take a dictionary of configuration
key/value pairs, similar to the usage of [`ffx config`][ffx-config].

```python
config = { "log.dir": "/path/to/logs", "log.level": "trace" }
ctx = Context(target="nodename", config=config)
```

In most cases, a user must specify a target, which is the nodename of a Fuchsia
device.

The most common way of using this object is to connect to a specific FIDL
protocol on a component running on a Fuchsia device. This is done by calling the
`connect_to_protocol` method, which takes a component moniker and a protocol
name.

## Tutorial

This tutorial walks through writing a Python script that reads a list of
addresses and prints information about the Fuchsia device at each address.

Note: Most FIDL interfaces should just work. However, some advanced APIs are not
supported, e.g., reading from or writing to a VMO.

1. [Prerequisites](#prerequisites)
2. [Create a build target](#create-a-build-target)
3. [Write the script](#write-the-script)
4. [Build and run the script](#build-and-run-the-script)

Please [file an issue][file-an-issue] if you encounter bugs, or have questions
or suggestions.

### Prerequisites {:.numbered}

This tutorial requires the following:

- [Fuchsia source checkout and associated development environment.][get-started]
- Fuchsia device (physical or emulated) reachable via `ffx` that exposes
  the remote control service (RCS).

  When running `ffx target list`, the field under `RCS` must read `Y`:

  ```none {:.devsite-disable-click-to-copy}
  NAME                    SERIAL       TYPE       STATE      ADDRS/IP                       RCS
  fuchsia-emulator        <unknown>    Unknown    Product    [fe80::5054:ff:fe63:5e7a%4]    Y
  ```

  (For more information, see
  [Interacting with target devices][interact-with-target-devices].)

### Create a build target {:.numbered}

Update a `BUILD.gn` file to include a build target like the following:

```none {:.devsite-disable-click-to-copy}
import("//build/python/python_binary.gni")

assert(is_host)

{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/BUILD.gn" region_tag="describe_host_example_build_target" %}
```

The `ffx` libraries enable connecting to our Fuchsia device. And
the FIDL dependencies make the necessary Python FIDL bindings available to the
script.

### Write the script {:.numbered}

First, our script needs to import the necessary modules:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/examples/describe_host.py" region_tag="required_import_block" %}
```

The `fidl_fuchsia_developer_remotecontrol` and `fidl_fuchsia_buildinfo` Python
modules contains the Python FIDL bindings for the `fuchsia.developer.ffx` and
`fuchsia.buildinfo` FIDL libraries.

The `Context` object provides connections to Fuchsia targets.

Next, our script needs to define a function (called `describe_host` in this
example) to retrieve information from a target device:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/examples/describe_host.py" region_tag="describe_host_function" %}
```

This function instantiates a `Context` to connect to a Fuchsia device at
particular IP address, and then call the
`fuchsia.developer.remotecontrol/RemoteControl.IdentifyHost` and
`fuchsia.buildinfo/Provider.GetBuildInfo` methods to get information about the
target.

Note: You might notice the component moniker `core/build-info` in the script.
See the [Finding component monikers][#finding-component-monikers] for how to
discover the component moniker for the Fuchsia component you wish to communicate
with.

Note: The `.unwrap()` called on the result of the `IdentifyHost` call is a
helper method defined for FIDL result types. It either returns the response
contained in the result, if there is one, or raises an AssertionError if the
result contains a framework or domain error. (The `.response` in this example is
a little misleading because the returned `RemoteControlIdentifyHostResult` has a
response field with type `RemoteControlIdentifyHostResponse` that also contains
a response field. There are two nested response fields in the value returned by
`IdentifyHost`).

Finally, you wrap this code with some Python boilerplate to read addresses and
print information for each target device. Thus, you arrive at the following
script:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/examples/describe_host.py" region_tag="full_code" %}
```

### Build and run the script {:.numbered}

This example code lives in `//tools/fidl/fidlgen_python`, so you build it with
the following command on an `x64` host (after adding
`//tools/fidl/fidlgen_python:examples` to `host_labels` with `fx args`):

```posix-terminal
fx build --host //tools/fidl/fidlgen_python:describe_host_example
```

Next, you use `ffx target list` to identify the address of our target device.

```sh {:.devsite-disable-click-to-copy}
$ ffx target list
NAME                      SERIAL          TYPE        STATE      ADDRS/IP                                       RCS
fuchsia-emulator          <unknown>       core.x64    Product    [127.0.0.1:34953]                              Y
```

Then you run the script!

```sh {:.devsite-disable-click-to-copy}
$ fx run-in-build-dir host_x64/obj/tools/fidl/fidlgen_python/describe_host_example.pyz '127.0.0.1:34953'
Target Info Received:

    --- 127.0.0.1:34953 ---
    nodename: fuchsia-emulator
    product_config: core
    board_config: x64
    version: 2025-04-08T02:04:13+00:00
```

## Finding component monikers
To communicate with a Fuchsia component, a script must know the component's
moniker in advance. A component moniker can be retrieved using `ffx`. For
example, the following `ffx` command will print that `core/build-info` exposes
the `fuchsia.buildinfo/Provider` capability:

```posix-terminal
ffx component capability fuchsia.buildinfo.Provider
```

This command will print output similar to the following:

```sh {:.devsite-disable-click-to-copy}
Declarations:
  `core/build-info` declared capability `fuchsia.buildinfo.Provider`

Exposes:
  `core/build-info` exposed `fuchsia.buildinfo.Provider` from self to parent

Offers:
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#cobalt`
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#remote-control`
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#sshd-host`
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#test_manager`
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#testing`
  `core` offered `fuchsia.buildinfo.Provider` from child `#build-info` to child `#toolbox`
  `core/sshd-host` offered `fuchsia.buildinfo.Provider` from parent to collection `#shell`

Uses:
  `core/remote-control` used `fuchsia.buildinfo.Provider` from parent
  `core/sshd-host/shell:sshd-0` used `fuchsia.buildinfo.Provider` from parent
  `core/cobalt` used `fuchsia.buildinfo.Provider` from parent
```

## Other examples

This section demonstrates various other scripted interactions.

Note: For more information on Python FIDL bindings, see this
[Python FIDL bindings][python-fidl-bindings] page.

### Reboot a device {:.numbered}

There's more than one way to reboot a device. One approach to reboot a device is
to connect to a component running the
`fuchsia.hardware.power.statecontrol/Admin` protocol, which can be found under
`/bootstrap/shutdown_shim`.

With this approach, the protocol is expected to exit mid-execution of the method
with a `PEER_CLOSED` error:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="src/developer/ffx/lib/fuchsia-controller/end_to_end_tests/mobly/reboot_test.py" region_tag="reboot_example" %}
```

However, a challenging part comes afterward when you need to determine whether
or not the device has come back online. This is usually done by attempting to
connect to a protocol (usually the `RemoteControl` protocol) until a timeout is
reached.


### Run a component

Note: This section may be subject to change depending on the development in the
component framework.

You can use the `RemoteControl` protocol to start a component, which involves
the following steps:

1. Connect to the lifecycle controller:

   ```py
   import fidl_fuchsia_developer_remotecontrol as f_remotecontrol
   import fidl_fuchsia_sys2 as f_sys2
   ch = ctx.connect_to_remote_control_proxy()
   remote_control_proxy = f_remotecontrol.RemoteControlClient(ch)
   client, server = fuchsia_controller_py.Channel.create()
   await remote_control_proxy.root_lifecycle_controller(server=server.take())
   lifecycle_ctrl = f_sys2.LifecycleControllerClient(client)
   ```

2. Attempt to start the instance of the component:

   ```py
   import fidl_fuchsia_component as f_component
   client, server = fuchsia_controller_py.Channel.create()
   await lifecycle_ctrl.start_instance("some_moniker", server=server.take())
   binder = f_component.BinderClient(client)
   ```

   The `binder` object lets the user know whether or not the component remains
   connected. However, it has no methods. Support to determine whether the
   component has become unbound (using the binder protocol) is not yet
   implemented.

### Get a snapshot

Getting a snapshot from a fuchsia device involves running a snapshot and binding
a `File` protocol for reading:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="src/developer/ffx/lib/fuchsia-controller/end_to_end_tests/mobly/target_identity_tests.py" region_tag="snapshot_example" %}
```

## Implementing a FIDL server on a host

An important task for Fuchsia Controller (either for handling passed bindings or
for testing complex client side code) is to run a FIDL server. In this section,
you return to the `echo` example and implement an `echo` server. The functions
you need to override are derived from the FIDL file definition. So the `echo`
server (using the `ffx` protocol) would look like below:

```py
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/tests/test_server_and_event_handler.py" region_tag="echo_server_impl" %}
```

To make a proper implementation, you need to import the appropriate libraries.
As before, you will import `fidl_fuchsia_developer_ffx`. However, since you're
going to run an `echo` server, the quickest way to test this server is to use a
`Channel` object from the `fuchsia_controller_py` library:

```py
import fidl_fuchsia_developer_ffx as ffx
from fuchsia_controller_py import Channel
```

This `Channel` object behaves similarly to the ones in other languages. The
following code is a simple program that utilizes the `echo` server:

```py
import asyncio
import unittest
import fidl_fuchsia_developer_ffx as ffx
from fuchsia_controller_py import Channel


{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/tests/test_server_and_event_handler.py" region_tag="echo_server_impl" %}


class TestCases(unittest.IsolatedAsyncioTestCase):

    async def test_echoer_example(self):
{% includecode gerrit_repo="fuchsia/fuchsia" gerrit_path="tools/fidl/fidlgen_python/tests/test_server_and_event_handler.py" region_tag="use_echoer_example" %}
```

There are a few things to note when implementing a server:

* Method definitions can either be `sync` or `async`.
* The `serve()` task will process requests and call the necessary method in
  the server implementation until either the task is completed or the
  underlying channel object is closed.
* If an exception occurs when the serving task is running, the client
  channel receives a `PEER_CLOSED` error. Then you must check the result
  of the serving task.
* Unlike Rust's async code, when creating an async task, you must keep
  the returned object until you're done with it. Otherwise, the task may
  be garbage collected and canceled.

### Common FIDL server code patterns

Note: For more information on writing async Python code with Fuchsia Controller,
see this [async Python][async-python] page.

In contrast to the simple `echo` server example above, this section covers
different types of server interactions.

#### Creating a FIDL server class

Let's work with the following FIDL protocol to make a server:

```fidl
library fuchsia.exampleserver;

type SomeGenericError = flexible enum {
    THIS = 1;
    THAT = 2;
    THOSE = 3;
};

closed protocol Example {
    strict CheckFileExists(struct {
        path string:255;
        follow_symlinks bool;
    }) -> (struct {
        exists bool;
    }) error SomeGenericError;
};
```

FIDL method names are derived by changing the method name from Camel case to
Lower snake case. So the method `CheckFileExists` in Python changes to
`check_file_exists`.

The anonymous struct types is derived from the whole protocol name and
method. As a result, they can be quite verbose. The input method's input
parameter is defined as a type called `ExampleCheckFileExistsRequest`. And
the response is called `ExampleCheckFileExistsResponse`.

Putting these together, the FIDL server implementation in Python looks like
below:

```py
import fidl_fuchsia_exampleserver as fe

class ExampleServerImpl(fe.ExampleServer):

    def some_file_check_function(path: str) -> bool:
        # Just pretend a real check happens here.
        return True

    def check_file_exists(self, req: fe.ExampleCheckFileExistsRequest) -> fe.ExampleCheckFileExistsResponse:
        return fe.ExampleCheckFileExistsResponse(
            exists=ExampleServerImpl.some_file_check_function()
        )
```

It is also possible to implement the methods as `async` without issues.

In addition, returning an error requires wrapping the error in the FIDL
`DomainError` object, for example:

```py
import fidl_fuchsia_exampleserver as fe

from fidl import DomainError

class ExampleServerImpl(fe.ExampleServer):

    def check_file_exists(self, req: fe.ExampleCheckFileExistsRequests) -> fe.ExampleCheckFileExistsResponse | DomainError:
        return DomainError(error=fe.SomeGenericError.THIS)
```

#### Handling events

Event handlers are written similarly to servers. Events are handled on the
client side of a channel, so passing a client is necessary to construct an event
handler.

Let's start with the following FIDL code to build an example:

```fidl
library fuchsia.exampleserver;

closed protocol Example {
    strict -> OnFirst(struct {
        message string:128;
    });
    strict -> OnSecond();
};
```

This FIDL example contains two different events that the event handler needs
to handle. Writing the simplest class that does nothing but print looks like
below:

```py
import fidl_fuchsia_exampleserver as fe

class ExampleEventHandler(fe.ExampleEventHandler):

    def on_first(self, req: fe.ExampleOnFirstRequest):
        print(f"Got a message on first: {req.message}")

    def on_second(self):
        print(f"Got an 'on second' event")
```

If you want to stop handling events without error, you can raise
`fidl.StopEventHandler`.

An example of this event can be tested using some existing fidlgen_python
testing code. But first, make sure that the Fuchsia controller tests have been
added to the Fuchsia build settings, for example:

```sh {:.devsite-disable-click-to-copy}
fx set ... --with-host //tools/fidl/fidlgen_python:tests
```

With a protocol from `fuchsia.controller.test` (defined in
[`fuchsia_controller.test.fidl`][test-fidl]), you can write code that
uses the `ExampleEvents` protocol, for example:

```py
import asyncio
import fidl_fuchsia_controller_test as fct

from fidl import StopEventHandler
from fuchsia_controller_py import Channel

class ExampleEventHandler(fct.ExampleEventsEventHandler):

    def on_first(self, req: fct.ExampleEventsOnFirstRequest):
        print(f"Got on-first event message: {req.message}")

    def on_second(self):
        print(f"Got on-second event")
        raise StopEventHandler

async def main():
    client_chan, server_chan = Channel.create()
    client = fct.ExampleEventsClient(client_chan)
    server = fct.ExampleEventsServer(server_chan)
    event_handler = ExampleEventHandler(client)
    event_handler_task = asyncio.get_running_loop().create_task(
        event_handler.serve()
    )
    server.on_first(message="first message")
    server.on_second()
    server.on_complete()
    await event_handler_task

if __name__ == "__main__":
    asyncio.run(main())
```

Then this can be run by completing the Python environment setup steps in the
[next section](#experiment-with-the-python-interpreter). When run, it prints
the following output and exits:

```sh {:.devsite-disable-click-to-copy}
Got on-first event message: first message
Got on-second event
```

For more examples on server testing, see this
[`test_server_and_event_handler.py`][test-server-and-event-handler] file.

<!-- Reference links -->

[python-fidl-bindings]: /docs/development/tools/fuchsia-controller/fidl-bindings.md
[fuchsia-controller]: /src/developer/ffx/lib/fuchsia-controller/README.md
[overnet]: /src/connectivity/overnet/README.md
[fuchsia-controller-header-file]: /src/developer/ffx/lib/fuchsia-controller/cpp/fuchsia_controller_internal/fuchsia_controller.h
[file-an-issue]: https://issuetracker.google.com/issues/new?component=1378581&template=1840403
[interact-with-target-devices]: /docs/development/tools/ffx/getting-started.md#interacting_with_target_devices
[test-server-and-event-handler]: /tools/fidl/fidlgen_python/tests/test_server_and_event_handler.py
[test-fidl]: /src/developer/ffx/lib/fuchsia-controller/fidl/fuchsia_controller.test.fidl
[async-python]: /docs/development/tools/fuchsia-controller/async-python.md
[get-started]: /docs/get-started/README.md
[ffx-config]: /docs/development/tools/ffx/commands/config.md#runtime-configuration