Viam Python SDK

(In)stability Notice

Warning This is an beta release of the Viam Python SDK. Stability is not guaranteed. Breaking changes are likely to occur, and occur often.

Installation

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

pip install viam-sdk

If your system is not supported, read further on how to install from source.

Upgrading

Note Because the SDK is under active development, we suggest that you upgrade the package frequently.

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 SDK that contains the necessary protocols. Therefore, to build from source, you will need both the Rust SDK and the Rust compiler.

1. Download/clone this repository
2. Download/clone the Rust SDK
3. Install Rust if not already available
4. From the viam-rust-sdk directory, run cargo build
   • You can optionally provide the --release flag: cargo build --release
5. Find the compiled library in viam-rust-sdk/target/debug/libviam.*
   • If you provided the --release flag, the enclosing directory will be release: viam-rust-sdk/target/release/libviam.*
   • The extension of the executable will depend on your operating system. For example, on macOS it will be libviam.dylib, whereas on Linux it will be libviam.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 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)
   • 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 issues 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 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.

Note Connecting to the viam-server can be done using either WebRTC (default) or direct connection. Currently, connecting over WebRTC is guaranteed on the local network. WebRTC for remote connections, however, is not guaranteed and may fail indeterminately.

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.

The do method

Every component provided by the SDK includes a generic do method which is useful to execute commands that are not already defined on the component.

async def do(self, command: Dict[str, Any]) -> Dict[str, Any]

If this is not generic enough, you can also create your own custom component by subclassing the viam.components.generic.Generic component class. For more details, you can view the documentation for the Generic component.

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 component types

The SDK provides a number of abstract base components. To add more abstract base components, follow these steps:

1. Create a new directory in viam.components with the name of the new component
2. Create 3 new files in the newly created directory:
   1. Add all imports for the package in __init__.py
   2. Define all requirements of the component in {COMPONENT}.py
   3. Implement the gRPC service for the new component in service.py
3. Add the new service to viam.rpc.server to expose the gRPC service
4. If the component needs to be included in the robot/status service, add it in viam.robot.service
5. Write tests for the new component and add the component to tests.mocks.components
6. Add the component to examples.server.v1.components and its corresponding concrete type in examples.server.v1.server

License

Copyright 2021-2022 Viam Inc.

Apache 2.0 - See LICENSE file