Package: viam-sdk
Viam Python SDKThe 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 ourSetupguide.If you would like to develop and contribute to Viam's Python SDK, take a look at theDevelopmentportion of the README.InstallationCurrently, we have pre-built binaries for macOS (both Intelx86_64and Apple Silicon) and Linux (x86,aarch64,armv6l) that you can install usingpip:pip install viam-sdkIf you intend to use theMLModelservice, 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 theML (machine learning) model servicedocumentation for more information.Windows is not supported. If you are using Windows, installviam-sdkin WSL. For other unsupported systems, read further on how to install from source.UpgradingTo upgrade, simply run thepip installcommand with the-Uoption:pip install -U viam-sdkInstalling from SourceThe 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 arust-utils repothat contains the necessary protocols. Therefore, to build from source, you will need both the Rust utils and the Rust compiler.Download/clone thisrepositoryDownload/clone therust-utilsInstall Rustif not already availableFrom therust-utilsdirectory, runcargo buildYou can optionally provide the--releaseflag:cargo build --releaseFind the compiled library inrust-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 belibviam_rust_utils.dylib, whereas on Linux it will belibviam_rust_utils.soCopy the compiled library to the directoryviam-python-sdk/src/viam/rpc/From theviam-python-sdkdirectory, runpoetry buildto create an installable packageFind the newly created installable package located inviam-python-sdk/dist/and pip install it directly, e.g.:pip install viam-python-sdk/dist/viam_sdk-0.1.0-py3-none-any.whlIf 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 thereleasespage of the rust-utils library.If you doNOTneed communication over WebRTC (and thus, do not need the native library), the steps are:Download/clone this repositoryRunpoetry buildfrom theviam-python-sdkdirectoryFind the newly created installable package located inviam-python-sdk/dist/and pip install it directly, e.g.:pip install viam-python-sdk/dist/viam_sdk-0.1.0-py3-none-any.whlEnsure that every connection has the optiondisable_webrtcset toTrue:viam.rpc.dial.DialOptions(disable_webrtc=True)For more information about connecting to a robot, see thedocumentationandexample usageConfigure a client application atapp.viam.comYour client application does not directly interact with your hardware. Instead, your client application makes calls to theviam-serverwhich can then issue commands to your hardware or read from sensors.To create a client application, to navigate toapp.viam.com. After you log in, perform these steps:Create a location (for examplehome)Create a robot (for examplearduino)Follow the steps on the setup tab:Setup Viam App Config on Single Board Computer (SBC)Download and Install Viam ServerWait until the robot shows as connected. If this doesn't happen try restarting the viam-server:sudo systemctl restart viam-serverNext, select theCODE SAMPLEtab in the Viam Web UI, and copy the boilerplate code from the section labeledPython 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, theviam-serverinstance on your robot is alive, and the computer running the program is able to connect to that instance.TheRobotClient& connectivityThe main entry point for using the SDK as a client is theRobotClientclass. This class can manage resources, operations, frames, etc., for the robot. It can also manage connectivity and behavior around sessions and reconnection through theRobotClient.Optionsnested class.TheRobotClientwill attempt to refresh its resources at a set interval (customizable viaOptions).In the event that connection is lost to the robot, theRobotClientwill 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 areNOTterminated and can possibly error with aGRPCErrorwhose status isDEADLINE_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 externalviam Rust utilslibrary. WebRTC settings can be changed using the appropriate attributes inviam.rpc.dial.DialOptions. These options can be passed to theRobotClientthroughRobotClient.Options.dial_options.SessionsSessions 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 settingRobotClient.Options.disable_sessions = True. Please see theRDK session documentationfor more details and server-side configuration options.ExamplesRead theExample Usagepage, 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 theexamplesdirectory.DocumentationDocumentation, like this entire project, is under active development, and can be found atpython.viam.dev.DevelopmentTo contribute to the python SDK, please see thecontribution guidelines.Adding new resource typesThe SDK provides a number of abstract base components and services (collectively: resources). To add more abstract resources, follow these steps:Create a new directory inviam.componentsorviam.serviceswith the name of the new componentCreate 4 new files in the newly created directory:Define all requirements of the resource in{RESOURCE_NAME}.pyImplement the gRPC service for the new resource inservice.pyCreate a gRPC client for the new resource inclient.pyRegister the subtype and define package exports in__init__.pyWrite tests for the new resource and add the resource totests.mocks.{components|services}If the resource is a component, add the component toexamples.server.v1.componentsand its corresponding concrete type inexamples.server.v1.serverLicenseCopyright 2021-2023 Viam Inc.Apache 2.0 - SeeLICENSEfile