Skip to main content

Viam Robotics Python SDK

Project description

Viam Python SDK

PyPI PyPI - Python Version documentation build status license

The Viam Python SDK allows you to build robots, access existing Viam robots, and manage your fleet of Viam robots.

If you would like a blueprint on setting up a Python environment with Viam from scratch, you can follow our Setup guide.

If you would like to develop and contribute to Viam's Python SDK, take a look at the Development portion of the README.

Installation

Currently, we have pre-built binaries for macOS (both Intel and Apple Silicon), along with Linux (x86, aarch64, armv6l) that you can install via pip

pip install viam-sdk

Windows is not supported. If you are using Windows, install viam-sdk in WSL. For other unsupported systems, read further on how to install from source.

Upgrading

To upgrade, simply run the pip install command with the -U option: pip install -U viam-sdk

Installing from Source

The Viam Python SDK uses native libraries to support communication over WebRTC, which will allow you to connect to robots that are not on the same network. In order to facilitate that communication, there is a rust-utils repo that contains the necessary protocols. Therefore, to build from source, you will need both the Rust utils and the Rust compiler.

  1. Download/clone this repository
  2. Download/clone the rust-utils
  3. Install Rust if not already available
  4. From the rust-utils directory, run cargo build
    • You can optionally provide the --release flag: cargo build --release
  5. Find the compiled library in rust-utils/target/debug/libviam_rust_utils.*
    • If you provided the --release flag, the enclosing directory will be release: rust-utils/target/release/libviam_rust_utils.*
    • The extension of the executable will depend on your operating system. For example, on macOS it will be libviam_rust_utils.dylib, whereas on Linux it will be libviam_rust_utils.so
  6. Copy the compiled library to the directory viam-python-sdk/src/viam/rpc/
  7. From the viam-python-sdk directory, run poetry build to create an installable package
  8. Find the newly created installable package located in viam-python-sdk/dist/ and pip install it directly, e.g.: pip install viam-python-sdk/dist/viam_sdk-0.1.0-py3-none-any.whl

If you have a macOS or Linux based operating system and do not want to build rust-utils manually, you can also look for the executable in the releases page of the rust-utils library.

If you do NOT need communication over WebRTC (and thus, do not need the native library), the steps are:

  1. Download/clone this repository
  2. Run poetry build from the viam-python-sdk directory
  3. Find the newly created installable package located in viam-python-sdk/dist/ and pip install it directly, e.g.: pip install viam-python-sdk/dist/viam_sdk-0.1.0-py3-none-any.whl
  4. Ensure that every connection has the option disable_webrtc set to True: viam.rpc.dial.DialOptions(disable_webrtc=True)

Configure a client application at app.viam.com

Your client application does not directly interact with your hardware. Instead, your client application makes calls to the viam-server which can then issue commands to your hardware or read from sensors.

To create a client application, to navigate to app.viam.com. After you log in, perform these steps:

  1. Create a location (for example home)
  2. Create a robot (for example arduino)
  3. Follow the steps on the setup tab:
    1. Setup Viam App Config on Single Board Computer (SBC)
    2. Download and Install Viam Server
    3. Wait until the robot shows as connected. If this doesn't happen try restarting the viam-server:
      sudo systemctl restart viam-server
      

Next, select the CODE SAMPLE tab in the Viam Web UI, and copy the boilerplate code from the section labeled Python SDK.

To ensure the installation succeeded and the systems are functional, save and run this simple program. If the program runs successfully, the python-sdk is properly installed, the viam-server instance on your robot is alive, and the computer running the program is able to connect to that instance.

The RobotClient & connectivity

The main entry point for using the SDK as a client is the RobotClient class. This class can manage resources, operations, frames, etc., for the robot. It can also manage connectivity and behavior around sessions and reconnection through the RobotClient.Options nested class.

The RobotClient will attempt to refresh its resources at a set interval (customizable via Options).

In the event that connection is lost to the robot, the RobotClient will attempt to reconnect at a set interval. There are two options available for customizing this behavior: how often the client checks the connection status (RobotClient.Options.check_connection_interval), and how often the client attempts to reconnect upon detecting a loss of connection (RobotClient.Options.attempt_reconnect_interval).

Upon a loss of connection, outstanding requests are NOT terminated and can possibly error with a GRPCError whose status is DEADLINE_EXCEEDED. When connection is restored, existing built-in clients will automatically receive the new connection - no need to re-obtain the client. Tasks initiated by Viam will automatically resume, but any user-defined tasks that depend on the connection should be checked and potentially restarted.

