diff --git a/docs/api-xcb-provider-xorg.md b/docs/api-xcb-provider-xorg.md index c4afc97..866361f 100644 --- a/docs/api-xcb-provider-xorg.md +++ b/docs/api-xcb-provider-xorg.md @@ -11,13 +11,13 @@ or entire screens managed by the Xorg server. The general format of a DAP spec for the `xcb` stim-buff-api with the `xorg` provider is: ``` -sensor-type|dev-identifier|stim-iface-api|xcb(stim-buff-api-params)|xorg(provider-params)|deviceSelector +sensor-type|dev-identifier|quale-iface-api|xcb(stim-buff-api-params)|xorg(provider-params)|deviceSelector ``` * `sensor-type` is always either '`+idev`' (interoceptor), '`+edev`' (extrospector), or '`+adev`' (actuator). * `dev-identifier` is a user-defined name for this specific device instance. -* `stim-iface-api` is the name of the StimIface library that should be used to +* `quale-iface-api` is the name of the StimIface library that should be used to process the data from the stim buffer. * `stim-buff-api` is `xcb` in this case, and the `stim-buff-api-params` in parentheses may be omitted, in which case the parentheses will be empty, but the parentheses @@ -98,25 +98,25 @@ xcb(dev-string)|My\ Exact\ Window\ Name ### To attach a specific window by name (substring match): ``` -+edev|my-window|visual-stimiface|xcb(dev-substring)|xorg(display=0|screen=0)|my-window ++edev|my-window|visual-qualeiface|xcb(dev-substring)|xorg(display=0|screen=0)|my-window ``` This will attach to a window whose name contains "my-window" as a substring. ### To attach a specific window by exact name: ``` -+edev|my-window|visual-stimiface|xcb(dev-string)|xorg(display=0|screen=0)|My\ Exact\ Window\ Name ++edev|my-window|visual-qualeiface|xcb(dev-string)|xorg(display=0|screen=0)|My\ Exact\ Window\ Name ``` This will attach to a window whose name exactly matches "My Exact Window Name". ### To attach a specific window by numeric ID: ``` -+edev|my-window|visual-stimiface|xcb(dev-id)|xorg(display=0|screen=0)|123456 ++edev|my-window|visual-qualeiface|xcb(dev-id)|xorg(display=0|screen=0)|123456 ``` This will attach to a window with the numeric ID `123456`. ### To attach the entire screen: ``` -+edev|my-screen|visual-stimiface|xcb()|xorg(display=0|screen=0)|all ++edev|my-screen|visual-qualeiface|xcb()|xorg(display=0|screen=0)|all ``` This will attach to the entire screen `0` of display `0`. diff --git a/docs/deviceAttachmentPipelineSpec.md b/docs/deviceAttachmentPipelineSpec.md index 32a771b..8ed3636 100644 --- a/docs/deviceAttachmentPipelineSpec.md +++ b/docs/deviceAttachmentPipelineSpec.md @@ -23,11 +23,11 @@ perceptual inputs -- like your own sense organs. For example, if you attach a camera as a sensor, salmanoff will experience it in the same way that you experience the visual sense data from your eyes. -## StimIface (Stimulus Interface): +## QualeIface (Quale Interface): -A StimIface is a **Stim**ulus **I**nter**face** library that connects to a +A QualeIface is a **Quale** **I**nter**face** library that connects to a particular stim buffer and allows the mind to process the stim features -presented in the device's stim buffers. StimIface libraries replace the +presented in the device's stim buffers. QualeIface libraries replace the previous notion of an implexor. They provide the interface between raw device data and the mind's processing capabilities. @@ -35,7 +35,7 @@ data and the mind's processing capabilities. The general format of a DAP specification is: ``` -sensor-type|dev-identifier|stim-iface-api|stim-buff-api(api-params)|provider(provider-params)|dev-selector +sensor-type|dev-identifier|quale-iface-api|stim-buff-api(api-params)|provider(provider-params)|dev-selector ``` * `sensor-type` is always either '`+idev`' (interoceptor), '`+edev`' @@ -44,7 +44,7 @@ sensor-type|dev-identifier|stim-iface-api|stim-buff-api(api-params)|provider(pro This represents a logical device that can be accessed through multiple providers and may expose multiple stim features. In a sense it's like a sense organ or sense modality. -* `stim-iface-api` is the name of the StimIface library that should be used to +* `quale-iface-api` is the name of the QualeIface library that should be used to process the data from the stim buffer. This replaces the previous implexor concept. * `stim-buff-api` is the interface that provides access to a specific stim @@ -66,7 +66,7 @@ If there's more than one parameter item in a list of `stim-buff-api-params` or `provider-params`, then the individual items in a list of `stim-buff-api-param` or `provider-params` should be separated by the h-bar character (`|`). E.g: ``` -+edev|soundcard0|audio-stimiface|alsa-audio(shmem|param2|param3)|alsa()|cardname ++edev|soundcard0|audio-qualeiface|alsa-audio(shmem|param2|param3)|alsa()|cardname ``` Each parameter must be in one of these forms: @@ -78,9 +78,9 @@ Each parameter must be in one of these forms: The `stim-buff-api-params` should **never** include options related to the stim buffer's type or format. The `stim-buff-api` must read and infer such -configuration details from the `stim-iface-api` portion of the DAP spec, and +configuration details from the `quale-iface-api` portion of the DAP spec, and configure itself accordingly to enable connection by the specified -stim-iface library in the way that it has been configured. +quale-iface library in the way that it has been configured. `stim-buff-api-params` are for options that are: - Device-specific (not modality-wide) @@ -148,33 +148,33 @@ required to effectuate the stim-buff controls. ### To attach a particular window from a window manager: ``` -+edev|my-window|visual-stimiface|wayland()|wayland(server-socket)|window0 ++edev|my-window|visual-qualeiface|wayland()|wayland(server-socket)|window0 ``` Connect to the Wayland server that's listening on `server-socket`, using the `wayland` stim-buff-api. Ask that Wayland server to give salmanoff read-access to all of the frames composited into the window buffer for `window0`. Use salmanoff's -`visual-stimiface` to process the visual data from that `window0`'s compositor buffer. +`visual-qualeiface` to process the visual data from that `window0`'s compositor buffer. ### To attach a window manager's entire rendered desktop: ``` -+edev|my-desktop|visual-stimiface|wayland()|wayland(listen-socket)|all ++edev|my-desktop|visual-qualeiface|wayland()|wayland(listen-socket)|all ``` In most cases, this is basically the same as attempting to attach all of the underlying GFX server's output. Connect to the Wayland server that's listening on `listen-socket`, using the `wayland` stim-buff-api. Ask that Wayland server to give salmanoff read-access to the -entire compositor framebuffer. Use salmanoff's `visual-stimiface` to process the visual data from +entire compositor framebuffer. Use salmanoff's `visual-qualeiface` to process the visual data from that Wayland server's compositor buffer. ### To attach all of an Xorg server's gfx output to all screens: ``` -+edev|my-xorg-display|visual-stimiface|x11()|xorg(listen-socket)|all ++edev|my-xorg-display|visual-qualeiface|x11()|xorg(listen-socket)|all ``` Connect to the Xorg server that's listening on `listen-socket`, using the `x11` stim-buff-api. Ask that Xorg server to let Salmanoff read out all of the frames written -out to all screens. Use salmanoff's `visual-stimiface` to process the visual data from the +out to all screens. Use salmanoff's `visual-qualeiface` to process the visual data from the server's gfx framebuffer. In most cases, this is basically the same as attempting to attach all of the @@ -186,11 +186,11 @@ WM's output. ### To attach all of an Xorg server's gfx output to a particular screen: ``` -+edev|my-screen|visual-stimiface|x11()|xorg(listen-socket)|:0 ++edev|my-screen|visual-qualeiface|x11()|xorg(listen-socket)|:0 ``` Connect to the Xorg server that's listening on `listen-socket`, using the `x11` stim-buff-api. Ask that Xorg server to let Salmanoff read out all of the frames written -out to display `:0`. Use salmanoff's `visual-stimiface` to process the visual data from display +out to display `:0`. Use salmanoff's `visual-qualeiface` to process the visual data from display `:0`'s framebuffer. * Implementation note: @@ -199,30 +199,30 @@ out to display `:0`. Use salmanoff's `visual-stimiface` to process the visual da ### To attach a camera device by connecting directly to its Linux driver: ``` -+edev|my-camera|visual-stimiface|v4l()|linux()|/dev/video0 ++edev|my-camera|visual-qualeiface|v4l()|linux()|/dev/video0 ``` We specify that we want to use the `linux` kernel's loaded driver to connect to communicate with `/dev/video0`, via the `Video4Linux` stim-buff-api. We want salmanoff -to use the `visual-stimiface` library to process the visual data from `/dev/video0`'s stim buffer. +to use the `visual-qualeiface` library to process the visual data from `/dev/video0`'s stim buffer. If `/dev/video0` is already consumed by another process, this may likely fail. ### To attach a microphone that's managed by ALSA server: ``` -+edev|my-microphone|audio-stimiface|alsa-mic(shmem)|alsa()|cardname ++edev|my-microphone|audio-qualeiface|alsa-mic(shmem)|alsa()|cardname ``` Connect to the ALSA server via `shmem`, using the `alsa-mic` stim-buff-api. Request access to the microphone function of the sound card with the name `cardname`. Use the -`audio-stimiface` library to process the audio data from `cardname`'s microphone stim buffer. +`audio-qualeiface` library to process the audio data from `cardname`'s microphone stim buffer. ### To attach a thermal sensor managed by Linux: ``` -+idev|my-thermal|thermal-stimiface|thermal-zone()|linux()|/sys/class/thermal_zone0 ++idev|my-thermal|thermal-qualeiface|thermal-zone()|linux()|/sys/class/thermal_zone0 ``` Use the `thermal-zone` SysFS stim-buff-api provided by `linux` to connect to the sensor -`/sys/class/thermal_zone0`. Use the `thermal-stimiface` library to process the thermal data from +`/sys/class/thermal_zone0`. Use the `thermal-qualeiface` library to process the thermal data from `thermal_zone0`'s heat stim buffer. ## Multiple Provider Examples: @@ -232,9 +232,9 @@ Use the `thermal-zone` SysFS stim-buff-api provided by `linux` to connect to the The same physical sound card `soundcard0` can be accessed through different providers: ``` -+edev|soundcard0|audio-stimiface|alsa-audio()|alsa()|card0 -||| +edev|soundcard0|audio-stimiface|direct-file-ops()|linux()|/dev/snd/pcmC0D0p -||| +idev|soundcard0|audio-stimiface|alsa-mic()|alsa()|card0 ++edev|soundcard0|audio-qualeiface|alsa-audio()|alsa()|card0 +||| +edev|soundcard0|audio-qualeiface|direct-file-ops()|linux()|/dev/snd/pcmC0D0p +||| +idev|soundcard0|audio-qualeiface|alsa-mic()|alsa()|card0 ``` This shows: @@ -247,9 +247,9 @@ This shows: A camera device `camera0` might expose different data streams: ``` -+edev|camera0|visual-stimiface|v4l-rgb()|linux()|/dev/video0 -||| +edev|camera0|visual-stimiface|v4l-yuv()|linux()|/dev/video0 -||| +idev|camera0|thermal-stimiface|v4l-thermal()|linux()|/dev/video0 ++edev|camera0|visual-qualeiface|v4l-rgb()|linux()|/dev/video0 +||| +edev|camera0|visual-qualeiface|v4l-yuv()|linux()|/dev/video0 +||| +idev|camera0|thermal-qualeiface|v4l-thermal()|linux()|/dev/video0 ``` This shows the same camera device providing: @@ -287,7 +287,7 @@ Separate individual DAP specifications with two consecutive h-bar characters (`||`), like this: ``` -+edev|my-window|visual-stimiface|wayland()|wayland(server-socket)|window0 -|| +edev|my-xorg-display|visual-stimiface|x11()|xorg(listen-socket)|all -|| +idev|my-thermal|thermal-stimiface|thermal-zone()|linux()|/sys/class/thermal_zone0 ++edev|my-window|visual-qualeiface|wayland()|wayland(server-socket)|window0 +|| +edev|my-xorg-display|visual-qualeiface|x11()|xorg(listen-socket)|all +|| +idev|my-thermal|thermal-qualeiface|thermal-zone()|linux()|/sys/class/thermal_zone0 ``` diff --git a/docs/livox-gen1-lidar-dap-spec.md b/docs/livox-gen1-lidar-dap-spec.md index 101d76b..bc75f9a 100644 --- a/docs/livox-gen1-lidar-dap-spec.md +++ b/docs/livox-gen1-lidar-dap-spec.md @@ -2,11 +2,20 @@ ## Overview -The LivoxGen1Lidar DAP specification defines how to attach to Livox Gen1 LiDAR devices and access their various data streams using a unified stim-buff-api with mode-based parameter selection. +The LivoxGen1Lidar DAP specification describes how to attach to Livox Gen1 +LiDAR devices and access their various data streams. The Livox Gen1 LiDAR +presents multiple stim features, each with its own dedicated stim-buff-api. ## Stim-Buff-API Structure -The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-based parameters to specify which data interface to present. +The LivoxGen1Lidar DAP uses multiple stim-buff-api names, one for each stim feature it presents: + +* `livoxGen1-pcloud` - Point cloud coordinate data +* `livoxGen1-pcloudIntensity` - Point cloud intensity/reflectivity data +* `livoxGen1-gyro` - Gyroscope data from internal IMU +* `livoxGen1-accel` - Accelerometer data from internal IMU + +Each stim-buff-api is designed to work with specific stim-iface libraries that understand the data format and processing requirements for that particular stim feature. ## DAP Specifications @@ -16,21 +25,11 @@ The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-b **Syntax**: ``` -+idev | avia0 | structural-stimiface | livoxGen1(mode=pointCloudIntensity) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++idev | avia0 | pcloudIntensity | livoxGen1-pcloudIntensity(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ``` -**Alternative Syntax** (all equivalent): -``` -+idev | avia0 | structural-stimiface | livoxGen1(stim=pcloudIntensity) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 -+idev | avia0 | structural-stimiface | livoxGen1(affordance=pCloudI) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 -``` - -**Mode Parameter Values** (synonymous): -- `pointCloudIntensity` -- `pcloudIntensity` -- `pCloudIntensity` -- `pCloudI` -- `pcloudI` +**Stim-Buff-API**: `livoxGen1-pcloudIntensity` +**Quale-Iface-API**: `pcloudIntensity` - Processes intensity/reflectivity data from point clouds ### 2. Point Cloud Coordinate Data Device (Extrospector) @@ -38,15 +37,21 @@ The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-b **Syntax**: ``` -+edev | avia0 | structural-stimiface | livoxGen1(mode=pcloud,format=xyz) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++edev | avia0 | pcloud(format=xyz) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ``` -**Mode Parameter Values** (synonymous): -- `pcloud` -- `pCloud` -- `pointCloud` +**Alternative Format Examples**: +``` ++edev | avia0 | pcloud(format=spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++edev | avia0 | pcloud(format=spherical-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++edev | avia0 | pcloud(format=dual-cartesian) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++edev | avia0 | pcloud(format=dual-spherical) | livoxGen1-pcloud(data-rate-hz=10) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 +``` -**Format Parameter** (for point cloud modes): +**Stim-Buff-API**: `livoxGen1-pcloud` +**Quale-Iface-API**: `pcloud` - Processes spatial coordinate data from point clouds + +**Format Parameter Values** (for pcloud quale-iface-api): - `xyz`: Standard Cartesian coordinates (X, Y, Z) - `spherical`: Raw spherical coordinates - `spherical-cartesian`: Spherical coordinates converted to Cartesian @@ -62,11 +67,11 @@ The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-b **Syntax**: ``` -+idev | avia0 | gyro-stimiface | livoxGen1(mode=gyro) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++idev | avia0 | gyro | livoxGen1-gyro(data-rate-hz=100) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ``` -**Mode Parameter Values**: -- `gyro` +**Stim-Buff-API**: `livoxGen1-gyro` +**Quale-Iface-API**: `gyro` - Processes gyroscope angular velocity data ### 4. IMU Accelerometer Data Device (Interoceptor) @@ -74,11 +79,11 @@ The LivoxGen1Lidar DAP uses a unified stim-buff-api name `livoxGen1` with mode-b **Syntax**: ``` -+idev | avia0 | accel-stimiface | livoxGen1(mode=accel) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ++idev | avia0 | accel | livoxGen1-accel(data-rate-hz=100) | livoxProto1(handshake-timeout-ms=1000,retry-delay-ms=3000,smo-ip=192.168.1.50,smo-subnet-nbits=24) | 3JEDK380010Z39 ``` -**Mode Parameter Values**: -- `accel` +**Stim-Buff-API**: `livoxGen1-accel` +**Quale-Iface-API**: `accel` - Processes accelerometer linear acceleration data ## Provider Parameters @@ -124,16 +129,26 @@ The `livoxProto1` provider accepts the following parameters: ## Parameter Summary -### Mode/Stim/Affordance Parameter Values +### Stim-Buff-API Names -| Data Type | Mode Values | Description | -|-----------|-------------|-------------| -| Point Cloud Intensity | `pointCloudIntensity`, `pcloudIntensity`, `pCloudIntensity`, `pCloudI`, `pcloudI` | Light intensity/reflectivity data | -| Point Cloud Coordinates | `pcloud`, `pCloud`, `pointCloud` | Spatial coordinate data | -| Gyroscope | `gyro` | Angular velocity measurements | -| Accelerometer | `accel` | Linear acceleration measurements | +| Stim Feature | Stim-Buff-API | Quale-Iface-API | Description | +|--------------|---------------|----------------|-------------| +| Point Cloud Intensity | `livoxGen1-pcloudIntensity` | `pcloudIntensity` | Light intensity/reflectivity data | +| Point Cloud Coordinates | `livoxGen1-pcloud` | `pcloud` | Spatial coordinate data | +| Gyroscope | `livoxGen1-gyro` | `gyro` | Angular velocity measurements | +| Accelerometer | `livoxGen1-accel` | `accel` | Linear acceleration measurements | -### Format Parameter Values (for point cloud modes) +### Stim-Buff-API Parameters + +Each stim-buff-api accepts device-specific parameters: + +| Parameter | Description | Example | +|-----------|-------------|---------| +| `data-rate-hz` | Data sampling rate in Hz | `data-rate-hz=10` | + +### Quale-Iface-API Parameters + +The `pcloud` quale-iface-api accepts format parameters: | Format | Description | |--------|-------------|