feat: add IPC WebSocket example and enhance IPC client with device discovery and actions

Author: DennisMoschina

README.md

@@ -34,6 +34,33 @@ ppg_red = dataset.ppg["ppg.red"]
 audio_df = dataset.get_audio_dataframe()
 ```
 
+## IPC WebSocket Example
+
+```python
+import asyncio
+from open_wearable import OpenWearableIPCClient
+
+
+async def main() -> None:
+    async with OpenWearableIPCClient() as client:
+        await client.start_scan()
+        devices = await client.get_discovered_devices()
+        wearable = client.wearable(devices[0].id)
+
+        await wearable.connect()
+        await wearable.actions.synchronize_time()
+
+        sensors = await wearable.actions.list_sensors()
+        stream = await wearable.streams.sensor_values(sensor_id=sensors[0].sensor_id)
+        async for event in stream:
+            print(event.data)
+            break
+        await stream.close()
+
+
+asyncio.run(main())
+```
+
 ## Documentation
 
 - [Documentation index](docs/README.md)

docs/api-reference.md

@@ -13,6 +13,63 @@ Primary internal package layers:
 - `open_wearable.data`
 - `open_wearable.ipc`
 
+## IPC Client (`open_wearable.ipc`)
+
+`OpenWearableIPCClient` is an async JSON-RPC style client for
+`ws://127.0.0.1:8765/ws` by default.
+
+### Connection Lifecycle
+
+```python
+async with OpenWearableIPCClient() as client:
+    await client.ping()
+```
+
+### Discovery and Connection
+
+- `start_scan(check_and_request_permissions=True)`
+- `start_scan_async(check_and_request_permissions=True) -> dict`
+- `start_scan_stream(check_and_request_permissions=True) -> StreamSubscription`
+- `get_discovered_devices() -> list[DiscoveredDevice]`
+- `connect_device(device_id, connected_via_system=False) -> WearableSummary`
+- `connect_system_devices(ignored_device_ids=None) -> list[WearableSummary]`
+- `list_connected() -> list[WearableSummary]`
+- `disconnect(device_id)`
+
+### Action Sugar
+
+- `client.synchronize_time(device_id)`
+- `client.list_sensors(device_id) -> list[SensorInfo]`
+- `client.list_sensor_configurations(device_id) -> list[SensorConfiguration]`
+- `client.set_sensor_configuration(device_id, configuration_name=..., value_key=...)`
+
+Per-device handle:
+
+```python
+wearable = client.wearable(device_id)
+await wearable.connect()
+await wearable.actions.synchronize_time()
+```
+
+### Stream Sugar
+
+Use the typed stream helpers:
+
+```python
+stream = await wearable.streams.sensor_values(sensor_id="accelerometer_0")
+async for event in stream:
+    print(event.data)
+```
+
+Other helpers:
+
+- `wearable.streams.sensor_configuration()`
+- `wearable.streams.button_events()`
+- `wearable.streams.battery_percentage()`
+- `wearable.streams.battery_power_status()`
+- `wearable.streams.battery_health_status()`
+- `wearable.streams.battery_energy_status()`
+
 ## `SensorDataset`
 
 High-level API for loading and analyzing a single `.oe` recording.

src/open_wearable/__init__.py

@@ -1,24 +1,40 @@
 from .data import SensorDataset, load_recordings
 from .ipc import (
+    DiscoveredDevice,
     IPCClosedError,
     IPCError,
     IPCProtocolError,
     IPCRemoteError,
     IPCStreamError,
     OpenWearableIPCClient,
+    SensorConfiguration,
+    SensorConfigurationValue,
+    SensorInfo,
     StreamEvent,
     StreamSubscription,
+    Wearable,
+    WearableActions,
+    WearableStreams,
+    WearableSummary,
 )
 
 __all__ = [
+    "DiscoveredDevice",
     "IPCClosedError",
     "IPCError",
     "IPCProtocolError",
     "IPCRemoteError",
     "IPCStreamError",
     "OpenWearableIPCClient",
     "SensorDataset",
+    "SensorConfiguration",
+    "SensorConfigurationValue",
+    "SensorInfo",
     "StreamEvent",
     "StreamSubscription",
+    "Wearable",
+    "WearableActions",
+    "WearableStreams",
+    "WearableSummary",
     "load_recordings",
 ]

src/open_wearable/ipc/__init__.py

@@ -1,20 +1,41 @@
-from .client import OpenWearableIPCClient, StreamSubscription
+from .client import (
+    OpenWearableIPCClient,
+    StreamSubscription,
+    Wearable,
+    WearableActions,
+    WearableStreams,
+)
 from .errors import (
     IPCClosedError,
     IPCError,
     IPCProtocolError,
     IPCRemoteError,
     IPCStreamError,
 )
-from .models import StreamEvent
+from .models import (
+    DiscoveredDevice,
+    SensorConfiguration,
+    SensorConfigurationValue,
+    SensorInfo,
+    StreamEvent,
+    WearableSummary,
+)
 
 __all__ = [
+    "DiscoveredDevice",
     "IPCClosedError",
     "IPCError",
     "IPCProtocolError",
     "IPCRemoteError",
     "IPCStreamError",
     "OpenWearableIPCClient",
+    "SensorConfiguration",
+    "SensorConfigurationValue",
+    "SensorInfo",
     "StreamEvent",
     "StreamSubscription",
+    "Wearable",
+    "WearableActions",
+    "WearableStreams",
+    "WearableSummary",
 ]