The Viam Python SDK utilizes gRPC and, optionally WebRTC (defaults to on). gRPC is provided purely in python, but WebRTC is provided by the external viam Rust utils library. WebRTC settings can be changed using the appropriate attributes in viam.rpc.dial.DialOptions. These options can be passed to the RobotClient through RobotClient.Options.dial_options.

Sessions

Sessions are a safety feature that automatically cancel operations made by the python client if it loses connection to a robot. Sessions are enabled by default but can be disabled by setting RobotClient.Options.disable_sessions = True. Please see the RDK session documentation for more details and server-side configuration options.

Examples

Read the Example Usage page, to learn how to access a component, build a custom component, and expose custom components as a remote to existing robots.

More examples can be found in the examples directory.

Documentation

Documentation, like this entire project, is under active development, and can be found at python.viam.dev.


Development

To contribute to the python SDK, please see the contribution guidelines.

Adding new resource types

The SDK provides a number of abstract base components and services (collectively: resources). To add more abstract resources, follow these steps:

  1. Create a new directory in viam.components or viam.services with the name of the new component
  2. Create 4 new files in the newly created directory:
    1. Define all requirements of the resource in {RESOURCE_NAME}.py
    2. Implement the gRPC service for the new resource in service.py
    3. Create a gRPC client for the new resource in client.py
    4. Register the subtype and define package exports in __init__.py
  3. Write tests for the new resource and add the resource to tests.mocks.{components|services}
  4. If the resource is a component, add the component to examples.server.v1.components and its corresponding concrete type in examples.server.v1.server

License

Copyright 2021-2023 Viam Inc.

Apache 2.0 - See LICENSE file

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

viam_sdk-0.10.0-py3-none-manylinux2014_x86_64.whl (10.1 MB view details)

Uploaded Python 3

viam_sdk-0.10.0-py3-none-macosx_11_0_arm64.whl (7.6 MB view details)

Uploaded Python 3 macOS 11.0+ ARM64

viam_sdk-0.10.0-py3-none-macosx_10_16_x86_64.whl (7.7 MB view details)

Uploaded Python 3 macOS 10.16+ x86-64

viam_sdk-0.10.0-py3-none-linux_armv6l.whl (9.8 MB view details)

Uploaded Python 3

File details

Details for the file viam_sdk-0.10.0-py3-none-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for viam_sdk-0.10.0-py3-none-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 96287ad2e989d2bcede8e28302c9276b8aa48e8062249c9eafa2eba38d22d3c9
MD5 3b7722fd8b56d5d373e0ce1f67e7967f
BLAKE2b-256 9bb118cbe8f6851594d26c090b31e5f6dceb2f1e3b662bc0134454ce67ef0e70

See more details on using hashes here.

Provenance

File details

Details for the file viam_sdk-0.10.0-py3-none-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for viam_sdk-0.10.0-py3-none-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8b29f30f15340191f9f38ca585f2cd3dcc60963ea07b980105a3b0611a78f7c4
MD5 c4c7e7013824e9bc7b6d599edae24586
BLAKE2b-256 7cfbc70e3a8126cc98705b5345a9e120fdae2d0f7b0156af641503f3a5e045aa

See more details on using hashes here.

Provenance

File details

Details for the file viam_sdk-0.10.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for viam_sdk-0.10.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2453350f6b912c55c929596d730ff79cc0d0168e74414f4686b72dfc236493a2
MD5 64127eb0808b052cdd27196d4a386435
BLAKE2b-256 2008549256d1c5437719765b2f85e7e069f1f127fea605285a68847a7b7fef0b

See more details on using hashes here.

Provenance

File details

Details for the file viam_sdk-0.10.0-py3-none-macosx_10_16_x86_64.whl.

File metadata

File hashes

Hashes for viam_sdk-0.10.0-py3-none-macosx_10_16_x86_64.whl
Algorithm Hash digest
SHA256 d02404663db1c5d3c5635f13417460319eb9e5a6bb6f62747e3338819c130489
MD5 3827815dbbb07b5dac365fb1c828087a
BLAKE2b-256 ee5c960aa6df407b926738ad955a84fc54cf57175a0e339ec9ccc5f24735fe1c

See more details on using hashes here.

Provenance

File details

Details for the file viam_sdk-0.10.0-py3-none-linux_armv6l.whl.

File metadata

File hashes

Hashes for viam_sdk-0.10.0-py3-none-linux_armv6l.whl
Algorithm Hash digest
SHA256 3bc862ea8ee728dae286a3b11e9354351702c16572c88f1b2e12033ebdb1d835
MD5 f65a0cde49ad65068de038554e7e5a3a
BLAKE2b-256 732a5fb6390286872ee421b3e75308ee85d64b5ae0608f4aa5d2b159c4f64fb0

See more details on using hashes here.

Provenance

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page