# RoSys - The Robot System
RoSys provides an easy-to-use robot system.
Its purpose is similar to [ROS](https://www.ros.org/).
But RoSys is fully based on modern web technologies and focusses on mobile robotics.
The full documentation is available at [rosys.io](https://rosys.io/).
## Principles
### All Python
Python is great to write business logic.
Computation-heavy tasks are wrapped in processes, accessed through WebSockets or called via C++ bindings.
Like you would do in any other Python program.
### Modularity
You can structure your code as you please.
RoSys provides its magic without assuming a specific file structure, configuration files or enforced naming.
### Event Loop
Thanks to [asyncio](https://docs.python.org/3/library/asyncio.html) you can write your business logic without locks and mutexes.
The execution is [parallel but not concurrent](https://realpython.com/python-concurrency/) which makes it easier to read, write and debug.
In real-case scenarios this is also much faster than [ROS](https://www.ros.org/).
Its multiprocessing architecture requires too much inter-process communication.
### Web UI
Most machines need some kind of human interaction.
RoSys is built from the ground up to make sure your robot can be operated fully off the grid with any web browser.
This is done by incorporating [NiceGUI](https://nicegui.io/), a wonderful all-Python UI web framework.
It is also possible to proxy the user interface through a gateway for remote operation.
### Simulation
Robot hardware is often slower than your own computer.
To rapidly test out new behavior and algorithms, RoSys provides a simulation mode.
Here, all hardware is mocked and can even be manipulated to test wheel blockages and similar.
### Testing
You can use [pytest](https://docs.pytest.org/) to write high-level integration tests.
It is based on the above-described simulation mode and accelerates the robot's time for super fast execution.
## Architecture and Features
### Modules
RoSys modules are just Python modules which encapsulate certain functionality.
They can hold their own state, register lifecycle hooks, run methods repeatedly and subscribe to or raise [events](#events).
Modules can depend on other modules which is mostly implemented by passing them into the constructor.
### Lifecycle Hooks and Loops
Modules can register functions via `rosys.on_startup` or `rosys.on_shutdown` as well as repeatedly with a given interval with `rosys.on_repeat`.
<!-- prettier-ignore-start -->
!!! note
Note that NiceGUI's `app` object also provides methods `app.on_startup` and `app.on_shutdown`, but it is recommended to use RoSys' counterparts:
`rosys.on_startup` ensures the callback is executed _after_ persistent modules have been loaded from storage.
If you, e.g., set the `rosys.config.simulation_speed` programmatically via `app.on_startup()` instead of `rosys.on_startup`,
the change is overwritten by RoSys' `persistence.restore()`.
<!-- prettier-ignore-end -->
### Events
Modules can provide events to allow connecting otherwise separated modules of the system.
For example, one module might read sensor data and raise an event `NEW_SENSOR_DATA`, without knowing of any consumers.
Another module can register on `NEW_SENSOR_DATA` and act accordingly when being called.
### Automations
RoSys provides an `Automator` module for running "automations".
Automations are coroutines that can not only be started and stopped, but also paused and resumed, e.g. using `AutomationControls`.
Have a look at our [Click-and-drive](examples/click-and-drive.md) example.
### Persistence
Modules can register backup and restore methods to read and write their state to disk.
### Time
RoSys uses its own time which is accessible through `rosys.time`.
This way the time can advance much faster in simulation and tests if no CPU-intensive operation is performed.
To delay the execution of a coroutine, you should invoke `await rosys.sleep(seconds: float)`.
This creates a delay until the provided amount of _RoSys time_ has elapsed.
### Threading and Multiprocessing
RoSys makes extensive use of [async/await](#async) to achieve parallelism without threading or multiprocessing.
But not every piece of code you want to integrate is offering an asyncio interface.
Therefore RoSys provides two handy wrappers:
IO-bound:
If you need to read from an external device or use a non-async HTTP library like [requests](https://requests.readthedocs.io/),
you should wrap the code in a function and await it with `await rosys.run.io_bound(...)`.
CPU-bound:
If you need to do some heavy computation and want to spawn another process,
you should wrap the code in a function and await it with `await rosys.run.cpu_bound(...)`.
### Safety
Python (and Linux) is fast enough for most high-level logic, but has no realtime guarantees.
Safety-relevant behavior should therefore be put on a suitable microcontroller.
It governs the hardware of the robot and must be able to perform safety actions like triggering emergency hold etc.
We suggest to use an industrial PC with an integrated controller like the [Zauberzeug Robot Brain](https://www.zauberzeug.com/products/robot-brain).
It provides a Linux system to run RoSys, offers AI acceleration via NVidia Jetson, two integrated [ESP32](https://www.espressif.com/en/products/socs/esp32) microcontrollers and six I/O sockets with up to 24 GPIOs for digital I/Os, CAN, RS485, SPI, I2C, etc.
It also has two hardware ENABLE switches and one which is controllable via software.
To have flexible configuration for the microcontroller we created another open source project called [Lizard](https://lizard.dev/).
It is a domain-specific language interpreted by the microcontroller which enables you to write reactive hardware behavior without recompiling and flashing.
### User Interface
RoSys builds upon the open source project [NiceGUI](https://nicegui.io/) and offers many robot-related UI elements.
NiceGUI is a high-level UI framework for the web.
This means you can write all UI code in Python and the state is automatically reflected in the browser through WebSockets.
See any of our [examples](examples/steering.md).
RoSys can also be used with other user interfaces or interaction models if required, for example a completely app-based control through Bluetooth Low Energy with Flutter.
### Notifications
Modules can notify the user through `rosys.notify('message to the user')`.
When using NiceGUI, the notifications will show as snackbar messages.
The history of notifications is stored in the list `rosys.notifications`.
## Contributing
Thank you for your interest in contributing to RoSys!
We are thrilled to have you on board and appreciate your efforts to make this project even better.
As a growing open-source project, we understand that it takes a community effort to achieve our goals.
That's why we welcome all kinds of contributions, no matter how small or big they are.
Whether it's adding new features, fixing bugs, improving documentation, or suggesting new ideas,
we believe that every contribution counts and adds value to our project.
We have provided a detailed guide on how to contribute to RoSys in our
[CONTRIBUTING.md](https://github.com/zauberzeug/rosys/blob/main/CONTRIBUTING.md) file.
We encourage you to read it carefully before making any contributions to ensure that your work aligns with the project's goals and standards.
If you have any questions or need help with anything, please don't hesitate to reach out to us.
We are always here to support and guide you through the contribution process.
Raw data
{
"_id": null,
"home_page": "https://github.com/zauberzeug/rosys",
"name": "rosys",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "robot, framework, automation, control, steer",
"author": "Zauberzeug GmbH",
"author_email": "info@zauberzeug.com",
"download_url": "https://files.pythonhosted.org/packages/85/ad/69ad284ae9b7ff8704180010511bab57e1c8993c394c12623b19dba98939/rosys-0.21.0.tar.gz",
"platform": null,
"description": "# RoSys - The Robot System\n\nRoSys provides an easy-to-use robot system.\nIts purpose is similar to [ROS](https://www.ros.org/).\nBut RoSys is fully based on modern web technologies and focusses on mobile robotics.\n\nThe full documentation is available at [rosys.io](https://rosys.io/).\n\n## Principles\n\n### All Python\n\nPython is great to write business logic.\nComputation-heavy tasks are wrapped in processes, accessed through WebSockets or called via C++ bindings.\nLike you would do in any other Python program.\n\n### Modularity\n\nYou can structure your code as you please.\nRoSys provides its magic without assuming a specific file structure, configuration files or enforced naming.\n\n### Event Loop\n\nThanks to [asyncio](https://docs.python.org/3/library/asyncio.html) you can write your business logic without locks and mutexes.\nThe execution is [parallel but not concurrent](https://realpython.com/python-concurrency/) which makes it easier to read, write and debug.\nIn real-case scenarios this is also much faster than [ROS](https://www.ros.org/).\nIts multiprocessing architecture requires too much inter-process communication.\n\n### Web UI\n\nMost machines need some kind of human interaction.\nRoSys is built from the ground up to make sure your robot can be operated fully off the grid with any web browser.\nThis is done by incorporating [NiceGUI](https://nicegui.io/), a wonderful all-Python UI web framework.\nIt is also possible to proxy the user interface through a gateway for remote operation.\n\n### Simulation\n\nRobot hardware is often slower than your own computer.\nTo rapidly test out new behavior and algorithms, RoSys provides a simulation mode.\nHere, all hardware is mocked and can even be manipulated to test wheel blockages and similar.\n\n### Testing\n\nYou can use [pytest](https://docs.pytest.org/) to write high-level integration tests.\nIt is based on the above-described simulation mode and accelerates the robot's time for super fast execution.\n\n## Architecture and Features\n\n### Modules\n\nRoSys modules are just Python modules which encapsulate certain functionality.\nThey can hold their own state, register lifecycle hooks, run methods repeatedly and subscribe to or raise [events](#events).\nModules can depend on other modules which is mostly implemented by passing them into the constructor.\n\n### Lifecycle Hooks and Loops\n\nModules can register functions via `rosys.on_startup` or `rosys.on_shutdown` as well as repeatedly with a given interval with `rosys.on_repeat`.\n\n<!-- prettier-ignore-start -->\n!!! note\n Note that NiceGUI's `app` object also provides methods `app.on_startup` and `app.on_shutdown`, but it is recommended to use RoSys' counterparts:\n `rosys.on_startup` ensures the callback is executed _after_ persistent modules have been loaded from storage.\n If you, e.g., set the `rosys.config.simulation_speed` programmatically via `app.on_startup()` instead of `rosys.on_startup`,\n the change is overwritten by RoSys' `persistence.restore()`.\n<!-- prettier-ignore-end -->\n\n### Events\n\nModules can provide events to allow connecting otherwise separated modules of the system.\nFor example, one module might read sensor data and raise an event `NEW_SENSOR_DATA`, without knowing of any consumers.\nAnother module can register on `NEW_SENSOR_DATA` and act accordingly when being called.\n\n### Automations\n\nRoSys provides an `Automator` module for running \"automations\".\nAutomations are coroutines that can not only be started and stopped, but also paused and resumed, e.g. using `AutomationControls`.\nHave a look at our [Click-and-drive](examples/click-and-drive.md) example.\n\n### Persistence\n\nModules can register backup and restore methods to read and write their state to disk.\n\n### Time\n\nRoSys uses its own time which is accessible through `rosys.time`.\nThis way the time can advance much faster in simulation and tests if no CPU-intensive operation is performed.\nTo delay the execution of a coroutine, you should invoke `await rosys.sleep(seconds: float)`.\nThis creates a delay until the provided amount of _RoSys time_ has elapsed.\n\n### Threading and Multiprocessing\n\nRoSys makes extensive use of [async/await](#async) to achieve parallelism without threading or multiprocessing.\nBut not every piece of code you want to integrate is offering an asyncio interface.\nTherefore RoSys provides two handy wrappers:\n\nIO-bound:\nIf you need to read from an external device or use a non-async HTTP library like [requests](https://requests.readthedocs.io/),\nyou should wrap the code in a function and await it with `await rosys.run.io_bound(...)`.\n\nCPU-bound:\nIf you need to do some heavy computation and want to spawn another process,\nyou should wrap the code in a function and await it with `await rosys.run.cpu_bound(...)`.\n\n### Safety\n\nPython (and Linux) is fast enough for most high-level logic, but has no realtime guarantees.\nSafety-relevant behavior should therefore be put on a suitable microcontroller.\nIt governs the hardware of the robot and must be able to perform safety actions like triggering emergency hold etc.\n\nWe suggest to use an industrial PC with an integrated controller like the [Zauberzeug Robot Brain](https://www.zauberzeug.com/products/robot-brain).\nIt provides a Linux system to run RoSys, offers AI acceleration via NVidia Jetson, two integrated [ESP32](https://www.espressif.com/en/products/socs/esp32) microcontrollers and six I/O sockets with up to 24 GPIOs for digital I/Os, CAN, RS485, SPI, I2C, etc.\nIt also has two hardware ENABLE switches and one which is controllable via software.\n\nTo have flexible configuration for the microcontroller we created another open source project called [Lizard](https://lizard.dev/).\nIt is a domain-specific language interpreted by the microcontroller which enables you to write reactive hardware behavior without recompiling and flashing.\n\n### User Interface\n\nRoSys builds upon the open source project [NiceGUI](https://nicegui.io/) and offers many robot-related UI elements.\nNiceGUI is a high-level UI framework for the web.\nThis means you can write all UI code in Python and the state is automatically reflected in the browser through WebSockets.\nSee any of our [examples](examples/steering.md).\n\nRoSys can also be used with other user interfaces or interaction models if required, for example a completely app-based control through Bluetooth Low Energy with Flutter.\n\n### Notifications\n\nModules can notify the user through `rosys.notify('message to the user')`.\nWhen using NiceGUI, the notifications will show as snackbar messages.\nThe history of notifications is stored in the list `rosys.notifications`.\n\n## Contributing\n\nThank you for your interest in contributing to RoSys!\nWe are thrilled to have you on board and appreciate your efforts to make this project even better.\n\nAs a growing open-source project, we understand that it takes a community effort to achieve our goals.\nThat's why we welcome all kinds of contributions, no matter how small or big they are.\nWhether it's adding new features, fixing bugs, improving documentation, or suggesting new ideas,\nwe believe that every contribution counts and adds value to our project.\n\nWe have provided a detailed guide on how to contribute to RoSys in our\n[CONTRIBUTING.md](https://github.com/zauberzeug/rosys/blob/main/CONTRIBUTING.md) file.\nWe encourage you to read it carefully before making any contributions to ensure that your work aligns with the project's goals and standards.\n\nIf you have any questions or need help with anything, please don't hesitate to reach out to us.\nWe are always here to support and guide you through the contribution process.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modular Robot System With Elegant Automation Capabilities",
"version": "0.21.0",
"project_urls": {
"Homepage": "https://github.com/zauberzeug/rosys",
"Repository": "https://github.com/zauberzeug/rosys"
},
"split_keywords": [
"robot",
" framework",
" automation",
" control",
" steer"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bda46cf4bbb10f1ffc011b8f93db833ec37930f575fad390c1947bf5ff1535d0",
"md5": "5d7a920f1d08808187aae21578c4c7ba",
"sha256": "e86009f5ed7f04b546bfb69737a1868b6086bb4d0cc010b1b9341b8e399da626"
},
"downloads": -1,
"filename": "rosys-0.21.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5d7a920f1d08808187aae21578c4c7ba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 317144,
"upload_time": "2024-12-19T12:36:02",
"upload_time_iso_8601": "2024-12-19T12:36:02.563510Z",
"url": "https://files.pythonhosted.org/packages/bd/a4/6cf4bbb10f1ffc011b8f93db833ec37930f575fad390c1947bf5ff1535d0/rosys-0.21.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "85ad69ad284ae9b7ff8704180010511bab57e1c8993c394c12623b19dba98939",
"md5": "881b5175148300a3e53cce1ac70f8db8",
"sha256": "25d8aa66297dce72561c54bf60f85057a05e1f053dde7064cb044bc89ce2745e"
},
"downloads": -1,
"filename": "rosys-0.21.0.tar.gz",
"has_sig": false,
"md5_digest": "881b5175148300a3e53cce1ac70f8db8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 251900,
"upload_time": "2024-12-19T12:36:05",
"upload_time_iso_8601": "2024-12-19T12:36:05.393339Z",
"url": "https://files.pythonhosted.org/packages/85/ad/69ad284ae9b7ff8704180010511bab57e1c8993c394c12623b19dba98939/rosys-0.21.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 12:36:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zauberzeug",
"github_project": "rosys",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rosys"
}
JSON
