Merge branch 'viamrobotics:main' into rsdk-4788

Author: martha-johnston

README.md

@@ -1,46 +1,55 @@
 # 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)
 
+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](https://python.viam.dev/setup.html) guide.
+
+If you would like to develop and contribute to Viam's Python SDK, take a look at the [Development](#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](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`
+   - 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`
+   - 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 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](https://github.com/viamrobotics/rust-utils/releases/latest) 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
 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)
+   - 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)
 
@@ -79,31 +88,37 @@ The Viam Python SDK utilizes gRPC and, optionally WebRTC (defaults to on). gRPC
 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](https://pkg.go.dev/go.viam.com/rdk/session) for more details and server-side configuration 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. 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

SETUP.md

@@ -0,0 +1,62 @@
+# Viam + Python
+
+This guide will help you get set up with Viam with Python. It assumes that you are starting from scratch, and will walk you through setting up a fresh environment and installing the necessary requirements.
+
+## Setup your project
+
+The first step is to create a directory to house your project. For this guide, we will be using the directory name `viam-python`:
+
+```bash
+mkdir viam-python
+cd viam-python
+```
+
+## Create a Virtual Environment
+
+Now that we are in the project directory, let's create and activate a virtual environment for python to run in.
+
+> **INFO**
+> Creating a virtual environment (`venv`) is important as it isolates this python environment from any other you might already have. This allows us to ensure a clean project and easier dependency management, and it avoids bloating your global python environment.
+
+```bash
+python3 -m venv viam-env
+source viam-env/bin/activate
+```
+
+> **INFO**
+> Some Linux environments may not have the necessary requirements to create a virtual environment. If you receive an error, you can try running `apt install python3-venv` and then running the above commands.
+
+You will now see `(viam-env)` prepend the commands in your terminal window. This shows that the python packages being used are from this particular environment.
+
+You can exit this environment by running `deactivate`.
+
+## Install Viam
+
+Inside the activated `viam-env` python environment, you can now install the Viam SDK:
+
+```bash
+pip3 install viam-sdk
+```
+
+This will install Viam and all required dependencies.
+
+> **INFO**
+> Some features of the Viam SDK require additional dependencies. For example, the ML Models feature requires extras, which can be installed with `pip3 install viam-sdk[mlmodel]`. Read the documentation to determine if a specific feature requires extra dependencies.
+
+Should you need to install your own requirements, be sure to do so in this environment.
+
+## Setup your IDE
+
+You'll now want to point your IDE to use the python interpreter of your new environment, rather than the default interpreter (likely the global python interpreter).
+
+The following steps are for VS Code. If you're not using VS Code, please read your IDE's documentation on selecting python interpreters.
+
+1. Open the `viam-python` directory in VS Code
+1. Open the Command Palette (using `⇧⌘P` or through the menus View -> Command Palette)
+1. Select the command `Python: Select Interpreter`. There, you should see all the interpreters available to you. You're looking for one the on you just made: `viam-env`. It will look something like: `Python 3.11.5 ('viam-env': venv) ./viam-env/bin/python`. If you don't see it, click the `Refresh` icon on the top right of the Command Palette.
+
+Your IDE will now recognize all packages installed in this environment.
+
+## Start building!
+
+You are now ready to start using Viam's Python SDK!

docs/examples/example.ipynb

@@ -269,6 +269,9 @@
     "from typing import Any, Dict, Mapping, Optional\n",
     "\n",
     "from viam.components.sensor import Sensor\n",
+    "from viam.logging import getLogger\n",
+    "\n",
+    "LOGGER = getLogger(__name__)\n",
     "\n",
     "\n",
     "class MySensor(Sensor):\n",
@@ -282,6 +285,11 @@
     "    async def get_geometries(self, *, extra: Optional[Dict[str, Any]] = None, timeout: Optional[float] = None) -> List[Geometry]:\n",
     "        raise NotImplementedError\n",
     "\n",
+    "    def close(self):\n",
+    "        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module\n",
+    "        # is shutting down.\n",
+    "        LOGGER.debug(f\"{self.name} is closed.\")\n",
+    "\n",
     "# Anything below this line is optional and will be replaced later, but may come in handy for debugging and testing.\n",
     "# To use, call `python wifi_sensor_module.py` in the command line while in the `src` directory.\n",
     "async def main():\n",

docs/examples/module_step2.py

@@ -4,12 +4,15 @@
 from typing_extensions import Self
 
 from viam.components.sensor import Sensor
+from viam.logging import getLogger
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
 from viam.resource.base import ResourceBase
 from viam.resource.registry import Registry, ResourceCreatorRegistration
 from viam.resource.types import Model, ModelFamily
 
+LOGGER = getLogger(__name__)
+
 
 class MySensor(Sensor):
     # Subclass the Viam Sensor component and implement the required functions
@@ -26,6 +29,11 @@ async def get_readings(self, extra: Optional[Dict[str, Any]] = None, **kwargs) -
         wifi_signal = [x for x in content[2].split(" ") if x != ""]
         return {"link": wifi_signal[2], "level": wifi_signal[3], "noise": wifi_signal[4]}
 
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")
+
 
 async def main():
     Registry.register_resource_creator(Sensor.SUBTYPE, MySensor.MODEL, ResourceCreatorRegistration(MySensor.new))

docs/examples/module_step2_optional.py

@@ -4,12 +4,15 @@
 from typing_extensions import Self
 
 from viam.components.sensor import Sensor
+from viam.logging import getLogger
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
 from viam.resource.base import ResourceBase
 from viam.resource.registry import Registry, ResourceCreatorRegistration
 from viam.resource.types import Model, ModelFamily
 
+LOGGER = getLogger(__name__)
+
 
 class MySensor(Sensor):
     # Subclass the Viam Sensor component and implement the required functions
@@ -48,6 +51,11 @@ def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceNam
             multiplier = 1.0
         self.multiplier = multiplier
 
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")
+
 
 async def main():
     Registry.register_resource_creator(Sensor.SUBTYPE, MySensor.MODEL, ResourceCreatorRegistration(MySensor.new, MySensor.validate_config))

docs/examples/module_step3.py

@@ -4,13 +4,16 @@
 from typing_extensions import Self
 
 from viam.components.sensor import Sensor
+from viam.logging import getLogger
 from viam.module.module import Module
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
 from viam.resource.base import ResourceBase
 from viam.resource.registry import Registry, ResourceCreatorRegistration
 from viam.resource.types import Model, ModelFamily
 
+LOGGER = getLogger(__name__)
+
 
 class MySensor(Sensor):
     # Subclass the Viam Sensor component and implement the required functions
@@ -27,6 +30,11 @@ async def get_readings(self, extra: Optional[Dict[str, Any]] = None, **kwargs) -
         wifi_signal = [x for x in content[2].split(" ") if x != ""]
         return {"link": wifi_signal[2], "level": wifi_signal[3], "noise": wifi_signal[4]}
 
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")
+
 
 async def main():
     """

docs/examples/my_cool_arm.py

@@ -5,9 +5,12 @@
 from typing import Any, Dict, List, Optional, Tuple
 
 from viam.components.arm import Arm, JointPositions, KinematicsFileFormat, Pose
+from viam.logging import getLogger
 from viam.operations import run_with_operation
 from viam.proto.common import Capsule, Geometry, Sphere
 
+LOGGER = getLogger(__name__)
+
 
 class MyCoolArm(Arm):
     # Subclass the Viam Arm component and implement the required functions
@@ -102,3 +105,8 @@ async def get_geometries(self, *, extra: Optional[Dict[str, Any]] = None, timeou
 
     async def get_kinematics(self, extra: Optional[Dict[str, Any]] = None, **kwargs) -> Tuple[KinematicsFileFormat.ValueType, bytes]:
         return KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA, self.kinematics
+
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")

examples/complex_module/src/arm/my_arm.py

@@ -5,12 +5,15 @@
 from typing_extensions import Self
 
 from viam.components.arm import Arm, JointPositions, KinematicsFileFormat, Pose
+from viam.logging import getLogger
 from viam.operations import run_with_operation
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import Capsule, Geometry, ResourceName, Sphere
 from viam.resource.base import ResourceBase
 from viam.resource.types import Model, ModelFamily
 
+LOGGER = getLogger(__name__)
+
 
 class MyArm(Arm):
     # Subclass the Viam Arm component and implement the required functions
@@ -104,3 +107,8 @@ async def get_kinematics(self, extra: Optional[Dict[str, Any]] = None, **kwargs)
         with open(filepath, mode="rb") as f:
             file_data = f.read()
         return (KinematicsFileFormat.KINEMATICS_FILE_FORMAT_SVA, file_data)
+
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")

examples/complex_module/src/gizmo/my_gizmo.py

@@ -2,6 +2,7 @@
 
 from typing_extensions import Self
 
+from viam.logging import getLogger
 from viam.module.types import Reconfigurable
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
@@ -10,6 +11,8 @@
 
 from ..gizmo.api import Gizmo
 
+LOGGER = getLogger(__name__)
+
 
 class MyGizmo(Gizmo, Reconfigurable):
     """This is the specific implementation of a ``Gizmo`` (defined in api.py).
@@ -68,3 +71,8 @@ async def do_two(self, arg1: bool, **kwargs) -> str:
 
     def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceName, ResourceBase]):
         self.my_arg = config.attributes.fields["arg1"].string_value
+
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")

examples/server/v1/components.py

@@ -338,6 +338,9 @@ async def model_attributes(self) -> Board.Attributes:
     async def set_power_mode(self, **kwargs):
         raise NotImplementedError()
 
+    async def write_analog(self, pin: str, value: int, *, timeout: Optional[float] = None, **kwargs):
+        raise NotImplementedError()
+
     async def get_geometries(self, extra: Optional[Dict[str, Any]] = None, **kwargs) -> List[Geometry]:
         return GEOMETRIES
 

examples/simple_module/src/main.py

@@ -4,6 +4,7 @@
 from typing_extensions import Self
 
 from viam.components.sensor import Sensor
+from viam.logging import getLogger
 from viam.module.module import Module
 from viam.proto.app.robot import ComponentConfig
 from viam.proto.common import ResourceName
@@ -12,6 +13,8 @@
 from viam.resource.types import Model, ModelFamily
 from viam.utils import ValueTypes
 
+LOGGER = getLogger(__name__)
+
 
 class MySensor(Sensor):
     # Subclass the Viam Sensor component and implement the required functions
@@ -49,6 +52,11 @@ def reconfigure(self, config: ComponentConfig, dependencies: Mapping[ResourceNam
             multiplier = 1.0
         self.multiplier = multiplier
 
+    def close(self):
+        # This is a completely optional function to include. This will be called when the resource is removed from the config or the module
+        # is shutting down.
+        LOGGER.debug(f"{self.name} is closed.")
+
 
 async def main():
     """This function creates and starts a new module, after adding all desired resource models.