Metadata-Version: 2.4
Name: pyniryo-nate
Version: 1.0.1
Summary: Python client for the Niryo Nate robot API
Author-email: Niryo <j.mottier@niryo.com>
Maintainer-email: Niryo <j.mottier@niryo.com>
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Human Machine Interfaces
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: typing-extensions
Requires-Dist: paho-mqtt>=2.0
Requires-Dist: requests
Requires-Dist: urllib3
Requires-Dist: pydantic
Requires-Dist: pydantic[email]
Requires-Dist: strenum
Requires-Dist: orjson
Requires-Dist: pyjwt
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinxemoji; extra == "docs"
Requires-Dist: sphinx-tabs; extra == "docs"
Requires-Dist: sphinx-togglebutton; extra == "docs"
Provides-Extra: tests
Requires-Dist: pytest; extra == "tests"
Requires-Dist: coverage; extra == "tests"
Requires-Dist: mypy; extra == "tests"
Requires-Dist: types-requests; extra == "tests"
Provides-Extra: scripts
Requires-Dist: openapi3-parser; extra == "scripts"
Requires-Dist: pyyaml; extra == "scripts"
Requires-Dist: jinja2; extra == "scripts"
Requires-Dist: datamodel-code-generator[ruff]; extra == "scripts"
Provides-Extra: dev
Requires-Dist: pyniryo-nate[docs,scripts,tests]; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

pyniryo-nate
============

.. contents:: **Table of Contents**
    :backlinks: none

Installation
------------

``pyniryo-nate`` is distributed as a universal wheel and supports Python 3.10+.

.. code-block:: bash

    $ pip install pyniryo-nate

Usage
-----

``pyniryo-nate`` is the Python client of the Niryo Nate robot API. The full documentation is
available at https://pyniryo-nate.docs.niryo.com.

.. code-block:: python

    from pyniryo_nate import Nate
    from pyniryo_nate.models import Joints

    # Initialize with hostname and credentials
    nate = Nate(hostname="10.10.10.10", login=("user", "secret"))

    # Or use environment variables
    nate = Nate()

    # Move the robot. The key selector must be on manual, see the Direct control page of
    # the documentation.
    nate.robot.move(Joints(0, 0, 0, 0, 0, 0)).wait()

Constructor Arguments
~~~~~~~~~~~~~~~~~~~~~

The ``Nate`` class constructor accepts the following parameters:

- ``hostname`` (str): The hostname or IP address of the Nate API. If empty, it will use the ``NATE_HOSTNAME`` environment variable, defaulting to ``'localhost'`` if not set.
- ``login`` (tuple[str, str]): A tuple containing ``(username, password)`` for authentication. If empty, it will use the ``NATE_USERNAME`` and ``NATE_PASSWORD`` environment variables. A program run by the robot needs none.
- ``device_id`` (str): The identifier of the robot expected at ``hostname``. If empty, it will use the ``NATE_DEVICE_ID`` environment variable; if that is not set either, the first robot reached binds the client.

The Connecting page of the documentation covers the two ways to connect, from a remote host and as a program run by the robot.

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

The following environment variables can be used to configure the Nate client:

**Authentication:**

- ``NATE_HOSTNAME`` - The hostname or IP address of the Nate API (default: ``'localhost'``)
- ``NATE_USERNAME`` - Username for login authentication
- ``NATE_PASSWORD`` - Password for login authentication

**Advanced Options:**

- ``NATE_HTTP_PORT`` - HTTPS port of the API (default: ``8443``)
- ``NATE_MQTT_PORT`` - MQTTS port of the broker (default: ``8883``)
- ``NATE_CA_FILE`` - A PEM file holding extra root certificates to trust, on top of the root shipped with the package
- ``NATE_DEVICE_ID`` - The identifier of the expected robot; another robot at that address is refused before any credential is sent

Connection security
~~~~~~~~~~~~~~~~~~~

Every connection to the robot is encrypted, over HTTPS and MQTTS, and the Niryo root ships with
the package, so no setup is needed to trust a Niryo robot. A robot presenting a certificate from any other
authority is refused with a ``pyniryo_nate.exceptions.TlsError``. Pass the expected robot as
``Nate(hostname, login, device_id=...)`` or ``NATE_DEVICE_ID`` to refuse any other device at that address,
and point ``NATE_CA_FILE`` at a PEM file to trust extra roots.

License
-------

pyniryo-nate is distributed under the terms of
`GNU General Public License v3.0 <https://choosealicense.com/licenses/gpl-3.0>`_
