Metadata-Version: 2.4
Name: roslibpy
Version: 2.0.1
Summary: Python ROS Bridge library.
Home-page: https://github.com/gramaziokohler/roslibpy
Author: Gramazio Kohler Research
Author-email: gramaziokohler@arch.ethz.ch
License: MIT license
Keywords: ros,ros-bridge,robotics,websockets
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: IronPython
Classifier: Topic :: Scientific/Engineering
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: autobahn>=17.10
Requires-Dist: twisted[tls]>=17.9
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

============================
roslibpy: ROS Bridge library
============================



**Python ROS Bridge library** allows to use Python and IronPython to interact
with `ROS <http://www.ros.org>`_, the open-source robotic middleware.
It uses WebSockets to connect to
`rosbridge 2.0 <http://wiki.ros.org/rosbridge_suite>`_ and provides publishing,
subscribing, service calls, actionlib, TF, and other essential ROS functionality.

Unlike the `rospy <http://wiki.ros.org/rospy>`_ library, this does not require a
local ROS environment, allowing usage from platforms other than Linux.

The API of **roslibpy** is modeled to closely match that of `roslibjs`_.

ROS 1 is fully supported. ROS 2 support is still in progress.


Main features
-------------

* Topic publishing and subscribing.
* Service calls (client).
* Service advertisement (server).
* ROS parameter management (get/set/delete).
* ROS API services for getting ROS meta-information.
* Actionlib support for interfacing with preemptable tasks.
* TF Client via the ``tf2_web_republisher``.

**Roslibpy** runs on Python 3.x and IronPython 2.7.


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

To install **roslibpy**, simply use ``pip``::

    pip install roslibpy

For IronPython, the ``pip`` command is slightly different::

    ipy -X:Frames -m pip install --user roslibpy

Remember that you will need a working ROS setup including the
**rosbridge server** and **TF2 web republisher** accessible within your network.


Documentation
-------------

The full documentation, including examples and API reference
is available on `readthedocs <https://roslibpy.readthedocs.io/>`_.


Contributing
------------

Make sure you setup your local development environment correctly:

* Clone the `roslibpy <https://github.com/gramaziokohler/roslibpy>`_ repository.
* Create a virtual environment.
* Install development dependencies:

::

    pip install -r requirements-dev.txt

**You're ready to start coding!**

During development, use `pyinvoke <http://docs.pyinvoke.org/>`_ tasks on the
command prompt to ease recurring operations:

* ``invoke clean``: Clean all generated artifacts.
* ``invoke check``: Run various code and documentation style checks.
* ``invoke docs``: Generate documentation.
* ``invoke test``: Run all tests and checks in one swift command.
* ``invoke``: Show available tasks.

For more details, check the *Contributor's Guide* available as part of `the documentation <https://roslibpy.readthedocs.io/>`_.

The default branch was recently renamed to `main`. If you've already cloned this repository,
you'll need to update your local repository structure with the following lines:

::

    git branch -m master main
    git fetch origin
    git branch -u origin/main main


Releasing this project
----------------------

Ready to release a new version **roslibpy**? Here's how to do it:

* We use `semver <http://semver.org/>`_, i.e. we bump versions as follows:

  * ``patch``: bugfixes.
  * ``minor``: backwards-compatible features added.
  * ``major``: backwards-incompatible changes.

* Update the ``CHANGELOG.rst`` with all novelty!
* Create a release branch and prepare the release:

::

    git checkout -b release-x.y.z
    invoke release [patch|minor|major]

* This will run tests, bump the version, create a git tag, and commit changes.
* Push the release branch and tag, then create a Pull Request to ``main``:

::

    git push origin release-x.y.z
    git push origin --tags

* Once the PR is reviewed and merged into ``main``, the release workflow will automatically publish to PyPI.
* The workflow verifies the tag is on the ``main`` branch before publishing, preventing accidental releases from feature branches.


Credits
-------

This library is based on `roslibjs`_ and to a
large extent, it is a line-by-line port to Python, changing only where a more
idiomatic form makes sense, so a huge part of the credit goes to the
`roslibjs authors <https://github.com/RobotWebTools/roslibjs/blob/develop/AUTHORS.md>`_.

.. _roslibjs: http://wiki.ros.org/roslibjs


Changelog
=========

All notable changes to this project will be documented in this file.

The format is based on `Keep a Changelog <http://keepachangelog.com/en/1.0.0/>`_
and this project adheres to `Semantic Versioning <http://semver.org/spec/v2.0.0.html>`_.

2.0.1
----------

**Added**

**Changed**

**Fixed**

* Fixed reconnection on the Twisted transport failing after a connection had
  been idle for more than a few seconds: ``connect`` now schedules the
  connection through the reactor thread so an idle reactor is woken to service
  it (previously the new connector was added from another thread and the
  reactor, blocked in ``select()``, never noticed it).

**Deprecated**

**Removed**

2.0.0
----------

**Added**

* Added ROS 2 action client support.
* Added ``wait_goal`` method to ``ActionClient`` to block until a goal reaches a terminal state.
* Moved ``actionlib`` module to ``roslibpy.ros1`` namespace.

**Changed**

**Fixed**

* Fixed KeyError in ROS 2 ActionClient when receiving action results with different message formats from rosbridge.

