Move Websocket commands doc into docs directory

README.md

@@ -132,180 +132,10 @@ docker compose logs -f
 
 NOTE: Both Matter and this implementation are in an early state and features are probably missing or could be improved. See our [development notes](#development) how you can help out, with development and/or testing.
 
-### Websocket commands
-
-This list is not intended to be complete, for a complete oversight see the client implementation.
-
-**Set WiFi credentials**
-
-Inform the controller about the WiFi credentials it needs to send when commissioning a new device.
-
-```json
-{
-  "message_id": "1",
-  "command": "set_wifi_credentials",
-  "args": {
-    "ssid": "wifi-name-here",
-    "credentials": "wifi-password-here"
-  }
-}
-```
-
-**Set Thread dataset**
-
-Inform the controller about the Thread credentials it needs to use when commissioning a new device.
-
-```json
-{
-  "message_id": "1",
-  "command": "set_thread_dataset",
-  "args": {
-    "dataset": "put-credentials-here"
-  }
-}
-```
-
-**Commission with code**
-
-Commission a new device. For WiFi or Thread based devices, the credentials need to be set upfront, otherwise, commissioning will fail. Supports both QR-code syntax (MT:...) and manual pairing code as string.
-The controller will use bluetooth for the commissioning of wireless devices. If the machine running the Python Matter Server controller lacks Bluetooth support, commissioning will only work for devices already connected to the network (by cable or another controller).
-
-Matter QR-code
-```json
-{
-  "message_id": "2",
-  "command": "commission_with_code",
-  "args": {
-    "code": "MT:Y.ABCDEFG123456789"
-  }
-}
-```
-
-Manual pairing code
-```json
-{
-  "message_id": "2",
-  "command": "commission_with_code",
-  "args": {
-    "code": "35325335079",
-    "network_only": true
-  }
-}
-```
-
-**Open Commissioning window**
-
-Open a commissioning window to commission a device present on this controller to another.
-Returns code to use as discriminator.
-
-```json
-{
-  "message_id": "2",
-  "command": "open_commissioning_window",
-  "args": {
-    "node_id": 1
-  }
-}
-```
-
-**Get Nodes**
-
-Get all nodes already commissioned on the controller.
-
-```json
-{
-  "message_id": "2",
-  "command": "get_nodes"
-}
-```
-
-**Get Node**
-
-Get info of a single Node.
-
-```json
-{
-  "message_id": "2",
-  "command": "get_node",
-  "args": {
-    "node_id": 1
-  }
-}
-```
-
-**Start listening**
-
-When the start_listening command is issued, the server will dump all existing nodes. From that moment on all events (including node attribute changes) will be forwarded.
-
-```json
-{
-  "message_id": "3",
-  "command": "start_listening"
-}
-```
-
-**Send a command**
-
-Here is an example of turning on a switch (OnOff cluster)
-
-```json
-{
-  "message_id": "example",
-  "command": "device_command",
-  "args": {
-    "endpoint_id": 1,
-    "node_id": 1,
-    "payload": {},
-    "cluster_id": 6,
-    "command_name": "On"
-  }
-}
-```
-
-**Python script to send a command**
-
-Because we use the datamodels of the Matter SDK, this is a little bit more involved.
-Here is an example of turning on a switch:
-
-```python
-import json
-
-# Import the CHIP clusters
-from chip.clusters import Objects as clusters
-
-# Import the ability to turn objects into dictionaries, and vice-versa
-from matter_server.common.helpers.util import dataclass_from_dict,dataclass_to_dict
-
-command = clusters.OnOff.Commands.On()
-payload = dataclass_to_dict(command)
-
-
-message = {
-    "message_id": "example",
-    "command": "device_command",
-    "args": {
-        "endpoint_id": 1,
-        "node_id": 1,
-        "payload": payload,
-        "cluster_id": command.cluster_id,
-        "command_name": "On"
-    }
-}
-
-print(json.dumps(message, indent=2))
-```
-You can also provide parameters for the cluster commands. Here's how to change the brightness for example:
-
-```python
-command = clusters.LevelControl.Commands.MoveToLevelWithOnOff(
-  level=int(value), # provide a percentage
-  transitionTime=0, # in seconds
-)
-```
-
 ### Note when using Thread based Matter devices
 
-When communicating with Thread devices through a non-local Thread border router,
+> [!NOTE]
+> When communicating with Thread devices through a non-local Thread border router,
 your host must process ICMPv6 Router Advertisements. See the [openthread.io
 Bidirectional IPv6 Connectivity code labs](https://openthread.io/codelabs/openthread-border-router#6)
 on how-to setup your host correctly. Note that NetworkManager has its own ICMPv6
@@ -342,3 +172,7 @@ There is also a Python client library hosted in this repository (used by Home As
 The client library has a dependency on the chip/matter clusters package which contains all (Cluster) models and this package is os/platform independent. The server library depends on the Matter Core SDK (still named CHIP) which is architecture and OS specific. We build (and publish) wheels for Linux (amd64 and aarch64) to pypi but for other platforms (like Macos) you will need to build those wheels yourself using the exact same version of the SDK as we use for the clusters package. Take a look at our build script for directions: https://github.com/home-assistant-libs/chip-wheels/blob/main/.github/workflows/build.yaml
 
 To only install the client part: `pip install python-matter-server`
+
+### Websocket commands
+
+[Websocket documentation](/docs/websockets_api.md)

docs/websockets_api.md

@@ -0,0 +1,205 @@
+## Websocket documentation
+
+This list is not intended to be complete, for a complete oversight see the client implementation.
+
+## Websocket commands
+
+Here are the most frequently used commands:
+
+**Set WiFi credentials**
+
+Inform the controller about the WiFi credentials it needs to send when commissioning a new device.
+
+```json
+{
+  "message_id": "1",
+  "command": "set_wifi_credentials",
+  "args": {
+    "ssid": "wifi-name-here",
+    "credentials": "wifi-password-here"
+  }
+}
+```
+
+**Set Thread dataset**
+
+Inform the controller about the Thread credentials it needs to use when commissioning a new device.
+
+```json
+{
+  "message_id": "1",
+  "command": "set_thread_dataset",
+  "args": {
+    "dataset": "put-credentials-here"
+  }
+}
+```
+
+**Commission with code**
+
+Commission a new device. For WiFi or Thread based devices, the credentials need to be set upfront, otherwise, commissioning will fail. Supports both QR-code syntax (MT:...) and manual pairing code as string.
+The controller will use bluetooth for the commissioning of wireless devices. If the machine running the Python Matter Server controller lacks Bluetooth support, commissioning will only work for devices already connected to the network (by cable or another controller).
+
+Matter QR-code
+```json
+{
+  "message_id": "2",
+  "command": "commission_with_code",
+  "args": {
+    "code": "MT:Y.ABCDEFG123456789"
+  }
+}
+```
+
+Manual pairing code
+```json
+{
+  "message_id": "2",
+  "command": "commission_with_code",
+  "args": {
+    "code": "35325335079",
+    "network_only": true
+  }
+}
+```
+
+**Open Commissioning window**
+
+Open a commissioning window to commission a device present on this controller to another.
+Returns code to use as discriminator.
+
+```json
+{
+  "message_id": "2",
+  "command": "open_commissioning_window",
+  "args": {
+    "node_id": 1
+  }
+}
+```
+
+**Get Nodes**
+
+Get all nodes already commissioned on the controller.
+
+```json
+{
+  "message_id": "2",
+  "command": "get_nodes"
+}
+```
+
+**Get Node**
+
+Get info of a single Node.
+
+```json
+{
+  "message_id": "2",
+  "command": "get_node",
+  "args": {
+    "node_id": 1
+  }
+}
+```
+
+**Start listening**
+
+When the start_listening command is issued, the server will dump all existing nodes. From that moment on all events (including node attribute changes) will be forwarded.
+
+```json
+{
+  "message_id": "3",
+  "command": "start_listening"
+}
+```
+
+**Read an attribute**
+
+Here is an example of reading `OnOff` attribute on a switch (OnOff cluster)
+
+```json
+{
+  "message_id": "read",
+  "command": "read_attribute",
+  "args": {
+    "node_id": 1,
+     "attribute_path":"1/6/0"
+   }
+}
+```
+
+**Write an attribute**
+
+Here is an example of writing `OnTime` attribute on a switch (OnOff cluster)
+
+```json
+{
+   "message_id": "write",
+   "command":"write_attribute",
+   "args":{
+      "node_id":1,
+      "attribute_path":"1/6/16385",
+      "value": 10
+   }
+}
+```
+
+**Send a command**
+
+Here is an example of turning on a switch (OnOff cluster)
+
+```json
+{
+  "message_id": "example",
+  "command": "device_command",
+  "args": {
+    "endpoint_id": 1,
+    "node_id": 1,
+    "payload": {},
+    "cluster_id": 6,
+    "command_name": "On"
+  }
+}
+```
+
+**Python script to send a command**
+
+Because we use the datamodels of the Matter SDK, this is a little bit more involved.
+Here is an example of turning on a switch:
+
+```python
+import json
+
+# Import the CHIP clusters
+from chip.clusters import Objects as clusters
+
+# Import the ability to turn objects into dictionaries, and vice-versa
+from matter_server.common.helpers.util import dataclass_from_dict,dataclass_to_dict
+
+command = clusters.OnOff.Commands.On()
+payload = dataclass_to_dict(command)
+
+
+message = {
+    "message_id": "example",
+    "command": "device_command",
+    "args": {
+        "endpoint_id": 1,
+        "node_id": 1,
+        "payload": payload,
+        "cluster_id": command.cluster_id,
+        "command_name": "On"
+    }
+}
+
+print(json.dumps(message, indent=2))
+```
+You can also provide parameters for the cluster commands. Here's how to change the brightness for example:
+
+```python
+command = clusters.LevelControl.Commands.MoveToLevelWithOnOff(
+  level=int(value), # provide a percentage
+  transitionTime=0, # in seconds
+)
+```