# Gazoo Device Manager (GDM)
`gazoo_device` is a python package for interacting with smart devices. \
It contains Gazoo Device Manager (GDM), which defines a common device interface.
The common device interface standardizes device interactions and allows test
writers to share tests across devices despite the underlying differences in
communication types, OSes, and logic. \
GDM is available as a Python package for use in tests and comes with its own CLI
for quick device interactions. \
GDM is the open-source architecture which enables device-agnostic interations.
Device controllers used by GDM are contained in separate Python packages and can
be registered with the GDM architecture. \
GDM runs on the test host and communicates with the physical devices via one or
more device transports (such as SSH, ADB, HTTPS, UART). GDM does not require any
additional support from the device firmware.
GDM is used in most end-to-end device tests at Google Nest.
## Table of contents
1. [Install](#install)
1. [Uninstall](#uninstall)
2. [Quick start](#quick-start)
3. [Device controllers in GDM](#device-controllers-in-gdm)
4. [Config files](#config-files)
5. [Logs](#logs)
6. [Detecting devices](#detecting-devices)
7. [Using the CLI](#using-the-cli)
1. [Exploring device capabilities without a physical device](#exploring-device-capabilities-without-a-physical-device)
2. [Exploring device capabilities with a physical device](#exploring-device-capabilities-with-a-physical-device)
3. [Basic CLI usage](#basic-cli-usage)
8. [Using the gazoo_device python package](#using-the-gazoo_device-python-package)
9. [How to use GDM with test frameworks](#how-to-use-gdm-with-test-frameworks)
1. [GDM with Mobly](#gdm-with-mobly)
2. [GDM with Unittest](#gdm-with-unittest)
10. [Contributor documentation](#contributor-documentation)
11. [License](#license)
12. [Disclaimer](#disclaimer)
## Install
Supported host operating systems:
* Debian;
* Ubuntu;
* MacOS.
Windows is not supported.
Note: Raspberry Pi 4 on 64-bit Ubuntu 20.04 LTS is also supported as a host (see
the relevant [device setup section](docs/Raspberry_Pi_as_host.md)).
MacOS prerequisites:
1. Install Xcode Command Line Tools:
```shell
xcode-select --install
```
2. Install Brew (MacOS package manager):
https://brew.sh/
3. Verify your system `python3` executable.
1. Check that Python 3 is available:
```shell
which python3
```
2. Check that your Python 3 version is at least 3.9:
```
python3 -V
```
3. Check that your `python3` executable has `pip` module:
```
python3 -m pip --version
```
Installation steps:
1. Download the GDM installer archive:
```shell
curl -OL https://github.com/google/gazoo-device/releases/latest/download/gdm-install.sh
```
2. Run the installer:
```shell
bash gdm-install.sh
```
You should see the following message at the end of the installation:
```
Install done (exit 0)
```
3. Add `gdm` to your `$PATH`:
Add the following line to `~/.bash_profile` or `~/.bashrc`:
```shell
export PATH="${PATH}:${HOME}/gazoo/bin"
```
4. [Optional] Install optional dependencies
1.
Some of GDM's dependencies are optional and are not installed by the
installer automatically due to licensing restrictions.
To enable flashing NRF52840 DK and EFR32 dev boards through GDM, install the
J-Link SDK:
https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack.
Additional note to Apple M1 users:
Make sure to download "64-bit Apple M1 Installer" under macOS.
To determine whether your Mac is using an M1 chip, run
```
arch
```
in terminal. If you see ```arm64```, then your Mac is using M1.
2.
To enable flashing ESP32 dev boards through GDM, install `esptool`:
```shell
~/gazoo/gdm/virtual_env/bin/pip install esptool==4.1
```
GDM installation creates a virtual environment for the CLI at
`~/gazoo/gdm/virtual_env`. \
`gdm` CLI commands run in this virtual environment.
Run a few GDM CLI commands to verify GDM works:
```shell
gdm -v
gdm devices
gdm
```
`gdm -v` displays versions of the GDM launcher and of the python package:
```
Gazoo Device Manager launcher 1.0
Gazoo Device Manager 1.0.0
```
Typical output of `gdm devices`:
```
Device Alias Type Model Connected
--------------- --------------- ----------- ---------------- ------------
Other Devices Alias Type Model Available
--------------- --------------- ----------- ---------------- ------------
0 total Gazoo device(s) available.
```
`gdm` displays a help menu.
To update GDM to the latest version:
```
gdm update-gdm
```
To update (or downgrade) GDM to a specific version:
```
gdm update-gdm <version> # Example: gdm update-gdm 1.0.0
```
To install GDM in a virtual environment:
```
/path_to_virtual_env/bin/pip install gazoo-device
```
### Uninstall
To uninstall GDM:
```
curl -OL https://github.com/google/gazoo-device/releases/latest/download/gdm-cleanup.sh
bash gdm-cleanup.sh
```
## Quick start
This is the quickest way to get your hands dirty with GDM. You will need a
Raspberry Pi.
1. [Install GDM on the host](#install).
2. [Set up your Raspberry Pi as an auxiliary device in GDM and try out the CLI](docs/device_setup/Raspberry_Pi_as_supporting_device.md).
3. [Run the example on-device test with a test framework of your choice](https://github.com/google/gazoo-device/blob/master/examples/device_tests/README.md).
## Device controllers in GDM
To interact with devices, GDM creates one Python device controller object for
each physical device. The lifecycle of GDM device controllers is as follows:
1. a new device is connected to the host and is detected by GDM (one-time setup
step), which makes the device known to GDM:
```
gdm detect
```
2. a device controller instance is created at the beginning of a test or a CLI
device interaction;
3. one or more device commands are issued through the device controller
instance;
4. the device controller instance is closed when the test is finished or the
CLI interaction completes;
5. if the device is permanently disconnected from the host, it is removed from
the list of devices known to GDM (also a one-time step) through
```
gdm delete device-1234
```
Note that the term "device" is ambiguous in the context of GDM: it can refer to
either the device controller or the physical device. Device controllers can also
be referred to as device classes.
## Config files
GDM device configs are found in `~/gazoo/gdm/conf`.
You should not modify them directly. Instead, use `set-prop` and `get-prop`
commands:
* To set an optional device property:
```
gdm set-prop device-1234 property-name property-value
```
* To retrieve a device property:
```
gdm get-prop device-1234 property-name
```
* To set a Manager property:
```
gdm set-prop manager property-name property-value
```
* To retrieve a Manager property:
```
gdm get-prop manager property-name
```
## Logs
By default all GDM logs go to `~/gazoo/gdm/log/`. Log verbosity, output
directory, and standard output behavior can be configured via arguments to
`Manager.__init__` (see [gazoo_device/manager.py](gazoo_device/manager.py)).
GDM creates three types of log files.
### The `gdm.txt` log
All GDM logs go here. Device logs are **not** captured in this file. This log
file persists across GDM invocations. It provides the best history, but it can
be difficult to pinpoint the logs for a particular device interaction.
### Device log files, such as `linuxexample-1eb2-20201113-123538.txt`
These capture all communications between GDM and the device. Each log line is
prefixed with `GDM-<letter_or_digit>`, such as `GDM-M`, `GDM-0`, or `GDM-1`.
`GDM-M` are logs written by GDM. These include the commands that GDM wrote, the
regular expressions GDM expects to find after writing a command and the maximum
time window for the response, and the result of the expect (which regular
expression matched, if any).
`GDM-0`, `GDM-1`, and other `GDM-<digit>` logs come from device transports. The
digit corresponds to the index of the transport (as defined by
`get_transport_list()` methods of communication types in
[gazoo_device/switchboard/communication_types.py](gazoo_device/switchboard/communication_types.py)).
\
For some communication types, such as SSH and ADB, logs and command responses
come from different transports. In that case device responses come from `GDM-0`
and device logs come from `GDM-1`. \
For other communication types, there may only be a single transport, in which
case both device responses and logs come from `GDM-0`.
The names of device log files are logged during every CLI interaction. For
example: `linuxexample-1eb2 logging to file
/Users/artorl/gdm/log/linuxexample-1eb2-20201113-123548.txt`
### Device log event files, such as `linuxexample-1eb2-20201113-123548-events.txt`
These contain device log events. The log events to be captured are defined by
log event filters in [gazoo_device/filters/](gazoo_device/filters/).
A log filtering process receives all device logs in real time and captures lines
which match any of the device log filters into the device log event file.
The name of the log event file is constructed as
`<name_of_log_file>-events.txt`. For example,
`linuxexample-1eb2-20201113-123548-events.txt` is the log event file for the
`linuxexample-1eb2-20201113-123548.txt` device log file.
## Detecting devices
To detect all devices attached to your host, run `gdm detect` on the host. This
is a one-time step that is required when GDM is installed on the host or when a
new device is connected to the host. Devices typically require a special setup
before being usable with GDM. This can include a special cable connection
configuration, renaming serial cables, updating device firmware to a specific
version, setting up the device on a static IP address, or setting up
passwordless SSH access to the device. Refer to
[docs/device_setup/](docs/device_setup/) for instructions.
Device detection populates device configs:
* persistent properties are stored in `~/gazoo/gdm/conf/devices.json`;
* optional (settable) properties are stored in
`~/gazoo/gdm/conf/device_options.json`.
To view all devices currently known to GDM, run `gdm devices`.
Sample detection output (`cambrionix-kljo` was detected):
```
$ gdm detect
##### Step 1/3: Detecting potential new communication addresses. #####
detecting potential AdbComms communication addresses
detecting potential DockerComms communication addresses
'docker' is not installed. Cannot get Docker devices.
detecting potential JlinkSerialComms communication addresses
detecting potential PtyProcessComms communication addresses
detecting potential SshComms communication addresses
detecting potential SerialComms communication addresses
detecting potential YepkitComms communication addresses
'ykushcmd' is not installed. Cannot get Yepkit serials.
detecting potential PigweedSerialComms communication addresses
Found 1 possible serialcomms connections:
/dev/tty.usbserial-DM01KLJO
##### Step 2/3 Identify Device Type of Connections. #####
Identifying serialcomms devices..
/dev/tty.usbserial-DM01KLJO is a cambrionix.
serialcomms device_type detection complete.
##### Step 3/3: Extract Persistent Info from Detected Devices. #####
Getting info from communication port /dev/tty.usbserial-DM01KLJO for cambrionix
cambrionix_detect checking device readiness: attempt 1 of 1
cambrionix_detect starting AuxiliaryDevice.check_device_ready
cambrionix_detect health check 1/2 succeeded: Check device connected.
cambrionix_detect health check 2/2 succeeded: Check clear flags.
cambrionix_detect AuxiliaryDevice.check_device_ready successful. It took 0s.
cambrionix_detect starting Cambrionix.get_detection_info
cambrionix_detect Cambrionix.get_detection_info successful. It took 0s.
##### Detection Summary #####
1 new devices detected:
cambrionix-kljo
Device Alias Type Model Connected
-------------------------- --------------- -------------------- -------------------- ----------
Other Devices Alias Type Model Available
-------------------------- --------------- -------------------- -------------------- ----------
cambrionix-kljo <undefined> cambrionix PP15S available
0 total Gazoo device(s) available.
```
Device names are created as `devicetype-1234`, where the device type is provided
by the device controller, and the digits are the last 4 digits of the device's
serial number.
Detection only detects *new* devices. It does not re-detect already known
devices.
* To delete a known device:
```
gdm delete device-1234
```
* To redetect a device:
```
gdm redetect device-1234
```
## Using the CLI
### Exploring device capabilities without a physical device
GDM comes equipped with auto-generated documentation. To access it, you do not
need a device.
To see all commands available through the Manager class, run:
```
gdm
```
To start exploring device documentation, run:
```
gdm man
```
It will list all supported devices and provide commands to run if you are
interested in exploring capabilities of a specific device.
To see what is supported by a device type:
```
gdm man device_type
```
For example:
```
gdm man raspberrypi
```
To explore a device method, property, or capability, issue:
```
gdm man device_type attribute_name
```
For example:
```
gdm man raspberrypi firmware_version
gdm man raspberrypi reboot
gdm man raspberrypi file_transfer
```
To explore a capability method or property, issue:
```
gdm man device_type capability_name method_or_property_name
```
For example:
```
gdm man cambrionix switch_power off
gdm man raspberrypi file_transfer send_file_to_device
```
You can also explore GDM functionality via the dynamic Fire CLI. For example:
```
gdm -- --help
gdm create_device -- --help
```
### Exploring device capabilities with a physical device
If you have a physical device, you can use the dynamic Fire CLI to get help
about any attribute of the device. There are no limitations to this
documentation, and it is more detailed and more accurate, but the drawback is
that it requires a physical device. For example, assuming a `raspberrypi-kljo`
is attached:
```
gdm issue raspberrypi-kljo -- --help
gdm issue raspberrypi-kljo - reboot -- --help
```
### Basic CLI usage
Let us assume you have a `raspberrypi-kljo` connected.
Here are a few commonly used CLI commands:
* list all known devices:
```
gdm devices
```
* detect new devices:
```
gdm detect
```
or
```
gdm detect --static_ips=10.20.30.40,50.60.70.80
```
Note: detection does not remove devices which are already known to GDM.
* set a device property (such as an alias):
```
gdm set-prop raspberrypi-kljo alias rpi
```
* check GDM version:
```
gdm -v
```
* run health checks on a device:
```
gdm health-check raspberrypi-kljo
```
if you set the alias above, the following will also work:
```
gdm health-check rpi
```
* run health checks, then issue a device command or retrieve a property:
```
gdm issue raspberrypi-kljo - reboot
```
* issue a device command or retrieve a property *without* running health
checks:
```
gdm exec raspberrypi-kljo - reboot
```
* use a device capability:
```
gdm issue raspberrypi-kljo - file_transfer - recv_file_from_device --src="/tmp/foo" --dest="/tmp/bar"
```
(or use `gdm exec` to skip health checks).
Sometimes passing the arguments to the Fire CLI gets a bit tricky. Refer to the
[Python Fire documentation](https://google.github.io/python-fire/guide/) and
definitely review the
[argument parsing section](https://google.github.io/python-fire/guide/#argument-parsing).
The most commonly used device method is `shell`. It runs a shell command on the
device. It is required for primary devices, but is optional for auxiliary
devices. The only auxiliary device included with GDM that implements `shell()`
is Raspberry Pi. If you have a Raspberry Pi connected, you can try it out:
```
gdm issue raspberrypi-1234 - shell "echo 'foo'"
```
## Using the gazoo_device python package
Launch Python from a virtual environment with gazoo_device installed. \
You can use the GDM CLI virtual environment:
`~/gazoo/gdm/virtual_env/bin/python`.
```
from gazoo_device import Manager
manager = Manager()
rpi = manager.create_device('raspberrypi-962c')
rpi.reboot()
```
Note that the device you are creating should be shown as "available" in the
output of `gdm devices`.
## How to use GDM with test frameworks
GDM is framework-agnostic and can be used with any Python test framework. \
See
[examples/device_tests/README.md](https://github.com/google/gazoo-device/blob/master/examples/device_tests/README.md)
for GDM + unittest and GDM + Mobly examples.
## Contributor documentation
If you are interested in adding support for your device(s) to GDM, refer to
[CONTRIBUTING.md](CONTRIBUTING.md).
## License
Gazoo Device Manager is licensed under the
[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) License.
### Dependency license compliance
Gazoo Device Manager contains a dependency on
[pyudev](https://pypi.org/project/pyudev/), which is licensed under
[LGPL 2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). \
`pyudev` source code can be found here: https://github.com/pyudev/pyudev.
## Disclaimer
This is not an official Google product.
Raw data
{
"_id": null,
"home_page": "https://github.com/google/gazoo-device",
"name": "gazoo-device",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Google LLC",
"author_email": "gdm-authors@google.com",
"download_url": "https://files.pythonhosted.org/packages/be/0c/7e3afb7eccd2455e017b7e9523374ddbf750cfbb404742385e2f435a586b/gazoo_device-1.123.0.tar.gz",
"platform": null,
"description": "# Gazoo Device Manager (GDM)\n\n`gazoo_device` is a python package for interacting with smart devices. \\\nIt contains Gazoo Device Manager (GDM), which defines a common device interface.\nThe common device interface standardizes device interactions and allows test\nwriters to share tests across devices despite the underlying differences in\ncommunication types, OSes, and logic. \\\nGDM is available as a Python package for use in tests and comes with its own CLI\nfor quick device interactions. \\\nGDM is the open-source architecture which enables device-agnostic interations.\nDevice controllers used by GDM are contained in separate Python packages and can\nbe registered with the GDM architecture. \\\nGDM runs on the test host and communicates with the physical devices via one or\nmore device transports (such as SSH, ADB, HTTPS, UART). GDM does not require any\nadditional support from the device firmware.\n\nGDM is used in most end-to-end device tests at Google Nest.\n\n## Table of contents\n\n1. [Install](#install)\n 1. [Uninstall](#uninstall)\n2. [Quick start](#quick-start)\n3. [Device controllers in GDM](#device-controllers-in-gdm)\n4. [Config files](#config-files)\n5. [Logs](#logs)\n6. [Detecting devices](#detecting-devices)\n7. [Using the CLI](#using-the-cli)\n 1. [Exploring device capabilities without a physical device](#exploring-device-capabilities-without-a-physical-device)\n 2. [Exploring device capabilities with a physical device](#exploring-device-capabilities-with-a-physical-device)\n 3. [Basic CLI usage](#basic-cli-usage)\n8. [Using the gazoo_device python package](#using-the-gazoo_device-python-package)\n9. [How to use GDM with test frameworks](#how-to-use-gdm-with-test-frameworks)\n 1. [GDM with Mobly](#gdm-with-mobly)\n 2. [GDM with Unittest](#gdm-with-unittest)\n10. [Contributor documentation](#contributor-documentation)\n11. [License](#license)\n12. [Disclaimer](#disclaimer)\n\n## Install\n\nSupported host operating systems:\n\n* Debian;\n* Ubuntu;\n* MacOS.\n\nWindows is not supported.\n\nNote: Raspberry Pi 4 on 64-bit Ubuntu 20.04 LTS is also supported as a host (see\nthe relevant [device setup section](docs/Raspberry_Pi_as_host.md)).\n\nMacOS prerequisites:\n\n1. Install Xcode Command Line Tools:\n\n ```shell\n xcode-select --install\n ```\n\n2. Install Brew (MacOS package manager):\n\n https://brew.sh/\n\n3. Verify your system `python3` executable.\n\n 1. Check that Python 3 is available:\n\n ```shell\n which python3\n ```\n\n 2. Check that your Python 3 version is at least 3.9:\n\n ```\n python3 -V\n ```\n\n 3. Check that your `python3` executable has `pip` module:\n\n ```\n python3 -m pip --version\n ```\n\nInstallation steps:\n\n1. Download the GDM installer archive:\n\n ```shell\n curl -OL https://github.com/google/gazoo-device/releases/latest/download/gdm-install.sh\n ```\n\n2. Run the installer:\n\n ```shell\n bash gdm-install.sh\n ```\n\n You should see the following message at the end of the installation:\n\n ```\n Install done (exit 0)\n ```\n\n3. Add `gdm` to your `$PATH`:\n\n Add the following line to `~/.bash_profile` or `~/.bashrc`:\n\n ```shell\n export PATH=\"${PATH}:${HOME}/gazoo/bin\"\n ```\n\n4. [Optional] Install optional dependencies\n\n 1.\n\n Some of GDM's dependencies are optional and are not installed by the\n installer automatically due to licensing restrictions.\n\n To enable flashing NRF52840 DK and EFR32 dev boards through GDM, install the\n J-Link SDK:\n https://www.segger.com/downloads/jlink/#J-LinkSoftwareAndDocumentationPack.\n\n Additional note to Apple M1 users:\n Make sure to download \"64-bit Apple M1 Installer\" under macOS.\n\n To determine whether your Mac is using an M1 chip, run\n ```\n arch\n ```\n in terminal. If you see ```arm64```, then your Mac is using M1.\n\n 2.\n\n To enable flashing ESP32 dev boards through GDM, install `esptool`:\n\n ```shell\n ~/gazoo/gdm/virtual_env/bin/pip install esptool==4.1\n ```\n\nGDM installation creates a virtual environment for the CLI at\n`~/gazoo/gdm/virtual_env`. \\\n`gdm` CLI commands run in this virtual environment.\n\nRun a few GDM CLI commands to verify GDM works:\n\n```shell\ngdm -v\ngdm devices\ngdm\n```\n\n`gdm -v` displays versions of the GDM launcher and of the python package:\n\n```\nGazoo Device Manager launcher 1.0\nGazoo Device Manager 1.0.0\n```\n\nTypical output of `gdm devices`:\n\n```\nDevice Alias Type Model Connected\n--------------- --------------- ----------- ---------------- ------------\n\nOther Devices Alias Type Model Available\n--------------- --------------- ----------- ---------------- ------------\n\n0 total Gazoo device(s) available.\n```\n\n`gdm` displays a help menu.\n\nTo update GDM to the latest version:\n\n```\ngdm update-gdm\n```\n\nTo update (or downgrade) GDM to a specific version:\n\n```\ngdm update-gdm <version> # Example: gdm update-gdm 1.0.0\n```\n\nTo install GDM in a virtual environment:\n\n```\n/path_to_virtual_env/bin/pip install gazoo-device\n```\n\n### Uninstall\n\nTo uninstall GDM:\n\n```\ncurl -OL https://github.com/google/gazoo-device/releases/latest/download/gdm-cleanup.sh\nbash gdm-cleanup.sh\n```\n\n## Quick start\n\nThis is the quickest way to get your hands dirty with GDM. You will need a\nRaspberry Pi.\n\n1. [Install GDM on the host](#install).\n2. [Set up your Raspberry Pi as an auxiliary device in GDM and try out the CLI](docs/device_setup/Raspberry_Pi_as_supporting_device.md).\n3. [Run the example on-device test with a test framework of your choice](https://github.com/google/gazoo-device/blob/master/examples/device_tests/README.md).\n\n## Device controllers in GDM\n\nTo interact with devices, GDM creates one Python device controller object for\neach physical device. The lifecycle of GDM device controllers is as follows:\n\n1. a new device is connected to the host and is detected by GDM (one-time setup\n step), which makes the device known to GDM:\n\n ```\n gdm detect\n ```\n\n2. a device controller instance is created at the beginning of a test or a CLI\n device interaction;\n\n3. one or more device commands are issued through the device controller\n instance;\n\n4. the device controller instance is closed when the test is finished or the\n CLI interaction completes;\n\n5. if the device is permanently disconnected from the host, it is removed from\n the list of devices known to GDM (also a one-time step) through\n\n ```\n gdm delete device-1234\n ```\n\nNote that the term \"device\" is ambiguous in the context of GDM: it can refer to\neither the device controller or the physical device. Device controllers can also\nbe referred to as device classes.\n\n## Config files\n\nGDM device configs are found in `~/gazoo/gdm/conf`.\n\nYou should not modify them directly. Instead, use `set-prop` and `get-prop`\ncommands:\n\n* To set an optional device property:\n\n ```\n gdm set-prop device-1234 property-name property-value\n ```\n\n* To retrieve a device property:\n\n ```\n gdm get-prop device-1234 property-name\n ```\n\n* To set a Manager property:\n\n ```\n gdm set-prop manager property-name property-value\n ```\n\n* To retrieve a Manager property:\n\n ```\n gdm get-prop manager property-name\n ```\n\n## Logs\n\nBy default all GDM logs go to `~/gazoo/gdm/log/`. Log verbosity, output\ndirectory, and standard output behavior can be configured via arguments to\n`Manager.__init__` (see [gazoo_device/manager.py](gazoo_device/manager.py)).\n\nGDM creates three types of log files.\n\n### The `gdm.txt` log\n\nAll GDM logs go here. Device logs are **not** captured in this file. This log\nfile persists across GDM invocations. It provides the best history, but it can\nbe difficult to pinpoint the logs for a particular device interaction.\n\n### Device log files, such as `linuxexample-1eb2-20201113-123538.txt`\n\nThese capture all communications between GDM and the device. Each log line is\nprefixed with `GDM-<letter_or_digit>`, such as `GDM-M`, `GDM-0`, or `GDM-1`.\n\n`GDM-M` are logs written by GDM. These include the commands that GDM wrote, the\nregular expressions GDM expects to find after writing a command and the maximum\ntime window for the response, and the result of the expect (which regular\nexpression matched, if any).\n\n`GDM-0`, `GDM-1`, and other `GDM-<digit>` logs come from device transports. The\ndigit corresponds to the index of the transport (as defined by\n`get_transport_list()` methods of communication types in\n[gazoo_device/switchboard/communication_types.py](gazoo_device/switchboard/communication_types.py)).\n\\\nFor some communication types, such as SSH and ADB, logs and command responses\ncome from different transports. In that case device responses come from `GDM-0`\nand device logs come from `GDM-1`. \\\nFor other communication types, there may only be a single transport, in which\ncase both device responses and logs come from `GDM-0`.\n\nThe names of device log files are logged during every CLI interaction. For\nexample: `linuxexample-1eb2 logging to file\n/Users/artorl/gdm/log/linuxexample-1eb2-20201113-123548.txt`\n\n### Device log event files, such as `linuxexample-1eb2-20201113-123548-events.txt`\n\nThese contain device log events. The log events to be captured are defined by\nlog event filters in [gazoo_device/filters/](gazoo_device/filters/).\n\nA log filtering process receives all device logs in real time and captures lines\nwhich match any of the device log filters into the device log event file.\n\nThe name of the log event file is constructed as\n`<name_of_log_file>-events.txt`. For example,\n`linuxexample-1eb2-20201113-123548-events.txt` is the log event file for the\n`linuxexample-1eb2-20201113-123548.txt` device log file.\n\n## Detecting devices\n\nTo detect all devices attached to your host, run `gdm detect` on the host. This\nis a one-time step that is required when GDM is installed on the host or when a\nnew device is connected to the host. Devices typically require a special setup\nbefore being usable with GDM. This can include a special cable connection\nconfiguration, renaming serial cables, updating device firmware to a specific\nversion, setting up the device on a static IP address, or setting up\npasswordless SSH access to the device. Refer to\n[docs/device_setup/](docs/device_setup/) for instructions.\n\nDevice detection populates device configs:\n\n* persistent properties are stored in `~/gazoo/gdm/conf/devices.json`;\n* optional (settable) properties are stored in\n `~/gazoo/gdm/conf/device_options.json`.\n\nTo view all devices currently known to GDM, run `gdm devices`.\n\nSample detection output (`cambrionix-kljo` was detected):\n\n```\n$ gdm detect\n\n##### Step 1/3: Detecting potential new communication addresses. #####\n\n detecting potential AdbComms communication addresses\n detecting potential DockerComms communication addresses\n'docker' is not installed. Cannot get Docker devices.\n detecting potential JlinkSerialComms communication addresses\n detecting potential PtyProcessComms communication addresses\n detecting potential SshComms communication addresses\n detecting potential SerialComms communication addresses\n detecting potential YepkitComms communication addresses\n'ykushcmd' is not installed. Cannot get Yepkit serials.\n detecting potential PigweedSerialComms communication addresses\nFound 1 possible serialcomms connections:\n /dev/tty.usbserial-DM01KLJO\n\n##### Step 2/3 Identify Device Type of Connections. #####\n\nIdentifying serialcomms devices..\n /dev/tty.usbserial-DM01KLJO is a cambrionix.\n serialcomms device_type detection complete.\n\n##### Step 3/3: Extract Persistent Info from Detected Devices. #####\n\nGetting info from communication port /dev/tty.usbserial-DM01KLJO for cambrionix\n cambrionix_detect checking device readiness: attempt 1 of 1\n cambrionix_detect starting AuxiliaryDevice.check_device_ready\n cambrionix_detect health check 1/2 succeeded: Check device connected.\n cambrionix_detect health check 2/2 succeeded: Check clear flags.\n cambrionix_detect AuxiliaryDevice.check_device_ready successful. It took 0s.\n cambrionix_detect starting Cambrionix.get_detection_info\n cambrionix_detect Cambrionix.get_detection_info successful. It took 0s.\n\n##### Detection Summary #####\n\n 1 new devices detected:\n cambrionix-kljo\nDevice Alias Type Model Connected\n-------------------------- --------------- -------------------- -------------------- ----------\n\nOther Devices Alias Type Model Available\n-------------------------- --------------- -------------------- -------------------- ----------\ncambrionix-kljo <undefined> cambrionix PP15S available\n\n0 total Gazoo device(s) available.\n```\n\nDevice names are created as `devicetype-1234`, where the device type is provided\nby the device controller, and the digits are the last 4 digits of the device's\nserial number.\n\nDetection only detects *new* devices. It does not re-detect already known\ndevices.\n\n* To delete a known device:\n\n ```\n gdm delete device-1234\n ```\n\n* To redetect a device:\n\n ```\n gdm redetect device-1234\n ```\n\n## Using the CLI\n\n### Exploring device capabilities without a physical device\n\nGDM comes equipped with auto-generated documentation. To access it, you do not\nneed a device.\n\nTo see all commands available through the Manager class, run:\n\n```\ngdm\n```\n\nTo start exploring device documentation, run:\n\n```\ngdm man\n```\n\nIt will list all supported devices and provide commands to run if you are\ninterested in exploring capabilities of a specific device.\n\nTo see what is supported by a device type:\n\n```\ngdm man device_type\n```\n\nFor example:\n\n```\ngdm man raspberrypi\n```\n\nTo explore a device method, property, or capability, issue:\n\n```\ngdm man device_type attribute_name\n```\n\nFor example:\n\n```\ngdm man raspberrypi firmware_version\ngdm man raspberrypi reboot\ngdm man raspberrypi file_transfer\n```\n\nTo explore a capability method or property, issue:\n\n```\ngdm man device_type capability_name method_or_property_name\n```\n\nFor example:\n\n```\ngdm man cambrionix switch_power off\ngdm man raspberrypi file_transfer send_file_to_device\n```\n\nYou can also explore GDM functionality via the dynamic Fire CLI. For example:\n\n```\ngdm -- --help\ngdm create_device -- --help\n```\n\n### Exploring device capabilities with a physical device\n\nIf you have a physical device, you can use the dynamic Fire CLI to get help\nabout any attribute of the device. There are no limitations to this\ndocumentation, and it is more detailed and more accurate, but the drawback is\nthat it requires a physical device. For example, assuming a `raspberrypi-kljo`\nis attached:\n\n```\ngdm issue raspberrypi-kljo -- --help\ngdm issue raspberrypi-kljo - reboot -- --help\n```\n\n### Basic CLI usage\n\nLet us assume you have a `raspberrypi-kljo` connected.\n\nHere are a few commonly used CLI commands:\n\n* list all known devices:\n\n ```\n gdm devices\n ```\n\n* detect new devices:\n\n ```\n gdm detect\n ```\n\n or\n\n ```\n gdm detect --static_ips=10.20.30.40,50.60.70.80\n ```\n\n Note: detection does not remove devices which are already known to GDM.\n\n* set a device property (such as an alias):\n\n ```\n gdm set-prop raspberrypi-kljo alias rpi\n ```\n\n* check GDM version:\n\n ```\n gdm -v\n ```\n\n* run health checks on a device:\n\n ```\n gdm health-check raspberrypi-kljo\n ```\n\n if you set the alias above, the following will also work:\n\n ```\n gdm health-check rpi\n ```\n\n* run health checks, then issue a device command or retrieve a property:\n\n ```\n gdm issue raspberrypi-kljo - reboot\n ```\n\n* issue a device command or retrieve a property *without* running health\n checks:\n\n ```\n gdm exec raspberrypi-kljo - reboot\n ```\n\n* use a device capability:\n\n ```\n gdm issue raspberrypi-kljo - file_transfer - recv_file_from_device --src=\"/tmp/foo\" --dest=\"/tmp/bar\"\n ```\n\n (or use `gdm exec` to skip health checks).\n\nSometimes passing the arguments to the Fire CLI gets a bit tricky. Refer to the\n[Python Fire documentation](https://google.github.io/python-fire/guide/) and\ndefinitely review the\n[argument parsing section](https://google.github.io/python-fire/guide/#argument-parsing).\n\nThe most commonly used device method is `shell`. It runs a shell command on the\ndevice. It is required for primary devices, but is optional for auxiliary\ndevices. The only auxiliary device included with GDM that implements `shell()`\nis Raspberry Pi. If you have a Raspberry Pi connected, you can try it out:\n\n```\ngdm issue raspberrypi-1234 - shell \"echo 'foo'\"\n```\n\n## Using the gazoo_device python package\n\nLaunch Python from a virtual environment with gazoo_device installed. \\\nYou can use the GDM CLI virtual environment:\n`~/gazoo/gdm/virtual_env/bin/python`.\n\n```\nfrom gazoo_device import Manager\nmanager = Manager()\nrpi = manager.create_device('raspberrypi-962c')\nrpi.reboot()\n```\n\nNote that the device you are creating should be shown as \"available\" in the\noutput of `gdm devices`.\n\n## How to use GDM with test frameworks\n\nGDM is framework-agnostic and can be used with any Python test framework. \\\nSee\n[examples/device_tests/README.md](https://github.com/google/gazoo-device/blob/master/examples/device_tests/README.md)\nfor GDM + unittest and GDM + Mobly examples.\n\n## Contributor documentation\n\nIf you are interested in adding support for your device(s) to GDM, refer to\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nGazoo Device Manager is licensed under the\n[Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) License.\n\n### Dependency license compliance\n\nGazoo Device Manager contains a dependency on\n[pyudev](https://pypi.org/project/pyudev/), which is licensed under\n[LGPL 2.1](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.html). \\\n`pyudev` source code can be found here: https://github.com/pyudev/pyudev.\n\n## Disclaimer\n\nThis is not an official Google product.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Gazoo Device Manager",
"version": "1.123.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ac920e9ac19490c01af580093095712458f6d574ba49205f0fdef8079f51bb24",
"md5": "c71820db5bda210c357a8c8a63e2a779",
"sha256": "05342d80f7dab757cdc9b549daa08e36966d88d1f48df945628cc5c8bb3b2b97"
},
"downloads": -1,
"filename": "gazoo_device-1.123.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c71820db5bda210c357a8c8a63e2a779",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 634004,
"upload_time": "2023-03-22T22:43:14",
"upload_time_iso_8601": "2023-03-22T22:43:14.963787Z",
"url": "https://files.pythonhosted.org/packages/ac/92/0e9ac19490c01af580093095712458f6d574ba49205f0fdef8079f51bb24/gazoo_device-1.123.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "be0c7e3afb7eccd2455e017b7e9523374ddbf750cfbb404742385e2f435a586b",
"md5": "6a1b62eeba1cad335ac9f7e33993854f",
"sha256": "c40d23024fc696aec5212c4203668da4802fe37e703e4a5a3afe2d5848532b3d"
},
"downloads": -1,
"filename": "gazoo_device-1.123.0.tar.gz",
"has_sig": false,
"md5_digest": "6a1b62eeba1cad335ac9f7e33993854f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 381971,
"upload_time": "2023-03-22T22:43:18",
"upload_time_iso_8601": "2023-03-22T22:43:18.694287Z",
"url": "https://files.pythonhosted.org/packages/be/0c/7e3afb7eccd2455e017b7e9523374ddbf750cfbb404742385e2f435a586b/gazoo_device-1.123.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-22 22:43:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "google",
"github_project": "gazoo-device",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "gazoo-device"
}
JSON
