Metadata-Version: 2.1
Name: viam-sdk
Version: 0.4.0rc1
Summary: Viam Robotics Python SDK
License: Apache-2.0
Author: Naveed
Author-email: naveed@viam.com
Requires-Python: >=3.8.1,<3.12
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: Pillow (>=9.5.0,<10.0.0)
Requires-Dist: googleapis-common-protos (>=1.59.0,<2.0.0)
Requires-Dist: grpclib (>=0.4.4,<0.5.0)
Requires-Dist: protobuf (>=4.23.1,<5.0.0)
Requires-Dist: typing-extensions (>=4.6.1,<5.0.0)
Description-Content-Type: text/markdown

# Viam Python SDK
![PyPI](https://img.shields.io/pypi/v/viam-sdk)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/viam-sdk)
[![documentation](https://img.shields.io/static/v1?label=docs&message=python.viam.dev&color=lightgray)](https://python.viam.dev)
![build status](https://github.com/viamrobotics/python-sdk/actions/workflows/test.yml/badge.svg)
[![license](https://img.shields.io/badge/license-Apache_2.0-blue)](https://github.com/viamrobotics/viam-python-sdk/blob/main/LICENSE)

## 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`

If your system is not supported, 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](https://github.com/viamrobotics/rust-utils) 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](https://github.com/viamrobotics/viam-python-sdk)
1. Download/clone the [Rust utils](https://github.com/viamrobotics/rust-utils)
1. [Install Rust](https://www.rust-lang.org/tools/install) if not already available
1. From the `rust-utils` directory, run `cargo build`
    * You can optionally provide the `--release` flag: `cargo build --release`
1. 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`
1. Copy the compiled library to the directory `viam-python-sdk/src/viam/rpc/`
1. From the `viam-python-sdk` directory, run `poetry build` to create an installable package
1. 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
1. Run `poetry build` from the `viam-python-sdk` directory
1. 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`
1. 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](https://python.viam.dev) and [example usage](https://python.viam.dev/examples/example.html)

## Configure a client application at [app.viam.com](https://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](https://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](https://github.com/viamrobotics/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`.


## Examples
Read the [Example Usage](https://python.viam.dev/examples/example.html) 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`](/examples) directory.

## Documentation
Documentation, like this entire project, is under active development, and can be found at [python.viam.dev](https://python.viam.dev).

---
## Development
To contribute to the python SDK, please see the [contribution guidelines](https://python.viam.dev/contributing.html).

### 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
1. Create 4 new files in the newly created directory:
    1. Define all requirements of the resource in `{RESOURCE_NAME}.py`
    1. Implement the gRPC service for the new resource in `service.py`
    1. Create a gRPC client for the new resource in `client.py`
    1. Register the subtype and define package exports in `__init__.py`
1. Write tests for the new resource and add the resource to `tests.mocks.{components|services}`
1. 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](https://github.com/viamrobotics/viam-python-sdk/blob/main/LICENSE) file

