From 9d80466726a2adde7ab87bd85cebbc09c20c7a0f Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Thu, 20 Feb 2025 22:30:58 +0100 Subject: [PATCH 1/2] Add WebSocket topic filter docs Refs https://github.com/openhab/openhab-core/pull/4550. Signed-off-by: Florian Hotze --- configuration/websocket.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/configuration/websocket.md b/configuration/websocket.md index 7f1654b579..1e331987da 100644 --- a/configuration/websocket.md +++ b/configuration/websocket.md @@ -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 select and 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. @@ -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 From 73a825fd71385130dd325e5e663bccc420cc0723 Mon Sep 17 00:00:00 2001 From: Florian Hotze Date: Thu, 20 Feb 2025 22:32:12 +0100 Subject: [PATCH 2/2] Minor rewording Signed-off-by: Florian Hotze --- configuration/websocket.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/configuration/websocket.md b/configuration/websocket.md index 1e331987da..8c1220831f 100644 --- a/configuration/websocket.md +++ b/configuration/websocket.md @@ -121,7 +121,7 @@ It is recommended to at least set a source filter for the client itself to preve #### Filter by topic (`openhab/websocket/filter/topic`) -Topic filters can be used to select and exclude events of a specific topic from the event stream. +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`.