Skip to content

docs: rewrite README in Simplified Technical English #121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JarbasAl merged 1 commit into from
Jul 31, 2026
Merged

docs: rewrite README in Simplified Technical English #121

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
57 changes: 32 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,35 @@
# OVOS GUI MessageBus

GUI messagebus service, manages GUI state and implements the [gui protocol](./protocol.md)
`ovos-gui` is the GUI messagebus service for ovos-core. It manages GUI state and implements the [GUI protocol](./protocol.md).

GUI clients (the application that actually draws the GUI) connect to this service
GUI clients (the applications that draw the GUI) connect to this service over a websocket.

## Configuration

# Configuration

under mycroft.conf
Configure the service under `mycroft.conf`.

```javascript
{
"gui": {
// Override: SYSTEM (set by specific enclosures)
// Uncomment or add "idle_display_skill" to set initial homescreen
// Uncomment or add "idle_display_skill" to set the initial homescreen
// "idle_display_skill": "skill-ovos-homescreen.openvoiceos",

// Extensions are plugins that provide additional GUI platform support for specific devices
// eg, if using ovos-shell you should set extension to "ovos-gui-plugin-shell-companion"
// Extensions are plugins that add GUI platform support for specific devices.
// For example, set extension to "ovos-gui-plugin-shell-companion" if you use ovos-shell.
"extension": "generic",

// Default generic extension can provide homescreen functionality if enabled
// The default generic extension can provide homescreen functionality if enabled.
"generic": {
"homescreen_supported": false
},
// Optionally specify a default qt version for connected clients that don't report it

// Optionally set a default QT version for connected clients that do not report one.
// NOTE: currently only QT5 clients exist
"default_qt_version": 5
},
// The GUI messagebus websocket. Once port is created per connected GUI

// The GUI messagebus websocket. One port is created per connected GUI.
"gui_websocket": {
"host": "0.0.0.0",
"base_port": 18181,
Expand All @@ -40,25 +39,33 @@ under mycroft.conf
}
```

# Plugins
## Plugins

Plugins add platform-specific GUI functionality, such as showing a homescreen or closing a window.

You usually do not need any of these plugins unless a GUI client application tells you to install one.

plugins provide platform specific GUI functionality, such as determining when to show a homescreen or close a window
- [OpenVoiceOS/ovos-gui-plugin-shell-companion](https://github.com/OpenVoiceOS/ovos-gui-plugin-shell-companion)
- [OpenVoiceOS/ovos-gui-plugin-mobile](https://github.com/OpenVoiceOS/ovos-gui-plugin-mobile)
- [OpenVoiceOS/ovos-gui-plugin-plasmoid](https://github.com/OpenVoiceOS/ovos-gui-plugin-plasmoid)
- [OpenVoiceOS/ovos-gui-plugin-bigscreen](https://github.com/OpenVoiceOS/ovos-gui-plugin-bigscreen)

you should usually not need any of these unless instructed to install it from a GUI client application
## Related projects

- https://github.com/OpenVoiceOS/ovos-gui-plugin-shell-companion
- https://github.com/OpenVoiceOS/ovos-gui-plugin-mobile
- https://github.com/OpenVoiceOS/ovos-gui-plugin-plasmoid
- https://github.com/OpenVoiceOS/ovos-gui-plugin-bigscreen
- [OpenVoiceOS/ovos-core](https://github.com/OpenVoiceOS/ovos-core) — the assistant runtime that this service runs alongside.
- [OpenVoiceOS/ovos-gui-api-client](https://github.com/OpenVoiceOS/ovos-gui-api-client) — a Python client library for this service.
- [OpenVoiceOS/ovos-shell](https://github.com/OpenVoiceOS/ovos-shell) — a reference GUI client that connects to this service.

## Limitations

# Limitations
Skills and other OVOS components populate GUI resource files under the local OVOS cache directory. GUI client applications must be able to reach these files.

gui resources files are populated under `~/.cache/mycrot/ovos-gui` by skills and other OVOS components and are expectd to be accessible by GUI client applications
This means a GUI client must run on the same machine as `ovos-gui`, or implement its own access to the resource files. Resolving page names to URIs is the responsibility of the client application.

This means GUI clients are expected to be running under the same machine or implement their own access to the resource files (resolving page names to uris is the client app responsibility)
> TODO: a new repository will host the removed GUI file server, to serve resource files from the cache directory to client apps.

> TODO: new repository with the removed GUI file server, serve files from `~/.cache/mycrot/ovos-gui` to be handled by client apps
In a container setup, mount a shared volume between `ovos-gui`, the skills service, and the GUI client apps.

In case of containers a shared volume should be mounted between ovos-gui, skills and gui client apps
## License

This project is licensed under the [Apache License 2.0](./LICENSE.md).
Loading