**Deprecated**

**Removed**

1.8.1
----------

**Added**

**Changed**

**Fixed**

* Fixed ROS connection issue on IronPython.

**Deprecated**

**Removed**

1.8.0
----------

**Added**

* Added websocket header support to the ROS-client.

**Changed**

**Fixed**

**Deprecated**

**Removed**

1.7.0
----------

**Added**

* Added a ROS 2 compatible header class in ``roslibpy.ros2.Header``.

**Changed**

**Fixed**

**Deprecated**

**Removed**

1.6.0
----------

**Added**

* Added authentication functionality described in [rosauth](http://wiki.ros.org/rosauth).

**Changed**

**Fixed**

**Deprecated**

**Removed**

1.5.0
----------

**Added**

* Added a wait event to close on IronPython to ensure the close request is sent before returning.

**Changed**

**Fixed**

* Fixed reconnection behavior on IronPython which would trigger reconnects even after a manual disconnect.

**Deprecated**

**Removed**

1.4.2
----------

**Added**

**Changed**

* Added ``tls`` to the twisted requirement (#111).

**Fixed**

**Deprecated**

**Removed**

1.4.1
----------

**Added**

**Changed**

**Fixed**

* Fixed bug with action client/server and now they work as expected.
* Fixed Python 2.7 incompatibilities introduced in 1.4.0.

**Deprecated**

**Removed**

1.4.0
----------

**Added**

**Changed**

* Switched to ``black`` for python code formatting.
* Fix incompatible settings between ``black`` and ``flake8``.
* Updated Github Actions workflows to remove python 3.6 builds.
* Replaced occurrences of ``raise Exception`` with more specific ``Exception`` subclasses.

**Fixed**

**Deprecated**

**Removed**

1.3.0
----------

**Added**

* Added function to set the default timeout value.
* Added ROS host and port parameters to the command-line interface.

**Fixed**

* Fixed #87 where a goal could be marked as terminal on result alone rather
  than both result and status.
* Ensure input of ``Time`` is always two integers.

1.2.1
----------

**Added**

**Changed**

**Fixed**

* Fixed blocking issues on the Twisted/Autobahn-based implementation of websockets.

**Deprecated**

**Removed**

1.2.0
----------

**Changed**

* Changed behavior: Advertising services automatically reconnect when websockets is reconnected.
* References to ROS master change to ROS.

**Added**

* Added ``Header`` and ``Time`` data types.
* Added ROS API method to retrieve current ROS time: ``ros.get_time``.

1.1.0
----------

**Added**

* Added ``set_initial_delay``, ``set_max_delay`` and ``set_max_retries``  to ``RosBridgeClientFactory`` to control reconnection parameters.
* Added ``closing`` event to ``Ros`` class that gets triggered right before closing the connection.

1.0.0
----------

**Changed**

* Changed behavior: Topics automatically reconnect when websockets is reconnected.

**Added**

* Added blocking behavior to more ROS API methods: ``ros.get_nodes`` and ``ros.get_node_details``.
* Added reconnection support to IronPython implementation of websockets.
* Added automatic topic reconnection support for both subscribers and publishers.

**Fixed**

* Fixed reconnection issues on the Twisted/Autobahn-based implementation of websockets.

0.7.1
----------

**Fixed**

* Fixed blocking service calls for Mac OS.

0.7.0
----------

**Changed**

* The non-blocking event loop runner ``run()`` now defaults to 10 seconds timeout before raising an exception.

**Added**

* Added blocking behavior to ROS API methods, e.g. ``ros.get_topics``.
* Added command-line mode to ROS API, e.g. ``roslibpy topic list``.
* Added blocking behavior to the ``Param`` class.
* Added parameter manipulation methods to ``Ros`` class: ``get_param``, ``set_param``, ``delete_param``.

0.6.0
----------

**Changed**

* For consistency, ``timeout`` parameter of ``Goal.send()`` is now expressed in **seconds**, instead of milliseconds.

**Deprecated**

* The ``timeout`` parameter of ``ActionClient()`` is ignored in favor of blocking until the connection is established.

**Fixed**

* Raise exceptions when timeouts expire on ROS connection or service calls.

**Added**

* Support for calling a function in a thread from the Ros client.
* Added implementation of a Simple Action Server.

0.5.0
----------

**Changed**

* The non-blocking event loop runner now waits for the connection to be established in order to minimize the need for ``on_ready`` handlers.

**Added**

* Support blocking and non-blocking service calls.

**Fixed**

* Fixed an internal unsubscribing issue.

0.4.1
----------

**Fixed**

* Resolve reconnection issues.

0.4.0
----------

**Added**

* Add a non-blocking event loop runner.

0.3.0
----------

**Changed**

* Unsubscribing from a listener no longer requires the original callback to be passed.

0.2.1
----------

**Fixed**

* Fix JSON serialization error on TF Client (on Python 3.x).

0.2.0
----------

**Added**

* Add support for IronPython 2.7.

**Changed**

* Handler ``on_ready`` now defaults to run the callback in thread.

**Deprecated**

* Rename ``run_event_loop`` to the more fitting ``run_forever``.

0.1.1
----------

**Fixed**

* Minimal documentation fixes.

0.1.0
----------

**Added**

* Initial version.
