From 46ef17bb0576fff1cdd80ac3ac718df0c2e01495 Mon Sep 17 00:00:00 2001 From: Hayodea Hakol Date: Mon, 6 Jan 2025 21:00:31 -0400 Subject: [PATCH] Docs:deviceSpec: Update spec and document separators --- docs/deviceSpec.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/docs/deviceSpec.md b/docs/deviceSpec.md index d1f179f..2e51e9c 100644 --- a/docs/deviceSpec.md +++ b/docs/deviceSpec.md @@ -9,7 +9,7 @@ visual sense data from your eyes. ## 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 Interest") extraction algorithm. An Implex algorithm is used to scan a frame of input sensor data and detect objects and patterns within it. @@ -18,14 +18,16 @@ input sensor data and detect objects and patterns within it. The general format of a device-spec for a sensor is: ``` -implexor|api|server(server-params)|deviceselector +sensor-type|implexor|api(api-params)|server(server-params)|deviceselector ``` +* `sensor-type` is always either '`i`' (interoceptor), '`e`' (extrospector), + or '`a`' (actuator). * `implexor` is the name of the implexor algorithm that should be used with the data that is provided by the `server` via the `api`. * `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 - this `api`. + 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 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 @@ -37,7 +39,7 @@ Some examples follow: ### To attach a particular window from a window manager: ``` -visual-implexor|wayland|wayland(server-socket)|window0 +e|visual-implexor|wayland()|wayland(server-socket)|window0 ``` Connect to the Wayland server that's listening on `server-socket`, using the `wayland` api. Ask that Wayland server to give harikoff read-access to all @@ -46,7 +48,7 @@ of the frames composited into the window buffer for `window0`. Use harikoff's ### To attach a window manager's entire rendered desktop: ``` -visual-implexor|wayland|wayland(listen-socket)|all +e|visual-implexor|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. @@ -58,7 +60,7 @@ from that Wayland server's compositor data. ### To attach all of an Xorg server's gfx output to all screens: ``` -visual-implexor|x11|xorg(listen-socket)|all +e|visual-implexor|x11()|xorg(listen-socket)|all ``` Connect to the Xorg server that's listening on `listen-socket`, using the `x11` @@ -71,7 +73,7 @@ WM's output. ### To attach all of an Xorg server's gfx output to a particular screen: ``` -visual-implexor|x11|xorg(listen-socket)|:0 +e|visual-implexor|x11()|xorg(listen-socket)|:0 ``` 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 @@ -80,7 +82,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: ``` -visual-implexor|v4l|linux()|/dev/video0 +e|visual-implexor|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` API. We want harikoff @@ -90,24 +92,33 @@ If `/dev/video0` is already consumed by another process, this may likely fail. ### To attach a microphone that's managed by ALSA server: ``` -audio-implexor|alsa(shmem)|alsa()|cardname +e|audio-implexor|alsa(shmem)|alsa()|cardname ``` Connect to the ALSA server via `shmem`, using the `alsa` API. Request access to the microphone function of the sound card with the name `cardname`. Use the `audio-implexor` algorithm to implex from `cardname`'s microphone data. +### To attach a thermal sensor managed by Linux: +``` +i|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0 +``` + +Use the `thermal-zone` SysFS API provided by `linux` to connect to the sensor +`/sys/class/thermal_zone0`. Use the `thermal-implexor` implexor to implex from +`thermal_zone0`'s heat data. + ## Attaching actuators: Actuators are Harikoff's way of enacting changes in the external world. They're like your libs, or your mouth. Actuators enable harikoff to write outputs to the world outside. -### Wilzors: +### Wilzors: Actuator devices are analogous to your body's limbs. Harikoff controls these 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 +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 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 your actuator device. @@ -116,3 +127,13 @@ The general format for an actuator's device spec is: ``` WIP: TBD. ``` + +## Device specification files: + +Inside of a device spec file, you can list any number of device specs. Separate +individual device specs with two consecutive h-bar characters (`||`), like this: +``` +e|visual-implexor|wayland()|wayland(server-socket)|window0 +|| e|visual-implexor|x11()|xorg(listen-socket)|all +|| i|thermal-implexor|thermal-zone()|linux()|/sys/class/thermal_zone0 +```