NeoSense

Thermal monitoring and safe fan management for Linux laptops.

NeoSense is a modern interface around NBFC (Notebook FanControl). It is written in Rust and keeps fan writes behind a single safety supervisor.

NeoSense is not a replacement for NBFC. NBFC remains responsible for the embedded controller (EC), hardware configurations and vendor critical-temperature handling.

Project status

• Version: 2.4.0 development (Rust).
• Release status: 2.3.0 remains an unpublished frozen artifact; 2.4.0 is in development for the profile simulation engine. Neither is publicly released.
• Fan backend: NBFC.
• Platform: Linux.
• TUI: Ratatui/Crossterm, read-only by default; safe-auto can be applied through the supervisor with confirmation.
• Thermal profiles: deterministic preview/simulation engine; real closed-loop fan application remains disabled by hardware-safety policy.
• Manual fan control: implemented but blocked by policy on NBFC < 0.5.4, missing/stale sensors, ambiguous fan mapping and unreliable readback.

Commands

Command	Purpose
neosense status	Concise CPU/GPU, backend, fan and safety summary
neosense status --json	Versioned JSON summary
neosense sensors list	Typed sensor inventory with provenance and trust
neosense sensors show <id>	Raw and normalized details for one sensor
neosense sensors watch	Read-only periodic refresh
neosense fan status	Fan mode, requested/target/EC values and source
neosense fan auto	Return to NBFC automatic mode via the supervisor
neosense fan set	Manual speed request, subject to safety policy
neosense fan hold	Hold current target, subject to safety policy
neosense fan release	Explicit firmware/EC release (not implemented without validation)
neosense profile list/show/apply	Profile catalogue and compatibility; only safe-auto is applicable
neosense profile preview <name>	Calculate reference fan targets locally with no write
neosense profile select/clear	Select/clear a 2.4.0 supervisor simulation profile; no fan write
neosense hardware list/current/validate	NBFC model configurations and rate-config analysis
neosense service status	NBFC and NeoSense supervisor status
neosense diagnose	Read-only compatibility and safety diagnostics
neosense config show/path	Effective settings and supervisor socket
neosense tui	Interactive terminal UI
neosense completions <shell>	Generate bash/zsh/fish/elvish/powershell completions
neosense version	Version

Read commands work without the supervisor. All state-changing operations go through neosensed.

Installation

Platform support

NeoSense targets Linux laptops with NBFC, systemd and readable hwmon/thermal sensors. The current release is built and tested for x86_64-unknown-linux-gnu; no broad distribution or laptop compatibility claim is made from the single development machine. The tested environment is Nobara 44 with kernel 7.3 and NBFC 0.5.3. Other distributions may work, but should be validated read-only first with neosense diagnose --json.

Requirements

• Linux with systemd and NBFC installed and configured.
• NBFC 0.5.4 or newer recommended for protected manual control (status --json, reset-ec, systemd ExecStopPost).
• NBFC 0.5.3 remains usable read-only and for fan auto/diagnose.
• Rust/Cargo only for a source install.
• sudo for installing binaries and the systemd unit.
• No Python or other runtime dependency from NeoSense itself.

From a release archive (recommended)

Download neosense-<version>-<target>.tar.gz and SHA256SUMS, verify the checksum, then install:

sha256sum -c SHA256SUMS
tar -xzf neosense-2.4.0-x86_64-unknown-linux-gnu.tar.gz
cd neosense-2.4.0-x86_64-unknown-linux-gnu
sudo ./install.sh

The archive contains prebuilt binaries, so Rust is not required. The installer uses bin/neosense and bin/neosensed when present.

From source

git clone git@github.com:NeonMC23/NeoSense.git
cd NeoSense
sudo ./install.sh

A source checkout has no bin/ directory, so the installer builds release binaries with Cargo. Both paths create the neosense system group if needed and install:

• /usr/local/bin/neosense
• /usr/local/bin/neosensed
• /etc/systemd/system/neosensed.service
• /run/neosense/ (root:neosense, mode 0750)

