diff --git a/.github/workflows/deploy_mdbook.yml b/.github/workflows/deploy_mdbook.yml new file mode 100644 index 0000000..31559ee --- /dev/null +++ b/.github/workflows/deploy_mdbook.yml @@ -0,0 +1,41 @@ +name: Deploy mdbook +on: + push: + branches: + - main + paths: + - 'book.toml' + - 'docs/**' + - '.github/workflows/deploy_mdbook.yml' + +jobs: + deploy: + name: Deploy mdbook + runs-on: ubuntu-latest + permissions: + contents: write # To push a branch + pages: write # To push to a GitHub Pages site + id-token: write # To update the deployment status + steps: + - uses: actions/checkout@v5 + with: + fetch-depth: 0 + - name: Install latest mdbook + run: | + tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') + url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" + mkdir mdbook + curl -sSL $url | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + - name: Build Book + run: mdbook build + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + # Upload entire repository + path: 'book' + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 582689d..c98f736 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ .DS_Store *.bak Cargo.lock.tmp +/_work +/book diff --git a/CHANGELOG.md b/CHANGELOG.md index bc1b0e5..3b159f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ _Changes in the next release_ ### Added - Simple sensor panel with a file-based data source (#6) - Initial support for fan-, progress-, & pointer-sensors (#8) +- Use [mdBook](https://rust-lang.github.io/mdBook/) for documentation and publish user guide to GitHub pages (#10) ### Changed - Project structure using a Cargo workspace diff --git a/README.md b/README.md index fbba75d..dfd440b 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,21 @@ Reverse engineering the [AOOSTAR WTR MAX](https://aoostar.com/products/aoostar-w display protocol, with a proof-of-concept application written in Rust. It has only been tested on the WTR MAX, but should also support the GEM12+ PRO device. -**Disclaimer: ‼️ EXPERIMENTAL — use at your own risk ‼️** +Check out the **[User Guide](https://zehnm.github.io/aoostar-rs)** for a list of features and installation and usage information. + +## Features + +- Control the AOOSTAR WTR MAX and GEM12+ PRO second screen from Linux. +- Switch the display on or off. + - Also possible with standard [Linux shell commands](docs/shell_commands.md). + - [Linux systemd Service](docs/linux/README.md) to automatically switch off the LCD at boot up. +- Display images (with automatic scaling and partial update support). +- Render dynamic sensor panels defined from the AOOSTAR-X software. + - Update sensor values from simple text files. + - Rotate through multiple panels in a defined interval. +- USB device/serial port selection. + +## Disclaimer > I take no responsibility for the use of this software. > There is no official documentation available; @@ -22,88 +36,8 @@ Note: Multiple attempts to contact the manufacturer for documentation have recei With that out of the way, on to the fun stuff! -**See [Linux shell commands](docs/shell_commands.md) on how to switch off the display with standard Linux commands!** - -See [releases](https://github.com/zehnm/aoostar-rs/releases) for binary Linux x64 releases and [Linux systemd Service](linux/) -on how to automatically switch off the LCD at boot up. A Debian package for easy installation is planned for the future! - -## Reverse Engineering - -Reverse engineered LCD commands: [docs/lcd_protocol.md](docs/lcd_protocol.md) - -### Motivation - -Developing open client software to use the embedded second screen on various Linux distributions. -It *might* also work on Windows, but I neither have that OS, nor plan to install it. - -The official proprietary AOOSTAR-X display software is not suitable for NAS and security-minded users: - -- All-in-one solution that attempts to do everything, from sensor reading to running a web server for control and configuration (*exposed on all interfaces!*). - I prefer using existing monitoring tools and combining them to my liking. -- Resource hungry, written in Python. Archive of v1.3.4 is 178 MB. -- Closed source, requires root access, distributed over filesharing sites, some without HTTPS. -- Built-in expiration date. One must regularly update the software without being able to verify the source. -- Many untranslated messages in Chinese and missing instructions for included features. - -The display remains on continuously (24×7) if the official software is not running. - -### Goals - -- [x] Reverse engineer the LCD serial protocol to provide open screen software. - - Utilize the official AOOSTAR-X display software by sniffing USB communication, using `strace`, and decompiling the Python app. -- [x] Document known commands so clients in other programming languages can be written. -- [ ] Eventually, publish a Rust crate for easy integration into other Rust applications. - -**Out of scope:** - -- Reverse engineering the microcontroller firmware on the display board. - That would be an interesting task — potentially uncovering additional display commands — but is outside the project's current scope. -- Reimplementing the full AOOSTAR-X display software, which is overly complex for most use cases. - -### Features - -- Control the AOOSTAR WTR MAX and GEM12+ PRO second screen from Linux. -- Switch the display on or off. -- Display images (with automatic scaling and partial update support). -- Render dynamic sensor panels defined from the AOOSTAR-X software. - - Update sensor values from simple text files. - - Rotate through multiple panels in a defined interval. -- USB device/serial port selection. - -## Setup - -### Requirements - -1. A recent [Rust](https://rustup.rs/) toolchain is required, using `rust-up` is the easiest way to get everything set up. - -2. Install required build dependencies (shown for Ubuntu 25.04): - -```shell -sudo apt install build-essential git pkg-config libudev-dev -``` - -3. Checkout project: - -```shell -git clone https://github.com/zehnm/aoostar-rs.git -cd aoostar-rs -``` - -### Build - -A release build is highly recommended, as it significantly improves graphic rendering performance: - -```shell -cargo build --release -``` - -### Install - -See [Linux systemd Service](linux/) on how to automatically switch off the LCD at boot up. - -## Usage - -See [asterctl documentation](docs/README.md) for more information or run `asterctl --help` for available command line options. +- Browse the source code or read the [User Guide](https://zehnm.github.io/aoostar-rs) +- See [releases](https://github.com/zehnm/aoostar-rs/releases) for binary Linux x64 releases. A Debian package for easy installation is planned for the future! ## Contributing diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..8100357 --- /dev/null +++ b/book.toml @@ -0,0 +1,5 @@ +[book] +authors = ["Markus Zehnder"] +language = "en" +src = "docs" +title = "AOOSTAR WTR MAX / GEM12+ PRO Screen Control" diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/README.md b/docs/README.md index 3911e53..40c073b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,37 +1,52 @@ -# AOOSTAR WTR MAX Screen Control +# Introduction - [asterctl usage](asterctl.md) - [Linux shell control commands](shell_commands.md) without using asterctl -## Sensor Panels +## Motivation -- [Sensor panels](sensor_panels.md) -- [Custom sensor panels](sensor_custom_panel.md) +Developing open client software to use the embedded second screen on various Linux distributions. +It *might* also work on Windows, but I neither have that OS, nor plan to install it. -### Sensor Modes +The official proprietary AOOSTAR-X display software is not suitable for NAS and security-minded users: -Different sensor modes are supported: +- All-in-one solution that attempts to do everything, from sensor reading to running a web server for control and configuration (*exposed on all interfaces!*). + I prefer using existing monitoring tools and combining them to my liking. +- Resource hungry, written in Python. Archive of v1.3.4 is 178 MB. +- Closed source, requires root access, distributed over filesharing sites, some without HTTPS. +- Built-in expiration date. One must regularly update the software without being able to verify the source. +- Many untranslated messages in Chinese and missing instructions for included features. -- [Sensor mode 1: Text](sensor_mode1_text.md) -- [Sensor mode 2: Circular Progress](sensor_mode2_fan.md) -- [Sensor mode 3: Progress](sensor_mode3_progress.md) -- [Sensor mode 4: Pointer](sensor_mode4_pointer.md) +The display remains on continuously (24×7) if the official software is not running. -### Sensor Data Sources +## Goals -The sensor value reading is separated from the `asterctl` tool. +- [x] Reverse engineer the LCD serial protocol to provide open screen software. + - Utilize the official AOOSTAR-X display software by sniffing USB communication, using `strace`, and decompiling the Python app. +- [x] Document known commands so clients in other programming languages can be written. +- [ ] Eventually, publish a Rust crate for easy integration into other Rust applications. -Sensor values are provided in separate text files and are automatically read when the file changes. -Only the file data source is supported at the moment, other sources like pipes, sockets etc. might be supported later. +**Out of scope:** -- [Text file data source](sensor_data_txt_file.md) +- Reverse engineering the microcontroller firmware on the display board. + That would be an interesting task — potentially uncovering additional display commands — but is outside the project's current scope. +- Reimplementing the full AOOSTAR-X display software, which is overly complex for most use cases. -### Sensor Data Providers - -- Proof of concept [Linux shell scripts](sensor_data_shell.md) -- [sysinfo tool](sensor_data_sysinfo.md) ## Development -- [LCD Protocol](lcd_protocol.md) +- [Reverse engineered LCD protocol](lcd_protocol.md) +- [GitHub project](https://github.com/zehnm/aoostar-rs) +## Contributing + +Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. + +## License + +Licensed under either of + +- [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) +- [MIT License](http://opensource.org/licenses/MIT) + +at your option. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md new file mode 100644 index 0000000..420146c --- /dev/null +++ b/docs/SUMMARY.md @@ -0,0 +1,31 @@ +# Summary + +[Introduction](README.md) + +# User guide + +- [Installation](installation.md) + - [Linux systemd Service](linux/README.md) +- [asterctl Tool](asterctl.md) +- [Shell Commands](shell_commands.md) + +# Reference guide + +- [Sensor Panels](sensor/panel.md) + - [Custom Panel](sensor/custom_panel.md) + - [Configuration](sensor/cfg/README.md) + - [Text Sensor](sensor/cfg/mode1_text.md) + - [Circular Sensor](sensor/cfg/mode2_circular.md) + - [Progress Sensor](sensor/cfg/mode3_progress.md) + - [Pointer Sensor](sensor/cfg/mode4_pointer.md) +- [Sensor Value Provider](sensor/provider/README.md) + - [Text File Data Source](sensor/provider/text_file.md) + - [Shell Scripts](sensor/provider/shell_scripts.md) + - [Sysinfo Tool](sensor/provider/sysinfo.md) + + +# Development + +- [LCD Protocol](lcd_protocol.md) diff --git a/docs/asterctl.md b/docs/asterctl.md index f25bf17..d4e5140 100644 --- a/docs/asterctl.md +++ b/docs/asterctl.md @@ -15,7 +15,8 @@ Usage: asterctl [OPTIONS] Options: -d, --device - Serial device, for example "/dev/cu.usbserial-AB0KOHLS". Takes priority over --usb option + Serial device, for example "/dev/cu.usbserial-AB0KOHLS". + Takes priority over --usb option -u, --usb USB serial UART "vid:pid" in hex notation (lsusb output). Default: 416:90A1 @@ -32,21 +33,25 @@ Options: -c, --config AOOSTAR-X json configuration file to parse. - The configuration file will be loaded from the `config_dir` directory if no full path is specified. + The configuration file will be loaded from the `config_dir` directory + if no full path is specified. -p, --panels Include one or more additional custom panels into the base configuration. - Specify the path to the panel directory containing panel.json and fonts / img subdirectories. + Specify the path to the panel directory containing panel.json and fonts / + img subdirectories. --config-dir - Configuration directory containing configuration files and background images specified in the `config` file. Default: `./cfg` + Configuration directory containing configuration files and background + images specified in the `config` file. Default: `./cfg` --font-dir Font directory for fonts specified in the `config` file. Default: `./fonts` --sensor-path - Single sensor value input file or directory for multiple sensor input files. Default: `./cfg/sensors` + Single sensor value input file or directory for multiple sensor input files. + Default: `./cfg/sensors` -o, --off-after Switch off display n seconds after loading image or running demo @@ -58,7 +63,8 @@ Options: Test mode: save changed images in ./out folder --simulate - Simulate serial port for testing and development, `--device` and `--usb` options are ignored + Simulate serial port for testing and development, + `--device` and `--usb` options are ignored -h, --help Print help (see a summary with '-h') diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..002ad51 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,53 @@ +# Installation + +There are multiple ways to install the `asterctl` CLI tool. Choose any one of the methods below that best suit your needs. + +Please note that only Linux has been tested so far. + +## Pre-compiled binaries + +Executable binaries are available for download on the [GitHub Releases page](https://github.com/zehnm/aoostar-rs/releases). +Download the binary for your platform (only Linux available at the moment) and extract the archive. +The archive contains the `asterctl` and `sysinfo` executables which you can run. + +## Build from source using Rust + +To build the `asterctl` and `sysinfo` executables from source, you will first need to install Rust and Cargo. +Follow the instructions on the [Rust installation page](https://www.rust-lang.org/tools/install). +At least Rust version 1.88 is required. + +The project contains IDE settings for [RustRover](https://www.jetbrains.com/rust/) (or other JetBrain IDEs with the Rust +plugin) to get you up and running in no time. This is not a requirement, everything can be easily built on the command line. + +Once you have installed Rust, the following commands can be used to build `asterclt` and all other binaries: + +1. On Linux, install required build dependencies (shown for Ubuntu 25.04): + +```shell +sudo apt install build-essential git pkg-config libudev-dev +``` + +2. Checkout project: + +```shell +git clone https://github.com/zehnm/aoostar-rs.git +cd aoostar-rs +``` + +3. Build + +A release build is highly recommended, as it significantly improves graphic rendering performance: + +```shell +cargo build --release +``` + +The binaries will be located in the `./target/release` folder. + +> A Debian package for easy installation is planned for the future! + +See [Linux systemd Service](linux/) on how to automatically switch off the LCD at boot up. + +## Contributing + +Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. diff --git a/linux/README.md b/docs/linux/README.md similarity index 98% rename from linux/README.md rename to docs/linux/README.md index a566a12..b3c145d 100644 --- a/linux/README.md +++ b/docs/linux/README.md @@ -1,6 +1,7 @@ # Linux systemd Service -The systemd unit [lcd-off.service](lcd-off.service) can be installed to automatically switch off the embedded LCD on boot. +The systemd unit [lcd-off.service](https://github.com/zehnm/aoostar-rs/blob/main/linux/lcd-off.service) +can be installed to automatically switch off the embedded LCD on boot. The unit file has been tailored to Debian based Linux distros and has been tested on Proxmox 8.4 and Ubuntu 25.04. diff --git a/docs/sensor/README.md b/docs/sensor/README.md new file mode 100644 index 0000000..89077f3 --- /dev/null +++ b/docs/sensor/README.md @@ -0,0 +1,28 @@ +# Sensor Panels + +- [Sensor panels](panel.md) +- [Custom sensor panels](custom_panel.md) +- [Configuration](cfg/) + +## Sensor Modes + +Different sensor modes are supported: + +- [Sensor mode 1: Text](cfg/mode1_text.md) +- [Sensor mode 2: Circular Progress](cfg/mode2_circular.md) +- [Sensor mode 3: Progress](cfg/mode3_progress.md) +- [Sensor mode 4: Pointer](cfg/mode4_pointer.md) + +## Sensor Data Sources + +The sensor value reading is separated from the `asterctl` tool. + +Sensor values are provided in separate text files and are automatically read when the file changes. +Only the file data source is supported at the moment, other sources like pipes, sockets etc. might be supported later. + +- [Text file data source](provider/text_file.md) + +### Sensor Data Providers + +- Proof of concept [Linux shell scripts](provider/shell_scripts.md) +- [sysinfo tool](provider/sysinfo.md) diff --git a/docs/sensor/cfg/README.md b/docs/sensor/cfg/README.md new file mode 100644 index 0000000..11fa7b0 --- /dev/null +++ b/docs/sensor/cfg/README.md @@ -0,0 +1,43 @@ +# Sensor Configuration + +Specify configuration file to use: +```shell +asterctl --config monitor.json +``` + +- The configuration file is loaded from the configuration directory if not an absolute path is specified. +- The default configuration directory is `./cfg` and can be changed with the `--config-dir` command line option. + +The original AOOSTAR-X json configuration file format is used, but only a subset of the configuration is supported: + +- Setup object fields: + - `switchTime`: Optional switch time between panels in seconds, string value interpreted as float and converted to milliseconds. Default: 5 + - `refresh`: Panel redraw interval in seconds specified as a float number. Default: 1 +- Panel object fields in `diy[]`: + - `img`: Background image filename. Loaded from the specified configuration directory if not an absolute path is specified. + - `sensor`: Array of sensor objects. +- Sensor object fields: + - `label`: label identifier, also used as sensor value data source identifier + - `integerDigits`: sensor value format option: number of integer places. Value is 0-prefixed to number of places and set to `99` if overflown. + - `decimalDigits`: sensor value format option: number of decimal places. + - `unit`: optional unit label, appended after the sensor value + - `x`: x-position + - `y`: y-position + - `fontFamily`: Font name matching font filename without file extension. Fonts are loaded from the configured font directory. + - `fontSize`: Font size + - `fontColor`: Font color in `#RRGGBB` notation, or `-1` if not set. Examples: `#ffffff` = white, `#ff0000` = red. Default: `#ffffff` + - `textAlign`: Text alignment: `left`, `right`, `center` + - Fields used for the fan (2), progress (3) and pointer (4) sensor modes: + - `min_value` and `max_value` + - `width` and `height` + - `direction` + - `pic`: progress image, loaded from the specified configuration directory if not an absolute path is specified. + - `min_angle` and `max_angle` + - `xz_x` and `xz_y` + +Example configuration file: [cfg/monitor.json](https://github.com/zehnm/aoostar-rs/blob/main/cfg/monitor.json). + +Sensor values are not read from the configuration file (the `sensor.value` field is ignored). +See [Sensor Value Provider](../provider). + +More options might be supported later. diff --git a/docs/sensor_mode1_text.md b/docs/sensor/cfg/mode1_text.md similarity index 95% rename from docs/sensor_mode1_text.md rename to docs/sensor/cfg/mode1_text.md index 43d2bd7..c6279de 100644 --- a/docs/sensor_mode1_text.md +++ b/docs/sensor/cfg/mode1_text.md @@ -42,7 +42,7 @@ The sensor value can be formatted with the `unit` and `integerDigits` & `decimal Example `panel.json` with two "text" indicator sensors and the following (partial) background image in `img`: -sensor mode 1 background image example +sensor mode 1 background image example The background image and sensor definitions are taken from the default system panel configuration in the AOOSTAR-X app. @@ -84,7 +84,7 @@ The background image and sensor definitions are taken from the default system pa The following graphic is rendered for the two text fields defined above: -sensor mode 1 example +sensor mode 1 example ## Known Issues diff --git a/docs/sensor_mode2_fan.md b/docs/sensor/cfg/mode2_circular.md similarity index 89% rename from docs/sensor_mode2_fan.md rename to docs/sensor/cfg/mode2_circular.md index a61780e..b4b10d4 100644 --- a/docs/sensor_mode2_fan.md +++ b/docs/sensor/cfg/mode2_circular.md @@ -20,7 +20,7 @@ The following configuration and graphics are taken from the `仪表盘_windows` Example `panel.json` with a single "fan" indicator sensor and the following (partial) background image in `img`: -sensor mode 2 background image example +sensor mode 2 background image example ```json { @@ -52,11 +52,11 @@ Example `panel.json` with a single "fan" indicator sensor and the following (par Progress image `"pic": "progress_circle.png"`: -![progress graphic](img/progress_circle.png) +![progress graphic](../../img/progress_circle.png) The following graphic is rendered for progress example above: -sensor mode 2 example +sensor mode 2 example ## Known Issues diff --git a/docs/sensor_mode3_progress.md b/docs/sensor/cfg/mode3_progress.md similarity index 92% rename from docs/sensor_mode3_progress.md rename to docs/sensor/cfg/mode3_progress.md index b6b84cf..ebc2727 100644 --- a/docs/sensor_mode3_progress.md +++ b/docs/sensor/cfg/mode3_progress.md @@ -14,7 +14,7 @@ Sensor configuration fields: Example `panel.json` with two "progress" indicator sensor and the following (partial) background image in `img`: -sensor mode 3 background image example +sensor mode 3 background image example The background image and sensor definitions are taken from the default system panel configuration in the AOOSTAR-X app. @@ -83,11 +83,11 @@ The background image and sensor definitions are taken from the default system pa Progress image `"pic": "progress.png"`: -![progress graphic](img/progress.png) +![progress graphic](../../img/progress.png) The following graphic is rendered for progress example above: -sensor mode 3 example +sensor mode 3 example ## Known Issues diff --git a/docs/sensor_mode4_pointer.md b/docs/sensor/cfg/mode4_pointer.md similarity index 89% rename from docs/sensor_mode4_pointer.md rename to docs/sensor/cfg/mode4_pointer.md index 5110ff6..f5daf7a 100644 --- a/docs/sensor_mode4_pointer.md +++ b/docs/sensor/cfg/mode4_pointer.md @@ -20,7 +20,7 @@ The following configuration and graphics are taken from the `三环_windows` pan Example `panel.json` with a single "pointer" indicator sensor and the following (partial) background image in `img`: -sensor mode 4 background image example +sensor mode 4 background image example ```json { @@ -52,11 +52,11 @@ Example `panel.json` with a single "pointer" indicator sensor and the following Pointer image `"pic": "pointer.png"`: -![pointer graphic](img/mode4_pic.png) +![pointer graphic](../../img/mode4_pic.png) The following graphic is rendered for a sensor value of `47.7`: -sensor mode 4 example +sensor mode 4 example ## Known Issues diff --git a/docs/sensor_custom_panel.md b/docs/sensor/custom_panel.md similarity index 100% rename from docs/sensor_custom_panel.md rename to docs/sensor/custom_panel.md diff --git a/docs/sensor/panel.md b/docs/sensor/panel.md new file mode 100644 index 0000000..594b4a4 --- /dev/null +++ b/docs/sensor/panel.md @@ -0,0 +1,27 @@ +# Sensor Panels + +The `asterctl` tool is started in sensor panel mode if the `--config` command line option is specified. + +Sensor panels are dynamic screens showing various sensor values. Multiple rotating panels are supported. +The sensor values must be provided in simple key-value text files from external scripts or tools. The `asterctl` tool +is only responsible for rendering the panels on the embedded screen. + +Example panels from the AOOSTAR-X software, rendered with `asterctl` using dummy sensor values: + +Sensor panel 1 + +Sensor panel 1 + +See [custom sensor panels](custom_panel.md) for including custom panels. + +## Supported Features + +- One or multiple panels rotating in configurable interval (configuration value `setup.switchTime`). +- Each panel can be configured with multiple sensor fields. + - Text sensor value fields are supported (`sensor.mode: 1`), but there are still some text size and positioning issues. + - Fan (2), progress (3) and pointer (4) sensor modes are being worked on and not all configuration options are working yet. +- Each sensor field can be customized with an individual font, size, color and text alignment. +- Panels are redrawn at a configurable interval (configuration value `setup.refresh`). + - Only the updated areas of the image are sent to the display for faster updates. + +See [Sensor Configuration](cfg/) for more information. diff --git a/docs/sensor/provider/README.md b/docs/sensor/provider/README.md new file mode 100644 index 0000000..4024e34 --- /dev/null +++ b/docs/sensor/provider/README.md @@ -0,0 +1 @@ +# Sensor Value Provider diff --git a/docs/sensor_data_shell.md b/docs/sensor/provider/shell_scripts.md similarity index 88% rename from docs/sensor_data_shell.md rename to docs/sensor/provider/shell_scripts.md index 7a5f749..9ce0155 100644 --- a/docs/sensor_data_shell.md +++ b/docs/sensor/provider/shell_scripts.md @@ -1,6 +1,6 @@ # Sensor Data Provider Shell Scripts -The [/linux/scripts](../linux/scripts) directory contains some proof-of-concept Linux 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`. diff --git a/docs/sensor_data_sysinfo.md b/docs/sensor/provider/sysinfo.md similarity index 85% rename from docs/sensor_data_sysinfo.md rename to docs/sensor/provider/sysinfo.md index feacc4b..3993120 100644 --- a/docs/sensor_data_sysinfo.md +++ b/docs/sensor/provider/sysinfo.md @@ -1,6 +1,6 @@ # sysinfo Tool -The Rust based [sysinfo](../crates/sysinfo/src/main.rs) tool gathers many more system sensor values with the help of +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. @@ -18,7 +18,8 @@ Options: 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! + The temp directory must be on the same file system for atomic rename + operation! --console Print values in console @@ -27,7 +28,8 @@ Options: System sensor refresh interval in seconds --disk-refresh - Enable individual disk refresh logic as used in AOOSTAR-X. Refresh interval in seconds + Enable individual disk refresh logic as used in AOOSTAR-X. + Refresh interval in seconds --smartctl Retrieve drive temperature if `disk-update` option is enabled. diff --git a/docs/sensor_data_txt_file.md b/docs/sensor/provider/text_file.md similarity index 94% rename from docs/sensor_data_txt_file.md rename to docs/sensor/provider/text_file.md index 878fe7f..5d6d128 100644 --- a/docs/sensor_data_txt_file.md +++ b/docs/sensor/provider/text_file.md @@ -17,7 +17,7 @@ - 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](../cfg/monitor.json) panel configuration: +Example text file for the [cfg/monitor.json](https://github.com/zehnm/aoostar-rs/blob/main/cfg/monitor.json) panel configuration: ``` cpu_temperature: 65 diff --git a/docs/sensor_panels.md b/docs/sensor_panels.md deleted file mode 100644 index cf923b4..0000000 --- a/docs/sensor_panels.md +++ /dev/null @@ -1,68 +0,0 @@ -# Sensor Panels - -The `asterctl` tool is started in sensor panel mode if the `--config` command line option is specified. - -Sensor panels are dynamic screens showing various sensor values. Multiple rotating panels are supported. -The sensor values must be provided in simple key-value text files from external scripts or tools. The `asterctl` tool -is only responsible for rendering the panels on the embedded screen. - -Example panels from the AOOSTAR-X software, rendered with `asterctl` using dummy sensor values: - -Sensor panel 1 - -Sensor panel 1 - -## Supported Features - -- One or multiple panels rotating in configurable interval (configuration value `setup.switchTime`). -- Each panel can be configured with multiple sensor fields. - - Text sensor value fields are supported (`sensor.mode: 1`), but there are still some text size and positioning issues. - - Fan (2), progress (3) and pointer (4) sensor modes are being worked on and not all configuration options are working yet. -- Each sensor field can be customized with an individual font, size, color and text alignment. -- Panels are redrawn at a configurable interval (configuration value `setup.refresh`). - - Only the updated areas of the image are sent to the display for faster updates. - -## Panel Configuration File - -Specify configuration file to use: -```shell -asterctl --config monitor.json -``` - -- The configuration file is loaded from the configuration directory if not an absolute path is specified. -- The default configuration directory is `./cfg` and can be changed with the `--config-dir` command line option. - -The original AOOSTAR-X json configuration file format is used, but only a subset of the configuration is supported: - -- Setup object fields: - - `switchTime`: Optional switch time between panels in seconds, string value interpreted as float and converted to milliseconds. Default: 5 - - `refresh`: Panel redraw interval in seconds specified as a float number. Default: 1 -- Panel object fields in `diy[]`: - - `img`: Background image filename. Loaded from the specified configuration directory if not an absolute path is specified. - - `sensor`: Array of sensor objects. -- Sensor object fields: - - `label`: label identifier, also used as sensor value data source identifier - - `integerDigits`: sensor value format option: number of integer places. Value is 0-prefixed to number of places and set to `99` if overflown. - - `decimalDigits`: sensor value format option: number of decimal places. - - `unit`: optional unit label, appended after the sensor value - - `x`: x-position - - `y`: y-position - - `fontFamily`: Font name matching font filename without file extension. Fonts are loaded from the configured font directory. - - `fontSize`: Font size - - `fontColor`: Font color in `#RRGGBB` notation, or `-1` if not set. Examples: `#ffffff` = white, `#ff0000` = red. Default: `#ffffff` - - `textAlign`: Text alignment: `left`, `right`, `center` - - Fields used for the fan (2), progress (3) and pointer (4) sensor modes: - - `min_value` and `max_value` - - `width` and `height` - - `direction` - - `pic`: progress image, loaded from the specified configuration directory if not an absolute path is specified. - - `min_angle` and `max_angle` - - `xz_x` and `xz_y` - -Example configuration file: [cfg/monitor.json](../cfg/monitor.json). - -Sensor values are not read from the configuration file (the `sensor.value` field is ignored). See data sources below. - -More options might be supported later. - -See [custom sensor panels](sensor_custom_panel.md) for including custom panels.