mirror of
https://github.com/odriverobotics/ODrive.git
synced 2026-09-26 21:10:05 +08:00
update fibre readme to better reflect the current status
This commit is contained in:
Samuel Sadok
+85
-47
@@ -20,69 +20,107 @@ In particular:
|
||||
worry about breaking other applications. With Fibre's object model, the
|
||||
most common updates like adding methods, properties or arguments won't
|
||||
break anything. Sometimes you can get away with removing methods if they
|
||||
weren't used by other programs.
|
||||
weren't used by other programs. **This is not implemented yet.**
|
||||
|
||||
## Current Status ##
|
||||
|
||||
## Architecture ##
|
||||
The project is in an early stage and the focus so far was to get a minimum working implementation.
|
||||
|
||||
Note that this is not yet representative for the existing code.
|
||||
* **C++**: Currently only supports the server side (i.e. publishing local objects). The C++ library comes with builtin support for TCP and UDP transport layers on Posix platforms. The library can easily be used with user provided transport layers.
|
||||
|
||||
* **Python**: Currently only supports the client side (i.e. using remote objects). The Python library comes with builtin support for TCP, UDP, USB and UART transport layers.
|
||||
|
||||
Support for more languages (most importantly JavaScript) will be added once the protocol matures. Feel free to add your contribution.
|
||||
|
||||
## Show me some code
|
||||
|
||||
Consider this program:
|
||||
|
||||
```
|
||||
class TestClass {
|
||||
public:
|
||||
float property1;
|
||||
float property2;
|
||||
|
||||
/--------------\ /--------------\ /---------------------------\
|
||||
| Light Toggle | | Driver for | | LED strip -> simple light |
|
||||
| Applet | | Built-in LED | | adaptor |
|
||||
\--------------/ \--------------/ \---------------------------/
|
||||
| | |
|
||||
/-------------------------------------------------------\
|
||||
| Local Fibre Hub |
|
||||
\-------------------------------------------------------/
|
||||
| |
|
||||
/-----------\ /-----------\
|
||||
| USB relay | | UDP relay |
|
||||
\-----------/ \-----------/
|
||||
| |
|
||||
/---------------\ |
|
||||
| fibre-enabled | /-----------\
|
||||
| desk lamp | | UDP relay |
|
||||
\---------------/ \-----------/
|
||||
|
|
||||
/------------------\
|
||||
| remote fibre hub |
|
||||
\------------------/
|
||||
|
|
||||
/------------------\
|
||||
| LED strip driver |
|
||||
\------------------/
|
||||
float set_both(float arg1, float arg2) {
|
||||
property1 = arg1;
|
||||
property2 = arg2;
|
||||
return property1 + property2;
|
||||
}
|
||||
};
|
||||
|
||||
|
||||
int main() {
|
||||
TestClass test_object = TestClass();
|
||||
|
||||
while (1) {
|
||||
printf("test_object.property1: %f\n", test_object.property1);
|
||||
usleep(1000000 / 5); // 5 Hz
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Say you want to publish `test_object` so that a remote Fibre node can use it.
|
||||
|
||||
## Compatibility ##
|
||||
1. Add includes
|
||||
```C++
|
||||
#include <fibre/protocol.hpp>
|
||||
#include <fibre/posix_tcp.hpp>
|
||||
```
|
||||
1. Add Fibre export definitions to the exported class
|
||||
```C++
|
||||
class TestClass {
|
||||
[...]
|
||||
FIBRE_EXPORTS(TestClass,
|
||||
make_protocol_property("property1", &property1),
|
||||
make_protocol_property("property2", &property2),
|
||||
make_protocol_function("set_both", obj, &TestClass::set_both, "arg1", "arg2")
|
||||
);
|
||||
};
|
||||
```
|
||||
Note: in the future this will be generated from a YAML file using automatic code generation.
|
||||
|
||||
| | Linux |
|
||||
|------------------|:-----:|
|
||||
| **UDP** | yes |
|
||||
| **raw TCP** | yes |
|
||||
| **WebSocks** | |
|
||||
| **HTTP** | |
|
||||
| **Bluetooth LE** | |
|
||||
| **USB** | |
|
||||
| **Serial** | |
|
||||
| **CAN** | |
|
||||
| **SPI** | |
|
||||
| **I2C** | |
|
||||
1. Publish the object on Fibre
|
||||
```C++
|
||||
auto definitions = test_object.fibre_definitions;
|
||||
fibre_publish(definitions);
|
||||
```
|
||||
Note: currently you must publish all objects at once. This will be fixed in the future.
|
||||
|
||||
1. Start the TCP server
|
||||
```C++
|
||||
std::thread server_thread_tcp(serve_on_tcp, 9910);
|
||||
```
|
||||
Note: this step will be replaced by a simple `fibre_start()` call in the future. All builtin transport layers then will be started automatically.
|
||||
|
||||
## Projects based on Fibre ##
|
||||
## Adding Fibre to your project ##
|
||||
|
||||
[lightd](https://github.com/samuelsadok/lightd) Service that can be run on a Raspberry Pi (or similar) to control RGB LED strips
|
||||
We recommend Git subtrees if you want to include the Fibre source code in another project.
|
||||
Other contributors don't need to know anything about subtrees, to them the Fibre repo will be like any other normal directory.
|
||||
|
||||
## Roadmap ##
|
||||
#### Adding the repo
|
||||
```
|
||||
git remote add fibre-origin git@github.com:samuelsadok/fibre.git
|
||||
git fetch fibre-origin
|
||||
git subtree add --prefix=fibre --squash fibre-origin master
|
||||
```
|
||||
Instead of using the upstream remote, you might want to use your own fork for greater flexibility.
|
||||
|
||||
- Add compatibility with Windows, macOS, iOS, Android
|
||||
- Add bindings for JavaScript, C#
|
||||
- CI to test all items on the feature matrix
|
||||
#### Pulling updates from upstream
|
||||
```
|
||||
git subtree pull --prefix=fibre --squash fibre-origin master
|
||||
```
|
||||
|
||||
#### Contributing changes back to upstream
|
||||
This requires push access to `fibre-origin`.
|
||||
```
|
||||
git subtree push --prefix=fibre fibre-origin master
|
||||
```
|
||||
|
||||
## Projects using Fibre ##
|
||||
|
||||
- [ODrive](https://github.com/madcowswe/ODrive): High performance motor control
|
||||
- [lightd](https://github.com/samuelsadok/lightd): Service that can be run on a Raspberry Pi (or similar) to control RGB LED strips
|
||||
|
||||
## Contribute ##
|
||||
|
||||
|
||||
Reference in New Issue
Block a user