hayodea/salmanoff
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs:devspec: update docs with new device-type prefix syntax

Browse Source
This commit is contained in:
Hayodea Hekol
2025-01-07 14:31:30 -04:00
parent fe09b00c7f
commit e89a38203e
1 changed files with 43 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/deviceSpec.md
+43 -40
View File
@@ -2,17 +2,17 @@
## Attaching sensors: ## Attaching sensors:
Sensors are input devices to Harikoff. Harikoff will perceive them as perceptual Sensors are input devices to Harikoff. Harikoff will perceive them as
inputs -- like your own sense organs. For example, if you attach a camera as a perceptual inputs -- like your own sense organs. For example, if you attach a
sensor, harikoff will experience it in the same way that you experience the camera as a sensor, harikoff will experience it in the same way that you
visual sense data from your eyes. experience the visual sense data from your eyes.
## Implexors: ## Implexors:
An implexor is an **Imp**licit **Ex**istent isolat**Or** algorithm. It's An implexor is an **Imp**licit **Ex**istent isolat**Or** algorithm. It's
basically what conventional ML/LLM/ANN developers call an ROI ("Region of basically what conventional ML/LLM/ANN developers call an ROI ("Region of
Interest") extraction algorithm. An Implex algorithm is used to scan a frame of Interest") extraction algorithm. An Implex algorithm is used to scan a frame
input sensor data and detect objects and patterns within it. of input sensor data and detect objects and patterns within it.
## Sensor device spec: ## Sensor device spec:
@@ -21,13 +21,15 @@ The general format of a device-spec for a sensor is:
sensor-type|implexor|api(api-params)|server(server-params)|deviceselector sensor-type|implexor|api(api-params)|server(server-params)|deviceselector
``` ```
* `sensor-type` is always either '`i`' (interoceptor), '`e`' (extrospector), * `sensor-type` is always either '`+idev`' (interoceptor), '`+edev`'
or '`a`' (actuator). (extrospector), or '`+adev`' (actuator).
* `implexor` is the name of the implexor algorithm that should be used with * `implexor` is the name of the implexor algorithm that should be used with
the data that is provided by the `server` via the `api`. the data that is provided by the `server` via the `api`.
* `api` is the interface that the server uses to export perceptual data for * `api` is the interface that the server uses to export perceptual data for
harikoff to read. Harikoff will run the `implexor` algorithm on the data from harikoff to read. Harikoff will run the `implexor` algorithm on the data
this `api`. The `api-param` in parentheses may be omitted, in which case the parentheses will be empty, but the parentheses must always be written out. from this `api`. The `api-param` in parentheses may be omitted, in which
case the parentheses will be empty, but the parentheses must always be
written out.
* `server` may be a userspace daemon or an OS kernel that provides perceptual * `server` may be a userspace daemon or an OS kernel that provides perceptual
data via the `api`. The `server-params` in parentheses may be omitted, in data via the `api`. The `server-params` in parentheses may be omitted, in
which case the parenthesis will be empty, but the parentheses must always be which case the parenthesis will be empty, but the parentheses must always be
@@ -41,41 +43,41 @@ If there's more than one parameter item in a list of `api-params` or
`server-params`, then the individual items in a list of `api-param` or `server-params`, then the individual items in a list of `api-param` or
`server-params` should be separated by the h-bar character (`|`). E.g: `server-params` should be separated by the h-bar character (`|`). E.g:
``` ```
e|audio-implexor|alsa(shmem|param2|param3)|alsa()|cardname +edev|audio-implexor|alsa(shmem|param2|param3)|alsa()|cardname
``` ```
Some examples follow: Some examples follow:
### To attach a particular window from a window manager: ### To attach a particular window from a window manager:
``` ```
e|visual-implexor|wayland()|wayland(server-socket)|window0 +edev|visual-implexor|wayland()|wayland(server-socket)|window0
``` ```
Connect to the Wayland server that's listening on `server-socket`, using Connect to the Wayland server that's listening on `server-socket`, using the
the `wayland` api. Ask that Wayland server to give harikoff read-access to all `wayland` api. Ask that Wayland server to give harikoff read-access to all of
of the frames composited into the window buffer for `window0`. Use harikoff's the frames composited into the window buffer for `window0`. Use harikoff's
`visual-implexor` to implex from that `window0`'s compositor data. `visual-implexor` to implex from that `window0`'s compositor data.
### To attach a window manager's entire rendered desktop: ### To attach a window manager's entire rendered desktop:
``` ```
e|visual-implexor|wayland()|wayland(listen-socket)|all +edev|visual-implexor|wayland()|wayland(listen-socket)|all
``` ```
In most cases, this is basically the same as attempting to attach all of the In most cases, this is basically the same as attempting to attach all of the
underlying GFX server's output. underlying GFX server's output.
Connect to the Wayland server that's listening on `listen-socket`, using Connect to the Wayland server that's listening on `listen-socket`, using the
the `wayland` api. Ask that Wayland server to give harikoff read-access to the `wayland` api. Ask that Wayland server to give harikoff read-access to the
entire compositor framebuffer. Use harikoff's `visual-implexor` to implex entire compositor framebuffer. Use harikoff's `visual-implexor` to implex from
from that Wayland server's compositor data. that Wayland server's compositor data.
### To attach all of an Xorg server's gfx output to all screens: ### To attach all of an Xorg server's gfx output to all screens:
``` ```
e|visual-implexor|x11()|xorg(listen-socket)|all +edev|visual-implexor|x11()|xorg(listen-socket)|all
``` ```
Connect to the Xorg server that's listening on `listen-socket`, using the `x11` Connect to the Xorg server that's listening on `listen-socket`, using the `x11`
api. Ask that Xorg server to let Harikoff read out all of the frames written out api. Ask that Xorg server to let Harikoff read out all of the frames written
to all screens. Use harikoff's `visual-implexor` to implex from the server's out to all screens. Use harikoff's `visual-implexor` to implex from the
gfx framebuffer data. server's gfx framebuffer data.
In most cases, this is basically the same as attempting to attach all of the In most cases, this is basically the same as attempting to attach all of the
WM's output. WM's output.
@@ -86,11 +88,11 @@ WM's output.
### To attach all of an Xorg server's gfx output to a particular screen: ### To attach all of an Xorg server's gfx output to a particular screen:
``` ```
e|visual-implexor|x11()|xorg(listen-socket)|:0 +edev|visual-implexor|x11()|xorg(listen-socket)|:0
``` ```
Connect to the Xorg server that's listening on `listen-socket`, using the `x11` Connect to the Xorg server that's listening on `listen-socket`, using the `x11`
api. Ask that Xorg server to let Harikoff read out all of the frames written out api. Ask that Xorg server to let Harikoff read out all of the frames written
to display `:0`. Use harikoff's `visual-implexor` to implex from display out to display `:0`. Use harikoff's `visual-implexor` to implex from display
`:0`'s framebuffer data. `:0`'s framebuffer data.
* Implementation note: * Implementation note:
@@ -99,7 +101,7 @@ to display `:0`. Use harikoff's `visual-implexor` to implex from display
### To attach a camera device by connecting directly to its Linux driver: ### To attach a camera device by connecting directly to its Linux driver:
``` ```
e|visual-implexor|v4l()|linux()|/dev/video0 +edev|visual-implexor|v4l()|linux()|/dev/video0
``` ```
We specify that we want to use the `linux` kernel's loaded driver to connect We specify that we want to use the `linux` kernel's loaded driver to connect
to communicate with `/dev/video0`, via the `Video4Linux` API. We want harikoff to communicate with `/dev/video0`, via the `Video4Linux` API. We want harikoff
@@ -109,7 +111,7 @@ If `/dev/video0` is already consumed by another process, this may likely fail.
### To attach a microphone that's managed by ALSA server: ### To attach a microphone that's managed by ALSA server:
``` ```
e|audio-implexor|alsa(shmem)|alsa()|cardname +edev|audio-implexor|alsa(shmem)|alsa()|cardname
``` ```
Connect to the ALSA server via `shmem`, using the `alsa` API. Request access to Connect to the ALSA server via `shmem`, using the `alsa` API. Request access to
@@ -118,7 +120,7 @@ the microphone function of the sound card with the name `cardname`. Use the
### To attach a thermal sensor managed by Linux: ### To attach a thermal sensor managed by Linux:
``` ```
i|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0 +idev|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0
``` ```
Use the `thermal-zone` SysFS API provided by `linux` to connect to the sensor Use the `thermal-zone` SysFS API provided by `linux` to connect to the sensor
@@ -127,14 +129,14 @@ Use the `thermal-zone` SysFS API provided by `linux` to connect to the sensor
## Attaching actuators: ## Attaching actuators:
Actuators are Harikoff's way of enacting changes in the external world. They're Actuators are Harikoff's way of enacting changes in the external world.
like your libs, or your mouth. Actuators enable harikoff to write outputs to the They're like your libs, or your mouth. Actuators enable harikoff to write
world outside. outputs to the world outside.
### Wilzors: ### Wilzors:
Actuator devices are analogous to your body's limbs. Harikoff controls these by Actuator devices are analogous to your body's limbs. Harikoff controls these
using `wilzor` algorithms. Wilzor is a contraction of **Wil**lpower by using `wilzor` algorithms. Wilzor is a contraction of **Wil**lpower
Actuat**Or** but with a 'Z' in the middle to make it sound cooler. Different Actuat**Or** but with a 'Z' in the middle to make it sound cooler. Different
types of devices will require different wilzor algorithms. You need to know types of devices will require different wilzor algorithms. You need to know
what type of wilzor algorithm needs to be used to enable harikoff to control what type of wilzor algorithm needs to be used to enable harikoff to control
@@ -147,10 +149,11 @@ WIP: TBD.
## Device specification files: ## Device specification files:
Inside of a device spec file, you can list any number of device specs. Separate Inside of a device spec file, you can list any number of device specs.
individual device specs with two consecutive h-bar characters (`||`), like this: Separate individual device specs with two consecutive h-bar characters (`||`),
like this:
``` ```
e|visual-implexor|wayland()|wayland(server-socket)|window0 +edev|visual-implexor|wayland()|wayland(server-socket)|window0
|| e|visual-implexor|x11()|xorg(listen-socket)|all || +edev|visual-implexor|x11()|xorg(listen-socket)|all
|| i|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0 || +idev|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0
``` ```