It does not start an inactive supervisor. If the supervisor was already running, the installer restarts and verifies it after a successful upgrade; --no-restart keeps the old process running and prints the explicit restart step. A running supervisor's designed shutdown fail-safe may return NBFC to automatic mode, so this is not described as a zero-write upgrade.

Before replacing files, the installer stages and verifies the built binary, creates a timestamped backup under ${NEOSENSE_STATE_DIR:-/var/lib/neosense}/backups/, and restores the previous binary/unit if installation verification fails. It supports an in-place upgrade and verifies the restarted supervisor's IPC state. If restart verification fails, it restores the previous binaries/unit and attempts to restart the previous supervisor.

Supervisor access

Add an authorized user to the neosense group:

sudo usermod -aG neosense "$USER"
# Log out and back in, or run: newgrp neosense

The IPC socket is created as root:neosense, mode 0660; the runtime directory is root:neosense, mode 0750. A user outside the group receives a clear permission error (exit code 4).

Real-host checklist

See docs/HOST_INSTALL.md for the root installation, group-session, service, rollback and uninstall checklist.

Enable the supervisor

sudo systemctl enable --now neosensed

The supervisor is the sole fan-write authority. It sends READY=1 only after the socket is bound, permissioned, and an initial state snapshot is available. It sends WATCHDOG=1 only while its health checks pass, and STOPPING=1 during orderly shutdown.

The service uses Type=notify and WatchdogSec=10s. See docs/SYSTEMD.md.

Release archive

./packaging/build-release.sh

This produces dist/neosense-<version>-<target>.tar.gz containing the binaries, installer, uninstaller, systemd unit, docs, completions, BUILD-INFO and checksums. The archive is generated locally and is not committed. Validate it before publishing:

./packaging/test-release-archive.sh dist/neosense-*.tar.gz

The test checks archive contents and, when user namespaces are available, installs and uninstalls the extracted prebuilt archive in a temporary root.

Uninstall

sudo ./uninstall.sh

The script stops the supervisor (triggering automatic recovery), removes NeoSense-owned binaries, unit, runtime/state directories and backups, and removes the neosense group only when it is empty and has no primary users. NBFC configuration is untouched.

Usage

neosense status
neosense sensors list
neosense sensors show hwmon:coretemp:...:temp1
neosense fan status
neosense diagnose
neosense hardware list
neosense hardware current
sudo neosense hardware validate "Acer Nitro AN515-57 Custom"

hardware validate calls nbfc rate-config, which needs root to read ACPI tables.

Control through the supervisor:

sudo systemctl start neosensed
neosense fan auto
neosense fan set cpu 50 --yes

After group membership and a new login session, control commands no longer need sudo. fan set exits 8 if the safety policy cannot establish a safe operation. On NBFC 0.5.3 manual control is deliberately refused.

TUI

neosense tui

The header shows the application/version, hardware model, NBFC version and a compact supervisor state. Full IPC failures live in System/Diagnostics. Six views: Dashboard, Sensors, Fans, Profiles, System and Diagnostics.

• Tab/arrows: change view; 1–6: direct access.
• r: refresh; ?: help; q/Esc: quit.
• Profiles: Up/Down select; Enter previews/simulates the selected curve; y confirms, n cancels. Closed-loop profiles are simulation-only and never write fan state.
• a: return to NBFC automatic mode, with confirmation.
• Without a supervisor the TUI stays read-only and says so.
• No direct manual-speed path exists in the TUI. See docs/TUI.md for the real-terminal rendering evidence.

Diagnostics

neosense diagnose is grouped for scanning:

1. overall summary (operational, supervisor, fan control, thermal reliability, critical/warning counts);
2. critical blockers;
3. backend;
4. hardware;
5. thermal monitoring;
6. fan telemetry;
7. control capabilities;
8. security and permissions.

neosense diagnose --json exposes the same information with stable groups and a machine-readable summary. See docs/IMPLEMENTATION.md.

Safety

