asyncio_for_robotics 1.0.4__tar.gz

asyncio_for_robotics-1.0.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Elian NEPPEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asyncio_for_robotics-1.0.4/PKG-INFO

@@ -0,0 +1,261 @@
+Metadata-Version: 2.4
+Name: asyncio_for_robotics
+Version: 1.0.4
+Summary: Asyncio interface for ROS 2, Zenoh, and other robotic middlewares.
+Author-email: Elian <no@no.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/2lian/asyncio-for-robotics
+Project-URL: Repository, https://github.com/2lian/asyncio-for-robotics
+Project-URL: Issues, https://github.com/yourusername/asyncio-for-robotics/issues
+Keywords: asyncio,robotics,ros2,zenoh,publisher,subcriber
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Networking
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typing_extensions>=4.0; python_version < "3.11"
+Requires-Dist: async-timeout; python_version < "3.11"
+Provides-Extra: zenoh
+Requires-Dist: eclipse-zenoh>=1.0.0; extra == "zenoh"
+Provides-Extra: dev
+Requires-Dist: colorama; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: pyfiglet; extra == "dev"
+Requires-Dist: uvloop; extra == "dev"
+Provides-Extra: build
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# Asyncio For Robotics
+| Requirements | Compatibility | Tests |
+|---|---|---|
+| [![python](https://img.shields.io/pypi/pyversions/asyncio_for_robotics?logo=python&logoColor=white&label=Python&color=%20blue)](https://pypi.org/project/asyncio_for_robotics/)<br>[![mit](https://img.shields.io/badge/License-MIT-gold)](https://opensource.org/license/mit) | [![zenoh](https://img.shields.io/badge/Zenoh-%3E%3D1.0-blue)](https://zenoh.io/)<br>[![ros](https://img.shields.io/badge/ROS_2-Humble%20%7C%20Jazzy-blue?logo=ros)](https://github.com/ros2) | [![Python](https://github.com/2lian/asyncio-for-robotics/actions/workflows/python-package.yml/badge.svg)](https://github.com/2lian/asyncio-for-robotics/actions/workflows/python-package.yml)<br>[![ROS 2](https://github.com/2lian/asyncio-for-robotics/actions/workflows/ros-pytest.yml/badge.svg)](https://github.com/2lian/asyncio-for-robotics/actions/workflows/ros-pytest.yml) |
+
+The Asyncio For Robotics (`afor`) library makes `asyncio` usable with ROS 2, Zenoh and more, letting you write linear, testable, and non-blocking Python code.
+
+- Better syntax.
+- Only native python: Better docs and support.
+- Simplifies testing.
+
+*Will this make my code slower?* [No.](https://github.com/2lian/asyncio-for-robotics/tree/main/README.md#about-speed)
+
+*Will this make my code faster?* No. However `asyncio` will help YOU write
+better, faster code.
+
+*Does it replace ROS 2? Is this a wrapper?* No. It is a tool adding async capabilities. It gives you more choices, not less.
+
+## Install
+
+### Barebone
+
+```bash
+pip install asyncio_for_robotics
+```
+
+### For ROS 2
+
+Compatible with: `jazzy`,`humble` and newer. This library is pure python (>=3.10), so it installs easily.
+
+```bash
+pip install asyncio_for_robotics
+```
+
+### For Zenoh
+
+```bash
+pip install asyncio_for_robotics[zenoh]
+```
+
+## Read more
+
+- [Detailed ROS 2 tutorial](https://github.com/2lian/asyncio-for-robotics/blob/main/using_with_ros.md)
+- [Detailed examples](https://github.com/2lian/asyncio-for-robotics/blob/main/asyncio_for_robotics/example)
+  - [no talking 🦍 show me code 🦍](https://github.com/2lian/asyncio-for-robotics/blob/main/asyncio_for_robotics/example/ros2_pubsub.py)
+- [Usage for software testing](https://github.com/2lian/asyncio-for-robotics/blob/main/tests)
+- [Implement your own protocol](https://github.com/2lian/asyncio-for-robotics/blob/main/own_proto_example.md)
+
+## Code sample
+
+Syntax is identical between ROS 2 and Zenoh.
+
+### Wait for messages one by one
+
+Application:
+- Get the latest sensor data
+- Get clock value
+- Wait for trigger
+- Wait for system to be operational
+
+```python
+sub = afor.Sub(...)
+
+# get the latest message
+latest = await sub.wait_for_value()
+
+# get a new message
+new = await sub.wait_for_new()
+
+# get the next message received
+next = await sub.wait_for_next()
+```
+
+### Continuously listen to a data stream
+
+Application:
+- Process a whole data stream
+- React to changes in sensor data
+
+```python
+# Continuously process the latest messages
+async for msg in sub.listen():
+    status = foo(msg)
+    if status == DONE:
+        break
+
+# Continuously process all incoming messages
+async for msg in sub.listen_reliable():
+    status = foo(msg)
+    if status == DONE:
+        break
+```
+
+### Reliable, non-drifting Rate
+
+Application:
+- Periodic updates and actions
+
+```python
+# Rate is simply a subscriber triggering on every tick
+rate = afor.Rate(frequency=0.01, time_source=time.time_ns)
+
+# Wait for the next tick
+await rate.wait_for_new()
+
+# Executes after a tick
+async for _ in rate.listen():
+    foo(...)
+
+# Reliably executes for every tick
+async for _ in sub.listen_reliable():
+    foo(...)
+```
+
+### Improved Services / Queryable for ROS 2
+
+Services are needlessly convoluted in ROS 2 and intrinsically not async
+(because the server callback function MUST return a response). `afor` overrides
+the ROS behavior, allowing for the response to be sent later. Implementing
+similar systems for other transport protocol should be very easy: The server is just a
+`asyncio_for_robotics.core.BaseSub` generating responder objects.
+
+Application:
+- Client request reply from a server.
+- Servers can delay their response without blocking (not possible in ROS 2)
+
+```python
+# Server is once again a afor subscriber, but generating responder objects
+server = afor.Server(...)
+
+# processes all requests.
+# listen_reliable method is recommanded as it cannot skip requests
+async for responder in server.listen_reliable():
+    if responder.request == "PING!":
+        reponder.response = "PONG!"
+        await asyncio.sleep(...) # reply can be differed
+        reponder.send()
+    else:
+        ... # reply is not necessary
+```
+
+```python
+# the client implements a async call method
+client = afor.Client(...)
+
+response = await client.call("PING!")
+```
+
+### Process for the right amount of time
+
+Application:
+- Test if the system is responding as expected
+- Run small tasks with small and local code
+
+```python
+# Listen with a timeout
+data = await afor.soft_wait_for(sub.wait_for_new(), timeout=1)
+if isinstance(data, TimeoutError):
+    pytest.fail(f"Failed to get new data in under 1 second")
+
+
+# Process a codeblock with a timeout
+async with afor.soft_timeout(1):
+    sum = 0
+    total = 0
+    async for msg in sub.listen_reliable():
+        number = process(msg)
+        sum += number
+        total += 1
+
+last_second_average = sum/total
+assert last_second_average == pytest.approx(expected_average)
+```
+
+## About Speed
+
+The inevitable question: *“But isn’t this slower than the ROS 2 executor? ROS 2 is the best!”*
+
+In short: `rclpy`'s executor is the bottleneck. 
+- Comparing to the best ROS 2 Jazzy can do (`SingleThreadedExecutor`), `afor` increases latency from 110us to 150us.
+- Comparing to other execution methods, `afor` is equivalent if not faster.
+- If you find it slow, you should use C++ or Zenoh (or contribute to this repo?).
+
+Benchmark code is available in [`./tests/bench/`](https://github.com/2lian/asyncio-for-robotics/blob/main/tests/bench/), it consists in two pairs of pub/sub infinitely echoing a message (using one single node). The messaging rate, thus measures the request to response latency. 
+
+| With `afor`  | Transport | Executor                        | | Frequency (kHz) | Latency (ms) |
+|:----------:|:----------|:----------------------------------|-|---------:|---------:|
+| ✔️         | Zenoh     | None                              | | **95** | **0.01** |
+| ✔️         | ROS 2     | [Experimental Asyncio](https://github.com/ros2/rclpy/pull/1399)              | | **17** | **0.06** |
+| ❌         | ROS 2     | [Experimental Asyncio](https://github.com/ros2/rclpy/pull/1399)              | | 13 | 0.08 |
+| ❌         | ROS 2     | SingleThreaded                    | | 9 | 0.11 |
+| ✔️         | ROS 2     | SingleThreaded                    | | **7**  | **0.15** |
+| ✔️         | ROS 2     | MultiThreaded                     | | **3**  | **0.3** |
+| ❌         | ROS 2     | MultiThreaded                     | | **3**  | **0.3** |
+| ✔️         | ROS 2     | [`ros_loop` Method](https://github.com/m2-farzan/ros2-asyncio)                     | | 3  | 0.3 |
+
+
+Details:
+- `uvloop` was used, replacing the asyncio executor (more or less doubles the performances for Zenoh)
+- RMW was set to `rmw_zenoh_cpp`
+- ROS2 benchmarks uses `afor`'s `ros2.ThreadedSession` (the default in `afor`). 
+- Only the Benchmark of the [`ros_loop` method](https://github.com/m2-farzan/ros2-asyncio) uses `afor`'s second type of session: `ros2.SynchronousSession`.
+- ROS 2 executors can easily be changed in `afor` when creating a session.
+- The experimental `AsyncioExecutor` PR on ros rolling by nadavelkabets is incredible [https://github.com/ros2/rclpy/pull/1399](https://github.com/ros2/rclpy/pull/1399). Maybe I will add proper support for it (but only a few will want to use an unmerged experimental PR of ROS 2 rolling).
+- If there is interest in those benchmarks I will improve them, so others can run them all easily.
+
+Analysis:
+- Zenoh is extremely fast, proving that `afor` is not the bottleneck.
+- This `AsyncioExecutor` having better perf when using `afor` is interesting, because `afor` does not bypass code.
+  - I think this is due to `AsyncioExecutor` having some overhead that affects its own callback.
+  - Without `afor` the ROS 2 callback executes some code and publishes.
+  - With `afor` the ROS 2 callback returns immediately, and fully delegates execution to `asyncio`.
+- The increase of latency on the `SingleThreaded` executors proves that getting data in and out of the `rclpy` executor and thread is the main bottleneck. 
+  - `AsyncioExecutor` does not have such thread, thus can directly communicate.
+  - Zenoh has its own thread, however it is built exclusively for multi-thread operations, without any executor. Thus achieves far superior performances.
+- `MultiThreadedExecutor` is just famously slow.
+- Very surprisingly, the well known `ros_loop` method detailed here [https://github.com/m2-farzan/ros2-asyncio](https://github.com/m2-farzan/ros2-asyncio) is slow.

asyncio_for_robotics-1.0.4/README.md

@@ -0,0 +1,217 @@
+# Asyncio For Robotics
+| Requirements | Compatibility | Tests |
+|---|---|---|
+| [![python](https://img.shields.io/pypi/pyversions/asyncio_for_robotics?logo=python&logoColor=white&label=Python&color=%20blue)](https://pypi.org/project/asyncio_for_robotics/)<br>[![mit](https://img.shields.io/badge/License-MIT-gold)](https://opensource.org/license/mit) | [![zenoh](https://img.shields.io/badge/Zenoh-%3E%3D1.0-blue)](https://zenoh.io/)<br>[![ros](https://img.shields.io/badge/ROS_2-Humble%20%7C%20Jazzy-blue?logo=ros)](https://github.com/ros2) | [![Python](https://github.com/2lian/asyncio-for-robotics/actions/workflows/python-package.yml/badge.svg)](https://github.com/2lian/asyncio-for-robotics/actions/workflows/python-package.yml)<br>[![ROS 2](https://github.com/2lian/asyncio-for-robotics/actions/workflows/ros-pytest.yml/badge.svg)](https://github.com/2lian/asyncio-for-robotics/actions/workflows/ros-pytest.yml) |
+
+The Asyncio For Robotics (`afor`) library makes `asyncio` usable with ROS 2, Zenoh and more, letting you write linear, testable, and non-blocking Python code.
+
+- Better syntax.
+- Only native python: Better docs and support.
+- Simplifies testing.
+
+*Will this make my code slower?* [No.](https://github.com/2lian/asyncio-for-robotics/tree/main/README.md#about-speed)
+
+*Will this make my code faster?* No. However `asyncio` will help YOU write
+better, faster code.
+
+*Does it replace ROS 2? Is this a wrapper?* No. It is a tool adding async capabilities. It gives you more choices, not less.
+
+## Install
+
+### Barebone
+
+```bash
+pip install asyncio_for_robotics
+```
+
+### For ROS 2
+
+Compatible with: `jazzy`,`humble` and newer. This library is pure python (>=3.10), so it installs easily.
+
+```bash
+pip install asyncio_for_robotics
+```
+
+### For Zenoh
+
+```bash
+pip install asyncio_for_robotics[zenoh]
+```
+
+## Read more
+
+- [Detailed ROS 2 tutorial](https://github.com/2lian/asyncio-for-robotics/blob/main/using_with_ros.md)
+- [Detailed examples](https://github.com/2lian/asyncio-for-robotics/blob/main/asyncio_for_robotics/example)
+  - [no talking 🦍 show me code 🦍](https://github.com/2lian/asyncio-for-robotics/blob/main/asyncio_for_robotics/example/ros2_pubsub.py)
+- [Usage for software testing](https://github.com/2lian/asyncio-for-robotics/blob/main/tests)
+- [Implement your own protocol](https://github.com/2lian/asyncio-for-robotics/blob/main/own_proto_example.md)
+
+## Code sample
+
+Syntax is identical between ROS 2 and Zenoh.
+
+### Wait for messages one by one
+
+Application:
+- Get the latest sensor data
+- Get clock value
+- Wait for trigger
+- Wait for system to be operational
+
+```python
+sub = afor.Sub(...)
+
+# get the latest message
+latest = await sub.wait_for_value()
+
+# get a new message
+new = await sub.wait_for_new()
+
+# get the next message received
+next = await sub.wait_for_next()
+```
+
+### Continuously listen to a data stream
+
+Application:
+- Process a whole data stream
+- React to changes in sensor data
+
+```python
+# Continuously process the latest messages
+async for msg in sub.listen():
+    status = foo(msg)
+    if status == DONE:
+        break
+
+# Continuously process all incoming messages
+async for msg in sub.listen_reliable():
+    status = foo(msg)
+    if status == DONE:
+        break
+```
+
+### Reliable, non-drifting Rate
+
+Application:
+- Periodic updates and actions
+
+```python
+# Rate is simply a subscriber triggering on every tick
+rate = afor.Rate(frequency=0.01, time_source=time.time_ns)
+
+# Wait for the next tick
+await rate.wait_for_new()
+
+# Executes after a tick
+async for _ in rate.listen():
+    foo(...)
+
+# Reliably executes for every tick
+async for _ in sub.listen_reliable():
+    foo(...)
+```
+
+### Improved Services / Queryable for ROS 2
+
+Services are needlessly convoluted in ROS 2 and intrinsically not async
+(because the server callback function MUST return a response). `afor` overrides
+the ROS behavior, allowing for the response to be sent later. Implementing
+similar systems for other transport protocol should be very easy: The server is just a
+`asyncio_for_robotics.core.BaseSub` generating responder objects.
+
+Application:
+- Client request reply from a server.
+- Servers can delay their response without blocking (not possible in ROS 2)
+
+```python
+# Server is once again a afor subscriber, but generating responder objects
+server = afor.Server(...)
+
+# processes all requests.
+# listen_reliable method is recommanded as it cannot skip requests
+async for responder in server.listen_reliable():
+    if responder.request == "PING!":
+        reponder.response = "PONG!"
+        await asyncio.sleep(...) # reply can be differed
+        reponder.send()
+    else:
+        ... # reply is not necessary
+```
+
+```python
+# the client implements a async call method
+client = afor.Client(...)
+
+response = await client.call("PING!")
+```
+
+### Process for the right amount of time
+
+Application:
+- Test if the system is responding as expected
+- Run small tasks with small and local code
+
+```python
+# Listen with a timeout
+data = await afor.soft_wait_for(sub.wait_for_new(), timeout=1)
+if isinstance(data, TimeoutError):
+    pytest.fail(f"Failed to get new data in under 1 second")
+
+
+# Process a codeblock with a timeout
+async with afor.soft_timeout(1):
+    sum = 0
+    total = 0
+    async for msg in sub.listen_reliable():
+        number = process(msg)
+        sum += number
+        total += 1
+
+last_second_average = sum/total
+assert last_second_average == pytest.approx(expected_average)
+```
+
+## About Speed
+
+The inevitable question: *“But isn’t this slower than the ROS 2 executor? ROS 2 is the best!”*
+
+In short: `rclpy`'s executor is the bottleneck. 
+- Comparing to the best ROS 2 Jazzy can do (`SingleThreadedExecutor`), `afor` increases latency from 110us to 150us.
+- Comparing to other execution methods, `afor` is equivalent if not faster.
+- If you find it slow, you should use C++ or Zenoh (or contribute to this repo?).
+
+Benchmark code is available in [`./tests/bench/`](https://github.com/2lian/asyncio-for-robotics/blob/main/tests/bench/), it consists in two pairs of pub/sub infinitely echoing a message (using one single node). The messaging rate, thus measures the request to response latency. 
+
+| With `afor`  | Transport | Executor                        | | Frequency (kHz) | Latency (ms) |
+|:----------:|:----------|:----------------------------------|-|---------:|---------:|
+| ✔️         | Zenoh     | None                              | | **95** | **0.01** |
+| ✔️         | ROS 2     | [Experimental Asyncio](https://github.com/ros2/rclpy/pull/1399)              | | **17** | **0.06** |
+| ❌         | ROS 2     | [Experimental Asyncio](https://github.com/ros2/rclpy/pull/1399)              | | 13 | 0.08 |
+| ❌         | ROS 2     | SingleThreaded                    | | 9 | 0.11 |
+| ✔️         | ROS 2     | SingleThreaded                    | | **7**  | **0.15** |
+| ✔️         | ROS 2     | MultiThreaded                     | | **3**  | **0.3** |
+| ❌         | ROS 2     | MultiThreaded                     | | **3**  | **0.3** |
+| ✔️         | ROS 2     | [`ros_loop` Method](https://github.com/m2-farzan/ros2-asyncio)                     | | 3  | 0.3 |
+
+
+Details:
+- `uvloop` was used, replacing the asyncio executor (more or less doubles the performances for Zenoh)
+- RMW was set to `rmw_zenoh_cpp`
+- ROS2 benchmarks uses `afor`'s `ros2.ThreadedSession` (the default in `afor`). 
+- Only the Benchmark of the [`ros_loop` method](https://github.com/m2-farzan/ros2-asyncio) uses `afor`'s second type of session: `ros2.SynchronousSession`.
+- ROS 2 executors can easily be changed in `afor` when creating a session.
+- The experimental `AsyncioExecutor` PR on ros rolling by nadavelkabets is incredible [https://github.com/ros2/rclpy/pull/1399](https://github.com/ros2/rclpy/pull/1399). Maybe I will add proper support for it (but only a few will want to use an unmerged experimental PR of ROS 2 rolling).
+- If there is interest in those benchmarks I will improve them, so others can run them all easily.
+
+Analysis:
+- Zenoh is extremely fast, proving that `afor` is not the bottleneck.
+- This `AsyncioExecutor` having better perf when using `afor` is interesting, because `afor` does not bypass code.
+  - I think this is due to `AsyncioExecutor` having some overhead that affects its own callback.
+  - Without `afor` the ROS 2 callback executes some code and publishes.
+  - With `afor` the ROS 2 callback returns immediately, and fully delegates execution to `asyncio`.
+- The increase of latency on the `SingleThreaded` executors proves that getting data in and out of the `rclpy` executor and thread is the main bottleneck. 
+  - `AsyncioExecutor` does not have such thread, thus can directly communicate.
+  - Zenoh has its own thread, however it is built exclusively for multi-thread operations, without any executor. Thus achieves far superior performances.
+- `MultiThreadedExecutor` is just famously slow.
+- Very surprisingly, the well known `ros_loop` method detailed here [https://github.com/m2-farzan/ros2-asyncio](https://github.com/m2-farzan/ros2-asyncio) is slow.

asyncio_for_robotics-1.0.4/asyncio_for_robotics/__init__.py

@@ -0,0 +1,7 @@
+from asyncio_for_robotics.core.utils import soft_timeout, soft_wait_for, Rate
+
+__all__ = [
+    "soft_wait_for",
+    "soft_timeout",
+    "Rate",
+]

asyncio_for_robotics-1.0.4/asyncio_for_robotics/core/_logger.py

@@ -0,0 +1,125 @@
+import json
+import copy
+import logging.config
+import os
+from datetime import datetime
+from typing import Optional
+
+import colorama
+from colorama import Fore, Style, init
+
+
+class JsonLineFormatter(logging.Formatter):
+    """Outputs log records as JSON lines."""
+
+    def format(self, record):
+        log_record = {
+            "time": datetime.fromtimestamp(record.created).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "funcName": record.funcName,
+            "line": record.lineno,
+        }
+        if record.exc_info:
+            log_record["exc_info"] = self.formatException(record.exc_info)
+        return json.dumps(log_record)
+
+
+LEVEL_COLORS = {
+    "DEBUG": Fore.BLUE,
+    "INFO": Fore.CYAN,
+    "WARNING": Fore.YELLOW,
+    "ERROR": Fore.RED,
+    "CRITICAL": Fore.BLACK + Style.BRIGHT + colorama.Back.RED,
+}
+
+
+class OnlyLevelFilter(logging.Filter):
+    """Only allow a single level through this handler."""
+    def __init__(self, level):
+        self.level = level
+    def filter(self, record):
+        return record.levelno == self.level
+
+class ColoredFormatter(logging.Formatter):
+    """Adds colors to levelname in logs."""
+
+    def format(self, record: logging.LogRecord):
+        record = copy.deepcopy(record)
+        levelname = record.levelname
+        if levelname in LEVEL_COLORS:
+            record.levelname = (
+                f"{LEVEL_COLORS[levelname]}{record.levelname[0]}{Style.RESET_ALL}"
+            )
+            record.msg = f"{LEVEL_COLORS[levelname]}{record.msg}{Style.RESET_ALL}"
+        return super().format(record)
+
+
+def setup_logger(debug_path: Optional[str] = None):
+    handlers = ["stdout", "stderr"]
+    if debug_path:
+        handlers.append("json")
+        handlers.append("userlog")
+    cfg = {
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "user": {
+                "()": ColoredFormatter,
+                "format": "%(levelname)s| %(message)s",
+                "datefmt": "%Y-%m-%dT%H:%M:%S",
+            },
+            "json": {
+                "()": JsonLineFormatter,  # custom formatter
+            },
+        },
+        "filters": {"only_info": {"()": OnlyLevelFilter, "level": logging.INFO}},
+        "handlers": {
+            "stdout": {
+                "class": "logging.StreamHandler",
+                "level": "INFO",
+                "formatter": "user",
+                "filters": ["only_info"],
+                "stream": "ext://sys.stdout",
+            },
+            "stderr": {
+                "class": "logging.StreamHandler",
+                "level": "WARNING",
+                "formatter": "user",
+                "stream": "ext://sys.stderr",
+            },
+            "json": {
+                "class": "logging.FileHandler",
+                "level": "DEBUG",
+                "formatter": "json",
+                "filename": (
+                    os.path.expanduser(debug_path) + "/debug.log.jsonl"
+                    if debug_path is not None
+                    else "log.jsonl"
+                ),  # path relative to working dir
+                "mode": "w",
+            },
+            "userlog": {
+                "class": "logging.FileHandler",
+                "level": "DEBUG",
+                "formatter": "user",
+                "filename": (
+                    os.path.expanduser(debug_path) + "/debug.log"
+                    if debug_path is not None
+                    else "log"
+                ),  # path relative to working dir
+                "mode": "w",
+            },
+        },
+        "loggers": {
+            "asyncio_for_robotics": {
+                "level": "DEBUG",
+                "handlers": handlers,
+                "propagate": False,
+            },
+        },
+    }
+    logging.config.dictConfig(cfg)
+