Repository navigation
Releases
NeoSense 2.4.0
NeoSense 2.4.0 — release notes
Status: stable release, published 2026-11-19. The 2.3.0 archive remains
frozen and unpublished. This version makes the terminal application the primary
fan-control interface and completes the everyday Auto / Silent / Balanced /
Maximum workflow.
Highlights
Everyday cooling
- Auto restores the NBFC temperature-dependent software curve, the normal
automatic behavior on the validated Acer Nitro AN515-57. - Silent 25%, Balanced 60% and Maximum 100% are fixed logical
targets with supervisor preflight, backend verification, multi-fan leases and
a 15-minute automatic recovery. - CPU / GPU / Both manual control is bounded to 20–100%; 0% is refused.
- CLI preset commands accept
--yesfor explicit confirmation and--dry-run
for policy validation without a write.
Terminal UI
- Branded typographic identity: a bold ANSI Shadow-inspired
NEOSENSEbanner
with theLINUX THERMAL MANAGEMENTdescriptor and a telemetry rail on large
terminals, a compact two-row wordmark at medium sizes and a one-line wordmark
on small terminals. A strict printable-ASCII banner is selected automatically
on non-UTF-8 locales or withNEOSENSE_ASCII=1. - Consistent visual language across all seven views: compact header, filled
active tab, inset rounded panels, one accent colour, and●/▶markers for
active and selected states. - Dashboard prioritises the active mode, backend targets, both fan states,
temperatures, safety and warnings, with one-key mode selection. - Fan Control adds a selectable Both fans row alongside CPU and GPU, a
target bar, lease countdown and clearer requested/target/EC separation. - Presets render as mode cards on wide terminals and an aligned list on narrow
ones. - Profiles show active, selected and blocked states distinctly, with live
preview targets and curve detail. - Mode selection (Auto, preset or profile) applies immediately. Manual
percentage changes still asky/n. - Small-terminal layouts collapse gracefully; the tab bar switches to an index
below 62 columns.
Profiles
- Supervisor-owned closed-loop application with per-fan preflight, target
verification, partial application and blocked-fan reporting. - Preview (
profile preview, TUIp) remains local or simulation-only and
never writes fans. - Persistent custom curves: versioned JSON, strict validation, atomic writes,
backup, corruption recovery, CLI CRUD and TUI$EDITORediting. - Built-in curves are reference policies, not measured fan-response curves.
Installation
- Unified
neosense.shentry point with distribution detection, DNF/APT/Pacman/
Zypper dependency adapters, version checks, explicit privileged-operation
authorization, NBFC/backend state detection, competing-controller reporting
and read-only post-install verification. - Missing or incompatible fan backends abort the default installation before
software changes;--software-onlyis explicit and does not start the
supervisor. NBFC configuration and unrelated controllers are never modified. - Isolated installer-flow tests cover the supported distribution families,
missing/old dependencies, backend states, conflicts, dry-run and
non-interactive safety.
Safety and operations
neosensedremains the sole fan-write authority; the CLI and TUI use IPC only.- Lease expiry, stale telemetry, lost access control, NBFC critical mode and
failed verification trigger automatic recovery. An unconfirmed recovery is a
distinct fail-safe state. - Systemd
Type=notify,WatchdogSec=10sand anExecStopPostfail-safe. - Installer supports in-place upgrade, creates a timestamped backup and restores
the previous binaries/unit if verification fails. Uninstall preserves custom
profiles and validation evidence. - Host deployment of an earlier 2.4.0 candidate (
897e757) was verified
read-only: installed hashes matched, the supervisor reached READY, the
watchdog advanced, the socket remainedroot:neosense 0660, and both fans
returned to their normal automatic state. The current candidate was later
installed on the development host outside the release mission and verified
read-only: supervisor healthy, safetysafe_auto, both fans automatic, zero
critical diagnostics, NBFC untouched. SeeHOST_INSTALL.mdfor the exact
hashes, backups and deployment/rollback checklist. install.sh/uninstall.shexpose--help, reject unsupported custom runtime
and state paths for real systemd installs, and only print next-step hints that
still apply. Release archives record package, target, profile, Rust and Cargo
versions and are reproducible with the recorded toolchain.- A genuine Fedora 44 KVM VM validation installed the release archive, started
the supervisor without a backend, verified socket/permissions, exercised an
upgrade, restored files after an injected unit failure, and preserved
profile/validation data on uninstall. The official NBFC 0.5.4 Fedora RPM was
checksum-verified and installed, but its service could not start without a
laptop configuration or EC hardware. Backend-ready and physical validation
remain separate.
Validation
- CPU logical channel accepted at 0/50/100% (earlier supervisor session).
- GPU logical channel observed at 50/75/100% on 2026-11-17 with the CPU fan
automatic, 80/75 °C ceilings and verified Auto recovery. - Operator-attested mapping: CPU→LEFT, GPU→RIGHT.
- No independent RPM or airflow reference exists. Percentages are backend
targets; EC readback is not RPM. - See
docs/VALIDATION_RESULTS.mdfor the authoritative record.
Tests
460 automated Rust tests: 376 library, 75 CLI/integration, 7 low-level
installer, 1 English-only language guard, plus an additional binary test target.
A separate 66-case shell suite covers the unified installer's distribution
detection, dependency resolution, backend states, conflicts and dry-run safety. Coverage
includes policy, presets, profiles, custom-profile recovery, IPC, daemon
lifecycle, TUI navigation and rendering at small and large sizes, installer
rollback, PTY validation flows and JSON schemas.
Known limitations
- No independent RPM/airflow calibration; physical identity of the EC channels
remains unverified. - EC readback is a clamp artifact with
IndependentReadMinMaxValues=false. - Both NBFC fans declare
@CPU; the GPU logical channel relies on an
independent NVIDIA temperature guard and is reported as a warning. - Profiles are reference curves, not measured hardware response.
fan releaseremains unavailable until EC/firmware return is validated.- No broad laptop compatibility claim is made from a single machine.
Upgrade notes
Run sudo ./install.sh from the new archive or source checkout. Existing
profiles and validation evidence under /var/lib/neosense are preserved. An
already-running supervisor is restarted and verified; its designed shutdown
fail-safe may return NBFC to automatic mode. Use --no-restart to defer the
restart.
v1.0.1 NeoSense
NeoSense
Your laptop. Your fans. Your control.
A modern, elegant CLI wrapper for NBFC — inspired by Acer NitroSense.
Features · Preview · Installation · Commands · Roadmap
◈ Overview
NeoSense brings a clean, straightforward command-line experience to NBFC (Notebook FanControl) on Linux.
Control fan speeds, switch performance profiles, manage the NBFC service, and inspect your system's thermal status without memorizing a collection of low-level commands.
Built with modular Bash scripts, NeoSense aims to make laptop thermal management more accessible while keeping the interface lightweight, readable, and extensible.
NeoSense is a wrapper around NBFC, not a replacement for it. Hardware compatibility and low-level fan control depend on your NBFC installation and configuration.
⌁ Preview
A quick look at the NeoSense command-line interface:
_ _ ____
| \ | | ___ ___ / ___| ___ _ __ ___ ___
| \| |/ _ \/ _ \\___ \ / _ \ '_ \/ __|/ _ \
| |\ | __/ (_) |___) | __/ | | \__ \ __/
|_| \_|\___|\___/|____/ \___|_| |_|___/\___|
NeoSense v1.0
A modern NBFC wrapper
COMMANDS
├─ status System & thermal status
├─ auto / manual Fan control modes
├─ set Manual fan speeds
├─ turbo Maximum fan preset
├─ performance Performance preset
├─ balanced Everyday preset
├─ silent Low-noise preset
├─ daemon Service management
└─ config NBFC profiles
Illustrative layout of the available commands, not a verbatim terminal capture.
⚡ Features
| Feature | Description |
|---|---|
| ◉ Fan control | Switch between automatic and manual operation, or set CPU and GPU fan speeds individually or together. |
| ⚡ Performance presets | Quickly select Turbo, Performance, Balanced, or Silent fan profiles. |
| ⌖ Thermal monitoring | Inspect the active configuration, service state, temperatures, and current and target fan speeds. |
| ⚙ Service management | Enable, disable, restart, and inspect the NBFC systemd service directly from the CLI. |
| ▦ Configuration profiles | List available NBFC profiles, inspect the active profile, and apply a different configuration. |
| ⌘ Lightweight architecture | Modular Bash scripts with separate responsibilities for commands, system operations, configuration, and output. |
▸ Installation
Requirements
- A Linux distribution
- Bash and standard system utilities
- NBFC Linux installed and configured
sudoprivileges for operations that require elevated permissions
NBFC support varies by laptop model. Confirm that your hardware is supported and that its configuration works before using NeoSense to control the fans.
1. Install NBFC
On Arch Linux or Manjaro, if the package is available in your configured repositories or AUR helper:
yay -S nbfc-linuxOn other distributions, follow the installation instructions in the official nbfc-linux repository.
2. Install NeoSense
Clone the repository:
git clone https://github.com/NeonMC23/NeoSense.git
cd NeoSenseRun the installer:
sudo ./install.shThe installation script is intended to:
- Check that NBFC is installed.
- Install NeoSense files under
/usr/local/share/neosense/. - Create the
neosensecommand under/usr/local/bin/.
After installation, display the available commands:
neosense --helpCheck the installed version:
neosense --version⌘ Commands
System status
neosense statusDisplays the active NBFC configuration, service state, autostart state, operating mode, temperatures, and current and target fan speeds when the underlying system exposes those values.
Fan control
| Command | Description |
|---|---|
neosense auto |
Switch all fans to automatic mode |
neosense manual |
Switch to manual mode while keeping current speeds |
neosense set cpu <0-100> |
Set the CPU fan speed |
neosense set gpu <0-100> |
Set the GPU fan speed |
neosense set both <0-100> |
Set both fan speeds |
Examples:
neosense auto
neosense manual
neosense set cpu 75
neosense set gpu 65
neosense set both 80Performance presets
Choose a preset according to your workload:
| Preset | CPU fan | GPU fan | Typical use |
|---|---|---|---|
| 🔥 Turbo | 100% | 100% | Maximum cooling |
| ⚡ Performance | 80% | 80% | Gaming and heavy workloads |
| ◈ Balanced | 60% | 60% | Everyday use |
| ❄️ Silent | 25% | 25% | Light workloads |
neosense turbo
neosense performance
neosense balanced
neosense silentPreset percentages are the values defined by NeoSense; actual fan behavior depends on hardware and NBFC support.
NBFC service
| Command | Action |
|---|---|
neosense daemon enable |
Enable and start the service |
neosense daemon disable |
Stop and disable the service |
neosense daemon restart |
Restart the service |
neosense daemon status |
Inspect the service state |
Configuration profiles
| Command | Action |
|---|---|
neosense config current |
Show the active profile |
neosense config list |
List available NBFC profiles |
neosense config use "Acer Nitro AN515-57" |
Apply a profile and restart the service |
Use the exact configuration name reported by neosense config list on your system.
⚠️ Safety & compatibility
Fan control interacts with hardware-specific behavior. Incorrect settings can lead to excessive temperatures or unnecessary noise.
- Verify that NBFC supports your laptop and that its configuration is correct.
- Monitor CPU and GPU temperatures after changing fan settings.
- Avoid low manual fan speeds under sustained heavy workloads.
- Remember that a requested fan percentage does not guarantee a particular temperature.
- Use elevated privileges only when required by the operation.
NeoSense delegates hardware-level control to NBFC; it cannot guarantee compatibility with every laptop.
⛭ Project structure
NeoSense/
├── README.md
├── LICENSE
├── install.sh
├── uninstall.sh
├── neosense
└── src/
├── commands.sh
├── system.sh
├── config.sh
├── status.sh
└── utils.sh
| File | Responsibility |
|---|---|
neosense |
Main CLI entry point |
src/commands.sh |
Fan control commands and presets |
src/system.sh |
Temperatures and systemd service operations |
src/config.sh |
NBFC configuration profiles |
src/status.sh |
Status parsing and dashboard output |
src/utils.sh |
Colors, logging, and validation |
install.sh |
Installation |
uninstall.sh |
Uninstallation |
The modular structure keeps command handling separate from system operations and configuration management.
❓ Troubleshooting
“This command requires root privileges”
Some operations require elevated permissions to communicate with the underlying hardware or manage the system service. Run the relevant command with the required privileges and ensure that NBFC is configured correctly.
GPU temperature appears as N/A
Check whether your GPU driver exposes temperature information. On NVIDIA systems,...
NeoSense v1.0
❄️ NeoSense
NeoSense est un wrapper CLI (Command Line Interface) moderne, propre et élégant autour de NBFC (Notebook FanControl) sous Linux. Inspiré de l'interface de contrôle NitroSense d'Acer, NeoSense est conçu pour fonctionner sur n'importe quel ordinateur portable compatible avec NBFC.
Grâce à NeoSense, vous n'avez plus à mémoriser des commandes NBFC complexes. Contrôlez vos ventilateurs, changez de profil de performance en un clin d'œil, et surveillez l'état de votre matériel grâce à une interface colorée, lisible et hautement extensible.
🖥️ CAPTURE D'ÉCRAN (ASCII ART)
Voici à quoi ressemble la commande neosense status dans votre terminal :
+-------------------------------------------------------------+
| _ _ ____ |
| | \ | | ___ ___ / ___| ___ _ __ ___ ___ |
| | \| |/ _ \/ _ \ \___ \ / _ \ '_ \/ __|/ _ \ |
| | |\ | __/ (_) | ___) | __/ | | \__ \ __/ |
| |_| \_|\___|\___/ |____/ \___|_| |_|___/\___| v1.0 |
| |
+-------------------------------------------------------------+
Configuration :
Acer Nitro AN515-57 Custom
Service :
Running
Autostart :
Enabled
Mode :
Manual
CPU
Temp 58°C
Current 72%
Target 70%
GPU
Temp 53°C
Current 64%
Target 65%
🛠️ ARCHITECTURE DU PROJET
NeoSense a été pensé dès le premier jour pour être modulaire, propre et facilement extensible :
NeoSense/
├── README.md # Documentation complète
├── LICENSE # Licence MIT
├── install.sh # Script d'installation automatique
├── uninstall.sh # Script de désinstallation automatique
├── neosense # Script d'entrée CLI principal
└── src/ # Modules sources
├── commands.sh # Commandes de contrôle des ventilateurs
├── system.sh # Gestion des températures et du démon systemd
├── config.sh # Gestion des profils de configuration de NBFC
├── status.sh # Analyse de nbfc status et affichage du dashboard
└── utils.sh # Couleurs, journalisation et validations de base