1. Single writer. Only neosensed writes fan state.
2. No invented values. Missing, invalid, stale or unreadable sensors are null/unavailable, never 0 °C.
3. Evidence before control. Manual control needs valid, fresh and trusted CPU/GPU data, a known fan mapping, a floor, a ceiling and explicit confirmation.
4. No generic GPU sensor. Wi-Fi/NVMe/ACPI channels are never promoted to GPU by keyword.
5. No false success. nbfc set acceptance is not proof of physical fan speed. EC readback is not RPM.
6. Fail safe. Lease expiry, lost sensors, NBFC critical mode or failed verification trigger automatic recovery or a fail-safe state.
7. Profiles are validated. safe-auto is compatible only when NBFC, service and CPU evidence are available. Closed-loop Quiet/Balanced/Performance profiles use deterministic reference curves for preview/simulation; they are not applied to hardware until mapping, feedback, recovery and authorization are validated.
8. Warnings are explicit. Every warning carries a severity label, cause and next safe action; colour is never the only signal.

Known limitations

• NBFC 0.5.3 lacks status --json and reset-ec: protected manual control is refused.
• NBFC's own socket remains 0666. NBFC 0.5.3 and 0.5.4 hardcode chmod 0666 in server.c and offer no supported socket-permission option. The neosense group protects NeoSense only; any local user can call NBFC directly. No unsafe permission override was applied.
• Many laptops expose no RPM through hwmon; physical verification is then limited.
• Some NBFC configurations drive the GPU fan from @CPU; diagnose reports this and GPU manual control is blocked.
• Closed-loop Quiet/Balanced/Performance profiles now have deterministic simulation curves but are not applied to hardware. See docs/PROFILES.md.
• fan release is intentionally unavailable until reset-ec/firmware return is validated.
• No broad laptop compatibility claim is made from a single machine.

Architecture

neosense (Rust CLI) ── IPC ──┐
neosense tui (Ratatui) ─────┴── Unix JSON ──► neosensed
                                             ├── sensor registry / hwmon / thermal / NVIDIA
                                             ├── NBFC backend
                                             ├── safety policy + verification
                                             └── systemd READY / WATCHDOG / STOPPING

• neosense status/sensors/diagnose read directly and never write.
• fan/profile writes and TUI controls use the single supervisor IPC protocol.
• neosensed owns fan writes and recovery.
• Shell is limited to installation, removal and systemd integration.

Project tracking and release

• docs/CLI.md is the complete CLI reference.
• docs/CLI_AUDIT.md records the command inventory and validation matrix.
• docs/HARDWARE.md records current hardware evidence and backend acceptance criteria.
• docs/PROFILES.md documents curves, simulation boundaries and hardware-control prerequisites.
• docs/ROADMAP.md tracks feature status, evidence and blockers.
• docs/RELEASE.md describes the release checklist and artifacts.
• docs/RELEASE_NOTES.md contains the frozen 2.3.0 notes.
• docs/RELEASE_NOTES_2.4.0.md contains the 2.4.0 development notes.
• CHANGELOG.md records user-visible changes.
• CONTRIBUTING.md and SECURITY.md cover contribution and disclosure.

Development

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
cargo build --release --locked
shellcheck install.sh uninstall.sh

Tests never write fan state. Unit tests cover NBFC parsing, sensor fixtures, NVIDIA parsing, policy, profiles, IPC, daemon lifecycle and TUI rendering. See docs/IMPLEMENTATION.md.

Hardware testing

Hardware-dependent tests are separate. neosense diagnose --json is the read-only entry point. No fan speed, EC reset, firmware or NBFC configuration change should be performed without explicit authorization and a validated recovery plan.

Compatibility

Item	Status
Acer Nitro AN515-57, i5-11400H, RTX 3050, NBFC 0.5.3	Read-only verified; manual control refused
Other laptops	Must be validated individually; no broad claim
NBFC 0.5.4+	Recommended for protected manual control; test on target hardware
iGPU / no GPU	No invented GPU temperature; GPU control unavailable
No RPM	Verification limited; reported by diagnose

Roadmap

• Sensor and CLI correctness (done).
• Typed sensor model and read-only diagnostics (done).
• Supervisor, IPC and systemd recovery foundations (done).
• TUI, profile catalogue, deterministic simulation engine and compatibility checks (done).
• Real closed-loop hardware application, full hardware matrix and root-level systemd validation (next).

License

MIT. See LICENSE.