docs(readme): restructure and correct content - #272
Conversation
voidvore
commented
Aug 5, 2026
voidvore
commented
- Reorganize into clear sections and a package table
- Remove dead references to make bindings/introspection and typeshare
- Fix aura_support.ron path (rog-aura/data/, not data/layouts/)
- Align model lists with code: drop the fan-curve list, add the omitted Strix Scar 16/18 for AniMe
- Note that platform and fan controls need asus-nb-wmi/asus-armoury
- Link CONTRIBUTING.md and require cargo-cranky for the git hooks
- Tighten prose and drop editorial asides
- Reorganize into clear sections and a package table - Remove dead references to make bindings/introspection and typeshare - Fix aura_support.ron path (rog-aura/data/, not data/layouts/) - Align model lists with code: drop the fan-curve list, add the omitted Strix Scar 16/18 for AniMe - Note that platform and fan controls need asus-nb-wmi/asus-armoury - Link CONTRIBUTING.md and require cargo-cranky for the git hooks - Tighten prose and drop editorial asides
📝 WalkthroughSummary by CodeRabbit
WalkthroughREADME.md was reorganized and rewritten. It now covers project notices, compatibility, features, installation, service management, source builds, upgrades, development, licensing, and AI contributions. ChangesREADME documentation
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
Comment |
coderabbitai
Bot
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 187-188: Update the “Laptop support requests” section in README.md
to include a direct hyperlink to the project’s issue tracker, replacing or
augmenting the generic “project issue tracker” reference while preserving the
existing support-request guidance.
- Around line 10-14: Update README.md to satisfy Markdown linting by adding
blank lines after headings and before and after every fenced code block,
including the affected sections. Separate the IMPORTANT and WARNING admonitions
with a blank line so they remain distinct blocks, while preserving their
existing content and structure.
- Around line 156-163: Update the source uninstall instructions in the
“Uninstalling” section to stop and disable the asusd service before running sudo
make uninstall, then reload systemd afterward so active processes and removed
unit state are handled.
- Around line 124-128: Remove gtk3-devel from the openSUSE installation command
in the openSUSE prerequisites while preserving the “without GTK dependencies”
wording and all other listed packages.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: ad9cd379-186a-482e-944e-8caaf73162e5
📒 Files selected for processing (1)
README.md
📜 Review details
🧰 Additional context used
🪛 LanguageTool
README.md
[style] ~104-~104: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...vation may require manual intervention. On Pop!_OS systems, disable the `system76-...
(ENGLISH_WORD_REPEAT_BEGINNING_RULE)
🪛 markdownlint-cli2 (0.23.2)
README.md
[warning] 12-12: Blank line inside blockquote
(MD028, no-blanks-blockquote)
[warning] 32-32: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 37-37: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 39-39: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 45-45: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 50-50: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 60-60: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 66-66: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 72-72: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 77-77: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 95-95: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 99-99: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 110-110: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 111-111: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 117-117: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 118-118: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 124-124: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 126-126: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 133-133: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 135-135: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 142-142: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 143-143: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 149-149: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 151-151: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 153-153: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 156-156: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 158-158: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 160-160: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 167-167: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 177-177: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 181-181: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 184-184: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
[warning] 187-187: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 192-192: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
[warning] 203-203: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🔇 Additional comments (1)
README.md (1)
1-9: LGTM!Also applies to: 15-31, 40-44, 56-59, 80-94, 103-105, 165-166
|
@coderabbitai autofix |
|
This command requires write access to the repository. Only users with write or admin permissions can trigger CodeRabbit to commit or create pull requests. |
Updated project name from 'asusctl for ASUS laptops' to 'asusctl for ASUS ROG' and made various adjustments throughout the README.
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
README.md (2)
95-99: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winReplace or remove the empty openSUSE repository link.
The linked OBS directory currently reports
Directory is empty. (download.opensuse.org) Update the link and installation instructions to an active repository, or remove this row until a package is published.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.md` around lines 95 - 99, Update the openSUSE row in the distribution table to reference an active OBS repository with accurate installation instructions, or remove the row entirely until packages are published; do not retain the empty repository link or its current “Add OBS repository” guidance.
106-113: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winRun all system-service commands with root privileges.
Both sections invoke systemd without
sudo.
README.md#L106-L113: usesudoand start the staticasusd.serviceinstead of enabling it.README.md#L167-L173: usesudofordaemon-reloadandrestart.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.md` around lines 106 - 113, Update README.md lines 106-113 to run both service commands with sudo and start the static asusd.service without enabling it; update README.md lines 167-173 to prefix the systemctl daemon-reload and restart commands with sudo.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 129-135: Update the Fedora prerequisites in the README to install
or explicitly set up the required Rust toolchain and Cargo before the existing
make command. Keep the current Fedora dependency installation intact and ensure
the documented setup provides the selected toolchain needed by the build.
---
Outside diff comments:
In `@README.md`:
- Around line 95-99: Update the openSUSE row in the distribution table to
reference an active OBS repository with accurate installation instructions, or
remove the row entirely until packages are published; do not retain the empty
repository link or its current “Add OBS repository” guidance.
- Around line 106-113: Update README.md lines 106-113 to run both service
commands with sudo and start the static asusd.service without enabling it;
update README.md lines 167-173 to prefix the systemctl daemon-reload and restart
commands with sudo.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: e4d35378-942e-4b26-b862-8bf119d6bb6f
📒 Files selected for processing (1)
README.md
📜 Review details
🔇 Additional comments (2)
README.md (2)
177-185: Stop both installed services before uninstalling.The Makefile installs
asusd.serviceandasus-shutdown.service, but this sequence handles onlyasusd.service. Also, the staticasusd.servicecannot be disabled. Stop both services, then disable only units that support disabling before removing their files.
1-1: LGTM!Also applies to: 33-60, 66-88, 100-103, 115-127, 137-146, 148-165, 191-219, 225-237
| #### Fedora | ||
|
|
||
| ```sh | ||
| sudo dnf install cmake clang-devel libxkbcommon-devel systemd-devel expat-devel pcre2-devel libzstd-devel gtk3-devel | ||
| make | ||
| sudo make install | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Install the Rust toolchain in the Fedora prerequisites.
The README requires Rust and Cargo, but this Fedora command installs neither rust, rustup, nor cargo. Add the selected toolchain package or document an explicit rustup setup before make.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 129 - 135, Update the Fedora prerequisites in the
README to install or explicitly set up the required Rust toolchain and Cargo
before the existing make command. Keep the current Fedora dependency
installation intact and ensure the documented setup provides the selected
toolchain needed by the build.
| | **Ultramarine / Nobara** | Official Repositories | `sudo dnf install asusctl` | Direct package installation | | ||
| | **Fedora** | [Terra Repository](https://terrapkg.com/) | `sudo dnf install asusctl` | Requires Terra repository enabled | | ||
| | **openSUSE** | [OBS Repository](https://download.opensuse.org/repositories/home:/luke_nukem:/asus/) | Add OBS repository | Maintained on OpenSUSE Build Service | | ||
| | **Arch Linux** | AUR | `yay -S asusctl` | Maintained in AUR as `asusctl` | |
There was a problem hiding this comment.
Link to OGC arch pacman repo guide here for now. the AUR version is not maintained by us yet
| Restart `asusd` after starting the simulator to attach the service to the simulated display interface. Running the simulator on a laptop with a physical display redirects display output to the simulator window. | ||
|
|
||
| Mozilla Public License 2 (MPL-2.0) | ||
| ### Laptop support requests |
There was a problem hiding this comment.
For PPT sliders specifically the issue is #124
As for Backlight support, the procedure is to test changes to local aura_support.ron file and create a PR once the user is able to get it working. Irc we should've had a similar guide elsewhere for this
| See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow. Install `cargo-cranky`, then run `cargo test` once to set up the `cargo-husky` commit hooks: | ||
|
|
||
| D-Bus introspection XML requires with `make introspection` requires `anime_sim` to be running before starting `asusd`. | ||
| ```sh | ||
| cargo install cargo-cranky | ||
| cargo test | ||
| ``` |
There was a problem hiding this comment.
the mention of precommit and prepush hooks should be in CONTRIBUTING.md. not here
| ### AI contribution policy | ||
|
|
||
| AI contributions are welcomed like any other contributions, as long as they are reviewed and tested by the human pushing them before being merged. | ||
| Contributions created with AI assistance are reviewed under standard code contribution guidelines. All AI-assisted submissions must be reviewed, verified, and tested by the author before submitting a pull request. |
There was a problem hiding this comment.
I would say leave this as it was until I am able to think of proper guidelines for AI contributions, then I will write more on this myself
| > [!IMPORTANT] | ||
| > **Project Migration Notice:** This repository has migrated to the OpenGamingCollective ([OGC](https://github.com/opengamingcollective)) on [GitHub](https://github.com/opengamingcollective/asusctl). Active development takes place on the new repository. The legacy [GitLab page](https://gitlab.com/asus-linux/asusctl) is preserved for historical reference only. |
There was a problem hiding this comment.
We can remove this from the readme here, it only needs to remain on gitlab
| ``` | ||
|
|
||
| **Remember**: Using an unmaintained display server is your own choice and the responsibility falls on yourself. We cannot help you with this. | ||
| Devices displaying these hardware IDs typically function without extra configuration. Features such as battery charge thresholds use generic kernel interfaces and can work on other hardware, but platform and fan controls require the ASUS-specific `asus-nb-wmi` or `asus-armoury` drivers. |
There was a problem hiding this comment.
The original text also mentioned Anime matrix, LED, (and also slash) will work regardless of your laptop make, but was dropped here. For those, if it is a new laptop, then adding support will be needed. With that you can write "See (the section about adding support)"
| ### Kernel requirements | ||
|
|
||
| The main goal of this work is to provide a safe and easy to use abstraction over various laptop features via D-Bus, and to provide some helpful defaults and other behaviour such as toggling throttle/profile on AC/battery change. | ||
| Maintainers recommend running the latest stable Linux kernel, as driver improvements are merged upstream continuously. | ||
|
|
||
| - Provide safe D-Bus interface | ||
| - Respect the users resources: be small, light, and fast | ||
| Thermal Design Power (TDP) controls require the `asus-armoury` driver, which was included in mainline Linux starting with version 6.19. Kernels older than 6.19 do not support TDP management. |
There was a problem hiding this comment.
I feel this is becoming unnecessarily longer than the original while still stating the same thing. This could just be
Due to ongoing development, the minimum suggested kernel version is always **the latest**, as improvements are merged upstream continuously.
Support for Thermal Design Power (TDP) is tied to the new `asus-armoury` driver: available mainline since Linux 6.19: everything older is not supported.
2 participants
