Skip to content

Commit 5885425

Browse files
haixuanTaohaixuanTao
committed
Refactor README 
1 parent 9508fbb commit 5885425

File tree

1 file changed

+137
-21
lines changed

1 file changed

+137
-21
lines changed

‎README.md

+137-21
Original file line numberDiff line numberDiff line change
@@ -31,55 +31,109 @@
3131

3232
---
3333

34-
## Why dora-rs?
34+
# What is dora-rs?
3535

36-
In 2023, AI is booming! Robotic framework however hasn't changed much in years... This is why we create dora-rs! dora-rs is a new robotic framework that brings modernity into robotic application.
36+
Dataflow-oriented robotic application (dora-rs) is a framework that makes creation of robotic applications fast and simple.
3737

38-
dora-rs can already show impressive performance, up to 17x speedup compared to ROS2 in Python! This is the result of using our own shared memory server and Apache Arrow to achieve zero copy!
38+
Building a robotic application can be summed up as bringing together hardwares, algorithms, and AI models, and make them communicate with each others. At dora-rs, we try to:
3939

40-
Those performance improvements make a world of difference for beginners, AI practitioners, and weekend hobbyists who have been limited by the lack of support for Python in this field!
40+
- make integration of hardware and software easy by supporting Python, C, C++, and also ROS2.
41+
- make communication low latency by using zero-copy Arrow messages.
4142

42-
But, dora-rs is still experimental and we're still working on many features such as:
43+
dora-rs is still experimental and you might experience bugs, but we're working very hard to make it stable as possible.
4344

