magges/aoostar-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: use mdBook for documentation (#10)

Browse Source
This commit is contained in:
Markus Zehnder
2025-08-28 23:22:04 +02:00
committed by GitHub
parent d98cd89c48
commit 3414589bd5
24 changed files with 317 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sensor/cfg/README.md
+43
View File
@@ -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.
docs/sensor/cfg/mode1_text.md
+96
View File
@@ -0,0 +1,96 @@
# Sensor Mode 1 Text
A text sensor renders a text label with a sensor value and an optional unit text on the panel.
The value can be formatted as a fixed point decimal number or as an integer.
Text sensor configuration fields:
- `mode`: 1 (for text)
- `label`: label identifier, also used as sensor value data source identifier
- `direction`: 1 = left to right, 2 = right to left, 3 = top to bottom, 4 = bottom to top
- `label`: data source id to retrieve the current value from
- `unit`: optional unit label, appended after the sensor value
- `x`, `y`: position on the panel
- `fontFamily`: Font name matching font filename without file extension.
- Fonts are loaded from the configured font directory, or from the custom panel's `fonts` directory.
- An absolute file path can also be used.
- `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`, `center`, `right`
- `integerDigits`: number of integer digits: -1 or missing field = all digits, > 0 prefix with `0` and set to `9` if overflown
- `decimalDigits`: number fixed point digits: -1 = auto, 0 = integer number without decimal digits, > 0 fixed number of decimal digits
## Value Formatting
The sensor value can be formatted with the `unit` and `integerDigits` & `decimalDigits` options.
- The unit value is simply appended to the value, without whitespace.
- Example formatting for the value `123.456` with `integerDigits` & `decimalDigits`:
| integer | decimal | output |
|---------|---------|----------|
| 5 | 2 | 00123.46 |
| 5 | 1 | 00123.5 |
| 5 | 0 | 00123 |
| -1 | 2 | 123.46 |
| -1 | 1 | 123.5 |
| -1 | 0 | 123 |
| 2 | 0 | 99 |
## Example
Example `panel.json` with two "text" indicator sensors and the following (partial) background image in `img`:
<img src="../../img/sensor_mode1_background.png" alt="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.
```json
{
"name": "Text test panel",
"img": "background.png",
"sensor": [
{
"mode": 1,
"name": "CPU temp",
"label": "cpu_temperature",
"x": 195,
"y": 110,
"value": "65",
"fontFamily": "HarmonyOS_Sans_SC_Bold",
"fontSize": 120,
"fontColor": -1,
"textAlign": "center",
"decimalDigits": 0
},
{
"mode": 1,
"name": "CPU usage",
"label": "cpu_percent",
"unit": "%",
"x": 200,
"y": 285,
"value": "47.4",
"fontFamily": "HarmonyOS_Sans_SC_Bold",
"fontSize": 60,
"fontColor": -1,
"textAlign": "center",
"decimalDigits": 0
}
]
}
```
The following graphic is rendered for the two text fields defined above:
<img src="../../img/sensor_mode1.png" alt="sensor mode 1 example">
## Known Issues
Text sensor formatting has been reverse engineered from the AOOSTAR-X app. Not all options are supported
- Text position and font size calculation doesn't always match AOOSTAR-X.
- Needs investigation if value is in pixel or points.
- Might also need dpi adjustments.
- `fontWeight` not yet supported.
docs/sensor/cfg/mode2_circular.md
+69
View File
@@ -0,0 +1,69 @@
# Sensor Mode 2 Circular Progress
A circular progress sensor (known as `fan` in the AOOSTAR-X software) masks a progress bar image for a certain angular
range based on the corresponding sensor value. The masked image is alpha-blended with the panel image.
Sensor configuration fields:
- `mode`: 2 (for fan)
- `direction`: 1 = clockwise, 2 = counter-clockwise
- `label`: label identifier, also used as sensor value data source identifier
- `x`, `y`: position on the panel
- `width`, `height`: size of the circular progress element (not yet used)
- `pic`: circular progress image to overlay. Should match `width`, `height`
- `minAngle`, `maxAngle`: range of the masked image
- `minValue`, `maxValue`: clamp sensor value to this range
- `xz_x`, `xz_y`
## Example
The following configuration and graphics are taken from the `仪表盘_windows` panel configuration in `有线网卡 windows驱动.rar`.
Example `panel.json` with a single "fan" indicator sensor and the following (partial) background image in `img`:
<img src="../../img/sensor_mode2_background.jpg" alt="sensor mode 2 background image example">
```json
{
"name": "Fan test panel",
"img": "background.jpg",
"sensor": [
{
"id": "29d9ef2d-30b4-459d-b2b0-43cb6d4d6b41",
"itemName": "CPU usage",
"mode": 2,
"direction": 1,
"label": "cpu_percent",
"value": "47.7",
"x": 168,
"y": 184,
"width": 237,
"height": 237,
"minAngle": -160,
"maxAngle": 30,
"minValue": 0,
"maxValue": 80,
"xz_x": 0,
"xz_y": 0,
"pic": "progress_circle.png"
}
]
}
```
Progress image `"pic": "progress_circle.png"`:
![progress graphic](../../img/progress_circle.png)
The following graphic is rendered for progress example above:
<img src="../../img/sensor_mode2.jpg" alt="sensor mode 2 example">
## Known Issues
Fan sensor rendering has been reverse engineered from the AOOSTAR-X app. Not all options are supported.
- Work in progress, not yet fully tested
- `direction: 2` doesn't seem to work
- `widht`, `height` should be considered and auto-resized as for mode 4
docs/sensor/cfg/mode3_progress.md
+98
View File
@@ -0,0 +1,98 @@
# Sensor Mode 3 Progress
A progress sensor crops a progress image based on the corresponding sensor value and alpha-blends it with the panel image.
Sensor configuration fields:
- `mode`: 3 (for progress)
- `label`: label identifier, also used as sensor value data source identifier
- `direction`: 1 = left to right, 2 = right to left, 3 = top to bottom, 4 = bottom to top
- `x`, `y`: position on the panel
- `pic`: progress image to crop and overlay
- `minValue`, `maxValue`: clamp sensor value to this range
## Example
Example `panel.json` with two "progress" indicator sensor and the following (partial) background image in `img`:
<img src="../../img/sensor_mode3_background.png" alt="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.
```json
{
"name": "Progress test panel",
"img": "background.png",
"sensor": [
{
"mode": 3,
"name": "SSD 4 usage",
"label": "storage_ssd4_usage",
"x": 400,
"y": 45,
"direction": 1,
"value": "35",
"minValue": 0,
"maxValue": 100,
"pic": "progress.png"
},
{
"mode": 3,
"name": "SSD 5 usage",
"label": "storage_ssd5_usage",
"x": 400,
"y": 106,
"direction": 1,
"value": "80",
"minValue": 0,
"maxValue": 100,
"pic": "progress.png"
},
{
"mode": 1,
"name": "SSD 4 temp",
"label": "storage_ssd4_temperature",
"x": 580,
"y": 70,
"direction": 1,
"value": "34",
"fontFamily": "HarmonyOS_Sans_SC_Bold",
"fontSize": 24,
"textAlign": "center",
"integerDigits": -1,
"decimalDigits": 0,
"unit": " ℃"
},
{
"mode": 1,
"name": "SSD 5 temp",
"label": "storage_ssd5_temperature",
"x": 580,
"y": 130,
"direction": 1,
"value": "35",
"fontFamily": "HarmonyOS_Sans_SC_Bold",
"fontSize": 24,
"textAlign": "center",
"integerDigits": -1,
"decimalDigits": 0,
"unit": " ℃"
}
]
}
```
Progress image `"pic": "progress.png"`:
![progress graphic](../../img/progress.png)
The following graphic is rendered for progress example above:
<img src="../../img/sensor_mode3.png" alt="sensor mode 3 example">
## Known Issues
Progress sensor rendering has been reverse engineered from the AOOSTAR-X app. Not all options are supported.
- Work in progress, not yet fully tested
- `widht`, `height` should be considered and auto-resized as for mode 4
docs/sensor/cfg/mode4_pointer.md
+65
View File
@@ -0,0 +1,65 @@
# Sensor Mode 4 Pointer
A pointer sensor rotates an image at a certain angle calculated from the current sensor value and alpha-blends it with
the panel image.
Sensor configuration fields:
- `mode`: 4 (for pointer)
- `direction`: 1 = clockwise, 2 = counter-clockwise
- `label`: label identifier, also used as sensor value data source identifier
- `x`, `y`: position on the panel
- `width`, `height`: size of the pointer
- `pic`: pointer image to overlay. Should match `width`, `height`, otherwise it will be resized
- `minAngle`, `maxAngle`: range of the rotated image
- `minValue`, `maxValue`: scaling range to apply on the value for `minAngle` .. `maxAngle` (to be verified)
- `xz_x`, `xz_y`
## Example
The following configuration and graphics are taken from the `三环_windows` panel configuration in `有线网卡 windows驱动.rar`.
Example `panel.json` with a single "pointer" indicator sensor and the following (partial) background image in `img`:
<img src="../../img/sensor_mode4_background.png" alt="sensor mode 4 background image example">
```json
{
"name": "Pointer test panel",
"img": "background.jpg",
"sensor": [
{
"id": "a9d4acac-2af9-4fe0-9f69-86cd09f25696",
"itemName": "CPU dial",
"mode": 4,
"direction": 1,
"label": "cpu_percent",
"value": "47.7",
"x": 160,
"y": 208,
"width": 302,
"height": 302,
"minAngle": -110,
"maxAngle": 110,
"minValue": 0,
"maxValue": 90,
"xz_x": 0,
"xz_y": 0,
"pic": "pointer.png"
}
]
}
```
Pointer image `"pic": "pointer.png"`:
![pointer graphic](../../img/mode4_pic.png)
The following graphic is rendered for a sensor value of `47.7`:
<img src="../../img/sensor_mode4.png" alt="sensor mode 4 example">
## Known Issues
Pointer sensor rendering has been reverse engineered from the AOOSTAR-X app. Not all options are supported.
- Work in progress, not yet fully tested