feat: use mdBook for documentation (#10)

2025-08-28 23:22:04 +02:00
parent d98cd89c48
commit 3414589bd5
24 changed files with 317 additions and 194 deletions
@@ -0,0 +1 @@
+# Sensor Value Provider
@@ -0,0 +1,29 @@
+# Sensor Data Provider Shell Scripts
+
+The [/linux/scripts](../../../linux/scripts) directory contains some proof-of-concept Linux shell scripts.
+
+CPU and memory usage are written into a sensor data source text file that can be used by `asterctl`.
+
+```
+./cpu_usage.sh -h
+Simple PoC script to periodically write the CPU usage into a sensor text file.
+
+Usage:
+./cpu_usage.sh [-r REFRESH] [-s SENSOR_FILE] [-t TEMP_DIR]
+
+  -r REFRESH     refresh in seconds.  Default: 1
+  -s SENSOR_FILE output sensor file.  Default: /tmp/sensors/cpu.txt
+  -t TEMP_DIR    temporary directory. Default: /tmp
+```
+
+```
+./mem_usage.sh -h
+Simple PoC script to periodically write the memory usage into a sensor text file.
+
+Usage:
+./mem_usage.sh [-r REFRESH] [-s SENSOR_FILE] [-t TEMP_DIR]
+
+  -r REFRESH     refresh in seconds.  Default: 5
+  -s SENSOR_FILE output sensor file.  Default: /tmp/sensors/mem.txt
+  -t TEMP_DIR    temporary directory. Default: /tmp
+```
@@ -0,0 +1,51 @@
+# sysinfo Tool
+
+The Rust based [sysinfo](https://github.com/zehnm/aoostar-rs/blob/main/crates/sysinfo) tool gathers many more system sensor values with the help of
+the [sysinfo](https://github.com/GuillaumeGomez/sysinfo) crate.
+
+It supports FreeBSD, Linux, macOS, Windows and other OSes, but it has only been tested on Linux so far.
+
+```
+Proof of concept sensor value collection for the asterctl screen control tool
+
+Usage: sysinfo [OPTIONS]
+
+Options:
+  -o, --out <OUT>
+          Output sensor file
+
+  -t, --temp-dir <TEMP_DIR>
+          Temporary directory for preparing the output sensor file.
+          
+          The system temp directory is used if not specified.
+          The temp directory must be on the same file system for atomic rename
+          operation!
+
+      --console
+          Print values in console
+
+  -r, --refresh <REFRESH>
+          System sensor refresh interval in seconds
+
+      --disk-refresh <DISK_REFRESH>
+          Enable individual disk refresh logic as used in AOOSTAR-X.
+          Refresh interval in seconds
+
+      --smartctl
+          Retrieve drive temperature if `disk-update` option is enabled.
+          
+          Requires smartctl and password-less sudo!
+```
+
+Single test run with printing all sensors in the console:
+```shell
+sysinfo --console
+```
+
+Normal mode providing sensor values for `asterctl` in `/tmp/sensors/sysinfo.txt` every 3 seconds:
+
+```shell
+sysinfo --refresh 3 --out /tmp/sensors/sysinfo.txt
+```
+
+Note: the lower the refresh rate, the more resources are used!
@@ -0,0 +1,57 @@
+# Text File Data Source
+
+- Text file with ending: `.txt`
+- Simple key / value pairs, separated by a colon `:`. Example: `foo: bar`
+- Line based: one key / value per line.
+- Key and value are trimmed. Any whitespace will be removed.
+- Empty lines and comments are ignored.
+- Comments start with `#` at the beginning of the line.
+- Support for special keys: if key ends with `#unit` then the value is the unit for the corresponding key before the suffix
+    - Example: `net_download_speed#unit: M/S` is the unit value for `net_download_speed`.
+    - This can be used for dynamic unit values if they sensor value provider cannot add the unit to the corresponding value.
+- File contents will automatically be read when updated.
+    - This requires the sensor value provider to use atomic file updates!
+    - Best practice is to use a temporary file on the same filesystem and use a move or rename operation after all values have been written.
+- One or multiple sensor text files are supported.
+    - Either a single file can be specified, or a directory path.
+    - If a directory is specified, all children matching the sensor file naming pattern will be read and monitored.
+    - Any subdirectories are ignored (no recursive support).
+
+Example text file for the [cfg/monitor.json](https://github.com/zehnm/aoostar-rs/blob/main/cfg/monitor.json) panel configuration:
+
+```
+cpu_temperature: 65
+cpu_percent: 98
+memory_usage: 77
+memory_Temperature: 48
+net_ip_address: 146.56.182.244
+gpu_core: 98
+gpu_temperature: 78
+net_upload_speed: 100
+net_upload_speed#unit: K/S
+net_download_speed: 120
+net_download_speed#unit: M/S
+motherboard_temperature: 38
+storage_ssd[0]['temperature']: 31
+storage_ssd[0]['used']: 17
+storage_ssd[1]['temperature']: 32
+storage_ssd[1]['used']: 27
+storage_ssd[2]['temperature']: 33
+storage_ssd[2]['used']: 37
+storage_ssd[3]['temperature']: 34
+storage_ssd[3]['used']: 47
+storage_ssd[4]['temperature']: 35
+storage_ssd[4]['used']: 57
+storage_hdd[0]['temperature']: 36
+storage_hdd[0]['used']: 17
+storage_hdd[1]['temperature']: 37
+storage_hdd[1]['used']: 27
+storage_hdd[2]['temperature']: 38
+storage_hdd[2]['used']: 37
+storage_hdd[3]['temperature']: 39
+storage_hdd[3]['used']: 47
+storage_hdd[4]['temperature']: 40
+storage_hdd[4]['used']: 57
+storage_hdd[5]['temperature']: 10
+storage_hdd[5]['used']: 67
+```