44-
- [dora-ros2-bridge](https://github.com/dora-rs/dora-ros2-bridge) to bridge dora and ros 2!
45-
- dora-rs for Deep Learning applications, to make it easy to integrate state of the art DL model and hopefully train them within the framework.
45+
## Performance
4646

47-
Feel free to reach out if you have any questions!
47+
dora-rs can show impressive performance, up to 17x faster compared to current status quo ROS2 in Python! This is the result of using our own shared memory server and Apache Arrow to achieve zero copy data passing.
4848

49-
<p align="center">
50-
<img src="./docs/src/latency.png" width="600">
51-
52-
</p>
49+
<a href="https://dora.carsmos.ai/">
50+
<img src="./docs/src/latency.png" align="center" width="600">
51+
</a>
52+
53+
> See: https://github.com/dora-rs/dora-benchmark/tree/main for reproduction.
54+
55+
## Dataflow Paradignm
56+
57+
dora-rs implements a dataflow paradigm where tasks are split between nodes isolated as individual processes.
58+
Each node defines its inputs and outputs to connect with other nodes.
59+
The dataflow paradigm has the advantage of creating an abstraction layer that makes robotic applications modular and easily configurable.
60+
61+
## Communication
62+
63+
Communication between nodes is handled with shared memory on a same machine and TCP on distributed machines. Our shared memory implementation tracks messages across processes and discards them when obsolete. Shared memory slots are cached to avoid new memory allocation.
64+
65+
## Message Format
66+
67+
Nodes communicate with Apache Arrow Data Format.
68+
69+
[Apache Arrow](https://github.com/apache/arrow-rs) is a universal memory format for flat and hierarchical data. The Arrow memory format supports zero-copy reads for lightning-fast data access without serialization overhead. It defines a C data interface without any build-time or link-time dependency requirement, that means that dora-rs has **no compilation step** beyond the native compiler of your favourite language.
70+
71+
<img align="center" src="https://github.com/dora-rs/dora-rs.github.io/blob/main/static/img/arrow.png?raw=true" width="600">
72+
73+
## Opentelemetry
74+
75+
dora-rs uses Opentelemetry to record all your logs, metrics and traces. This means that the data and telemetry can be linked using a shared abstraction.
76+
77+
[Opentelemetry](https://opentelemetry.io/) is an open source observability standard that makes dora-rs telemetry collectable by most backend such as elasticseach, prometheus, Datadog..
78+
79+
Opentelemetry is language independent, backend agnostic, and easily collect distributed data, making it perfect for dora-rs applications.
80+
81+
<img src="https://github.com/dora-rs/dora-rs.github.io/blob/main/static/img/opentelemetry.png?raw=true" align="center" width="600">
82+
83+
## Hot-Reloading
84+
85+
dora-rs implements Hot-Reloading for python which means you can change code at runtime in Python while keeping your state intact.
86+
87+
Using the feature flag: `--attach --hot-reload`, dora-rs watch for code change and reload nodes that has been modified.
88+
You can check fail-safe mecanism at: https://github.com/dora-rs/dora/pull/239
89+
90+
<a href="http://www.youtube.com/watch?v=NvvTEP8Jak8">
91+
<img align="center" width="600" alt="demo" src=http://img.youtube.com/vi/NvvTEP8Jak8/0.jpg>
92+
</a>
93+
94+
## Self-Coding Robot: Code RAG (WIP)
95+
96+
You can easily create a self-coding robot, by combining Hot-reloading with a Retrieval Augmented Generation (RAG) that is going to generate code modification from your prompt.
97+
See:[examples/python-operator-dataflow](examples/python-operator-dataflow)
98+
99+
<img src="https://github.com/dora-rs/dora-rs.github.io/blob/main/static/img/RAG.svg?raw=true" align="center" width="600">
100+
101+
Self-Coding Robot is just the tip of the iceberg of robotics combined with llm, that we hope to power. There is so much more that we haven't explored yet like:
102+
103+
- [self-debugging](https://arxiv.org/pdf/2304.05128.pdf)
104+
- [memory](https://github.com/cpacker/MemGPT)
105+
- [function calling](https://github.com/ShishirPatil/gorilla)
106+
- ...
53107

54108
## Installation
55109

56110
Quickest way:
57111

58112
```bash
59-
cargo install dora-cli # In case of issues, you can try to add `--locked`
113+
cargo install dora-cli --locked
60114
pip install dora-rs # For Python API
61115

62116
dora --help
63117
```
64118

65-
For more installation guideline, check out our installation guide here: https://dora.carsmos.ai/docs/guides/Installation/installing
119+
For more info on installation, check out [our guide](https://dora.carsmos.ai/docs/guides/Installation/installing).
66120

67121
## Getting Started
68122

69123
1. Install the example python dependencies:
70124

71125
```bash
72-
pip install -r https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/requirements.txt
126+
pip install -r raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/requirements.txt
73127
```
74128

75129
2. Get some example operators:
76130

77131
```bash
78-
wget https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/webcam.py
79-
wget https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/plot.py
80-
wget https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/utils.py
81-
wget https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/object_detection.py
82-
wget https://raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/dataflow.yml
132+
wget raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/webcam.py
133+
wget raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/plot.py
134+
wget raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/utils.py
135+
wget raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/object_detection.py
136+
wget raw.githubusercontent.com/dora-rs/dora/v0.3.2/examples/python-operator-dataflow/dataflow.yml
83137
```
84138

85139
3. Start the dataflow
@@ -95,9 +149,54 @@ To stop your dataflow, you can use <kbd>ctrl</kbd>+<kbd>c</kbd>
95149

96150
To go further, you can add a yolov8 operator, check out our getting started here: https://dora.carsmos.ai/docs/guides/getting-started/yolov8/
97151

152+
## ROS2 Bridge
153+
154+
- Compilation Free Message passing to ROS 2
155+
- Automatic conversion ROS 2 Message <-> Arrow Array
156+
157+
```python
158+
import random
159+
import pyarrow as pa
160+
161+
# Configuration Boilerplate...
162+
turtle_twist_writer = ...
163+
164+
## Arrow Based ROS2 Twist Message
165+
## which does not requires ROS2 import
166+
message = pa.array([{
167+
"linear": {
168+
"x": 1,
169+
},
170+
"angular": {
171+
"z": 1
172+
},
173+
}])
174+
175+
turtle_twist_writer.publish(message)
176+
```
177+
178+
> You might want to use ChatGPT to write the Arrow Formatting: https://chat.openai.com/share/4eec1c6d-dbd2-46dc-b6cd-310d2895ba15
179+
180+
## Hardwares
181+
182+
Cool hardware that we think might be good fit to try out dora-rs 🙋 We are not sponsored by manufacturers:
183+
184+
| | Price | Open Source | Github | type | Dora Project |
185+
| --------------------------------- | ----- | ------------------ | ---------------------------------------------------- | ---------- | ------------------------------------------------------- |
186+
| DJI Robomaster S1 | 550$ | SDK | https://github.com/dji-sdk/RoboMaster-SDK | Rover | https://huggingface.co/datasets/dora-rs/dora-robomaster |
187+
| DJI Robomaster EP Core | 950$ | SDK | https://github.com/dji-sdk/RoboMaster-SDK | Rover, Arm | |
188+
| DJI Tello | 100$ | | | Drone | |
189+
| BitCraze Crazyflies | 225$ | Firmware, Lib, SDK | https://github.com/bitcraze | Drone | |
190+
| AlexanderKoch-Koch/low_cost_robot | 250$ | Everything | https://github.com/AlexanderKoch-Koch/low_cost_robot | Arm | |
191+
| xArm 1S | 200$ | | | Arm | |
192+
| Wavego | 250$ | | | Quadruplet | |
193+
| AINex | 800$ | | | Humanoid | |
194+
195+
> For more: https://docs.google.com/spreadsheets/d/1YYeW2jfOIWDVgdEgqnMvltonHquQ7K8OZCrnJRELL6o/edit#gid=0
196+
98197
## Documentation
99198

100-
The full documentation is available on our website: https://dora.carsmos.ai
199+
The full documentation is available on [our website](https://dora.carsmos.ai)
101200

102201
## Discussions
103202

@@ -110,6 +209,23 @@ Feel free to reach out on any topic, issues or ideas.
110209

111210
We also have [a contributing guide](CONTRIBUTING.md).
112211

212+
## Support Matrix
213+
214+
| | dora-rs | Hoped for |
215+
| --------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
216+
| **Tier 1 Support** | Python, Rust | C, C++, ROS 2 |
217+
| **Tier 2 Support** | C, C++, ROS2 |
218+
| **Hot-reloading** | Python | Rust (https://github.com/orgs/dora-rs/discussions/360) |
219+
| **Message Format** | Arrow | Native |
220+
| **Local Communication** | Shared Memory | Custom Middleware, [zero-copy GPU IPC](https://arrow.apache.org/docs/python/api/cuda.html), intra-process channel communication |
221+
| **Remote Communication** | TCP (See: https://github.com/dora-rs/dora/issues/459) | Custom Middleware, [Zenoh](https://zenoh.io/) |
222+
| **Metrics, Tracing, and Logging** | Opentelemetry | Native logging libraries into Opentelemetry |
223+
| **Data archives** | Parquet ([dora-record](libraries/extensions/dora-record)) |
224+
| **Visualization and annotation** | OpenCV | [rerun.io](rerun.io) |
225+
| **Supported Platforms (x86)** | Windows, macOS, Linux |
226+
| **Supported Platforms (ARM)** | macOS, Linux |
227+
| **Configuration** | YAML |
228+
113229
## License
114230

115231
This project is licensed under Apache-2.0. Check out [NOTICE.md](NOTICE.md) for more information.

0 commit comments

Comments
 (0)