Viam Python SDK
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 x86_64 and Apple Silicon) and Linux (x86, aarch64, armv6l) that you can install using pip:
pip install viam-sdk
If you want to install on Windows, you can install from github directly with pip:
pip install git+https://github.com/viamrobotics/viam-python-sdk.git
Note that only direct gRPC connections are supported on Windows; you will need to disable webrtc or else connection will fail. Full support (including webRTC) does exist on WSL.
If you intend to use the MLModel service, use the following command instead, which installs additional required dependencies:
pip install 'viam-sdk[mlmodel]'
You can also run this command on an existing Python SDK install to add support for the ML model service. See the ML (machine learning) model service documentation for more information.
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.
- Download/clone this repository
- Download/clone the rust-utils
- Install Rust if not already available
- From the
rust-utilsdirectory, runcargo build- You can optionally provide the
--releaseflag:cargo build --release
- You can optionally provide the
- Find the compiled library in
rust-utils/target/debug/libviam_rust_utils.*- If you provided the
--releaseflag, the enclosing directory will berelease: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 belibviam_rust_utils.so
- If you provided the
- Copy the compiled library to the directory
viam-python-sdk/src/viam/rpc/ - From the
viam-python-sdkdirectory, runuv build --wheelto create an installable package - Find the newly created installable package located in
viam-python-sdk/dist/and pip install it directly, for example: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:
- Download/clone this repository
- Run
uv build --wheelfrom theviam-python-sdkdirectory - Find the newly created installable package located in
viam-python-sdk/dist/and pip install it directly, for example:pip install viam-python-sdk/dist/viam_sdk-0.1.0-py3-none-any.whl - Ensure that every connection has the option
disable_webrtcset toTrue:viam.rpc.dial.DialOptions(disable_webrtc=True)- For more information about connecting to a robot, see the documentation and example usage
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:
- Create a location (for example
home) - Create a robot (for example
arduino) - Follow the steps on the setup tab:
-
Setup machine cloud credentials on Single Board Computer (SBC)
-
Download and Install Viam Server
-
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 CONNECT 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:
- Create a new directory in
viam.componentsorviam.serviceswith the name of the new component - Create 4 new files in the newly created directory:
- Define all requirements of the resource in
{RESOURCE_NAME}.py - Implement the gRPC service for the new resource in
service.py - Create a gRPC client for the new resource in
client.py - Register the API and define package exports in
__init__.py
- Define all requirements of the resource in
- Write tests for the new resource and add the resource to
tests.mocks.{components|services} - If the resource is a component, add the component to
examples.server.v1.componentsand its corresponding concrete type inexamples.server.v1.server
License
Copyright 2021-2024 Viam Inc.
Apache 2.0 - See LICENSE file
Release files for viam-sdk 0.82.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 82.5 MB
Release files / viam_sdk-0.82.0-py3-none-win_amd64.whl
| Download URL | viam_sdk-0.82.0-py3-none-win_amd64.whl |
|---|---|
| Size | 6.7 MB |
| Tags | Python 3 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
88be9ecaab362624b02783e36374b24b61a883aa43f4e60b7ec5ec53597ab930
|
|
BLAKE2b-256 checksum How to use checksums |
356ea5c73487c9496afe33447015369f1e5f4e444e70a780009d61ed1ff0f7dc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-musllinux_1_2_x86_64.whl
| Download URL | viam_sdk-0.82.0-py3-none-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Linux musl 1.2+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
743cb1d9fcfcc0d7683b734c3773cf07fe1a793b2f9f60fb2311cd0c2f6f96e6
|
|
BLAKE2b-256 checksum How to use checksums |
5cc281268a8b7cafafcb211dd3c916666501ee70ddf00e87ce562521836e2119
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-musllinux_1_2_i686.whl
| Download URL | viam_sdk-0.82.0-py3-none-musllinux_1_2_i686.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Linux musl 1.2+ x86-32 Python 3 |
|
SHA-256 checksum How to use checksums |
108de79251a57a1175667d2b595efcb8fe1747dc430bbb17dd9042054ab8cdad
|
|
BLAKE2b-256 checksum How to use checksums |
f11080caa840f2b5f3ecd51d2118a20fb31f1fcf50186716f2cf219e052a43c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-musllinux_1_2_armv7l.whl
| Download URL | viam_sdk-0.82.0-py3-none-musllinux_1_2_armv7l.whl |
|---|---|
| Size | 7.6 MB |
| Tags | Linux musl 1.2+ ARMv7l Python 3 |
|
SHA-256 checksum How to use checksums |
0b056f188ebe6cc8f4e6d93a6ae5fcc827eeed252a30e20df161e1c976d39478
|
|
BLAKE2b-256 checksum How to use checksums |
31642d805b3f91e6834c1ffc2bdb1f79df4c370d93ba2eb5353789f92e182abe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-musllinux_1_2_aarch64.whl
| Download URL | viam_sdk-0.82.0-py3-none-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Linux musl 1.2+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
5fcb1a9b5e743b921ea07ad91e11f49973f642c73b2f286d06b4e181175d3261
|
|
BLAKE2b-256 checksum How to use checksums |
903c7d671ad07fe3ea0da5cf9df12eab377f70717483fff1192361947f262750
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-manylinux2014_x86_64.whl
| Download URL | viam_sdk-0.82.0-py3-none-manylinux2014_x86_64.whl |
|---|---|
| Size | 7.6 MB |
| Tags | Linux glibc 2.17+ x86-64 Python 3 |
|
SHA-256 checksum How to use checksums |
079f4e16e86a0f61b691092454a3e4695078ce7674c5d651a164ccd12c05d06d
|
|
BLAKE2b-256 checksum How to use checksums |
a083dbfa37adc58ce54f0f4844497c91c66b741e64ea5fd11c026ca5f48151ea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-manylinux2014_aarch64.whl
| Download URL | viam_sdk-0.82.0-py3-none-manylinux2014_aarch64.whl |
|---|---|
| Size | 7.9 MB |
| Tags | Linux glibc 2.17+ ARM64 Python 3 |
|
SHA-256 checksum How to use checksums |
3653621c1b7730af7f6683282a26291bb6c8dec473d5c8ceeba6b5545ee29984
|
|
BLAKE2b-256 checksum How to use checksums |
67866393a527b73ccd2bbc1cc4d79107b13bcee49c09370d95d17d3b982edaa0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-macosx_11_0_arm64.whl
| Download URL | viam_sdk-0.82.0-py3-none-macosx_11_0_arm64.whl |
|---|---|
| Size | 6.9 MB |
| Tags | Python 3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
82618b0d12a72be1f3b3229846fac7e537a10face055b287448e5e0e5822222b
|
|
BLAKE2b-256 checksum How to use checksums |
cc0ef2cd75f14ae9b2744d47367147f6e14100225252384a8c7a30ed2cc78603
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-macosx_10_16_x86_64.whl
| Download URL | viam_sdk-0.82.0-py3-none-macosx_10_16_x86_64.whl |
|---|---|
| Size | 7.0 MB |
| Tags | Python 3 macOS 10.16+ x86-64 |
|
SHA-256 checksum How to use checksums |
334acd24fe8650c084d4d3281910b4b0ca29b0f828f7990e20b77d3c24ad30d7
|
|
BLAKE2b-256 checksum How to use checksums |
38604a8f841a322c8e47753032165a567b45a1e72e67b154d7649286c0a7fea0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-linux_armv7l.whl
| Download URL | viam_sdk-0.82.0-py3-none-linux_armv7l.whl |
|---|---|
| Size | 7.7 MB |
| Tags | Python 3 linux armv7l |
|
SHA-256 checksum How to use checksums |
d22a0e8d16e352b04a9a58a149a2b2100c846639084799ba10fde3058d41fae4
|
|
BLAKE2b-256 checksum How to use checksums |
135b0726bbe530e43ec03876a4455881fbaccb5ebd1de9290bc29e1a4ca92344
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / viam_sdk-0.82.0-py3-none-linux_armv6l.whl
| Download URL | viam_sdk-0.82.0-py3-none-linux_armv6l.whl |
|---|---|
| Size | 7.7 MB |
| Tags | Python 3 linux armv6l |
|
SHA-256 checksum How to use checksums |
601a68e6ba54cfb8d208b4567be6fefeb2698ffe0e65a5fdfc6dfd60f99fbcfa
|
|
BLAKE2b-256 checksum How to use checksums |
5e5bf753db336ea02e3e14e8d1a5b1c4955040006c439ef1f00659c2c57712ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
