Skip to content
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

Add WebSocket topic filter docs #2465

Merged
merged 2 commits into from
Feb 20, 2025
+38 −0
Merged

Add WebSocket topic filter docs #2465

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9d80466
Add WebSocket topic filter docs
florian-h05 Feb 20, 2025
73a825f
Minor rewording
florian-h05 Feb 20, 2025
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
38 changes: 38 additions & 0 deletions configuration/websocket.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,43 @@ A new filter message always overrides the settings before.
The default setting is no filter, i.e. all events from all sources.
It is recommended to at least set a source filter for the client itself to prevent event reflection.

#### Filter by topic (`openhab/websocket/filter/topic`)

Topic filters can be used to include and/or exclude events of a specific topic from the event stream.
They can be applied both inclusive and exclusive, and provide API compatibility with the existing topic filter functionality of the SSE event stream.

Topics usually start with `openhab` and are split into several segments separated by an `/`, e.g. `openhab/items/MyItem/command` to listen to commands to `MyItem`.
You may use `*` as a wildcard for a topic segment.
To exclude a topic, start it with a `!`.

When sending only exclude topics, all events except those excluded are sent.
In other cases, only events of the selected topics are sent, whereas exclude topics can be used to filter out a subset of the selected events.

The payload of the event contains a list of string with the topics:

```json
{
"type": "WebSocketEvent",
"topic": "openhab/websocket/filter/topic",
"payload": "[\"openhab/items/*/command\", \"!openhab/items/MyItem/command\"]",
"source": "WebSocketTestInstance",
"eventId": "10"
}
```

This example will only send `ItemCommandEvents` for all Items except `MyItem`.

The reception is acknowledged with the filter that is applied:

```json
{
"type": "WebSocketEvent",
"topic": "openhab/websocket/filter/topic",
"payload": "[\"openhab/items/*/command\", \"!openhab/items/MyItem/command\"]",
"eventId": "10"
}
```

#### Filter by source (`openhab/websocket/filter/source`)

Source filters can be used to remove events from a specific source from the event stream.
Expand Down Expand Up @@ -152,6 +189,7 @@ The reception is acknowledged with the filter that is applied:

Type filters are used to select a specific sub-set of all available events.
They are a inclusive, that means only those event types sent in the filter message are sent.

The payload of the event contains a list of strings with the event names:

```json
Expand Down