raspberry-stats
Advanced tools
A lightweight Node.js utility for gathering essential performance metrics from your Raspberry Pi—such as CPU temperature, memory usage, and more.
A Node.js module for retrieving system information from a Raspberry Pi.
It uses the child_process.spawn command to read various parameters, including CPU temperature, memory usage, disk usage, voltage, and clock frequencies.
Synchronous (callback-based) and asynchronous (promise-based) APIs are provided for each method.
Note: This module relies on
vcgencmdand other system commands that are typically available on Raspberry Pi OS. It may not work on other platforms or distributions where these commands are unavailable.
With npm:
npm install raspberry-stats
With yarn:
yarn add raspberry-stats
With pnpm:
pnpm add raspberry-stats
With bun:
bun add raspberry-stats
Example using both callback-based and async/await methods:
import {
getCPUTemperature,
getCPUTemperatureAsync,
getMemoryUsage,
getMemoryUsageAsync,
// ... other imports
} from "raspberry-stats";
// --- Using callback-based methods ---
// Each callback receives a SystemInfo<T> object containing { data, error }
// Example 1: CPU Temperature
getCPUTemperature((info) => {
if (info.error) {
console.error("Failed to retrieve CPU temperature:", info.error);
} else {
console.log(`CPU Temperature: ${info.data}°C`);
}
});
// Example 2: Memory Usage
getMemoryUsage((info) => {
if (info.error) {
console.error("Failed to retrieve memory usage:", info.error);
} else {
console.log("Memory usage:", info.data);
}
});
// --- Using promise-based methods (Async/Await) ---
// Each async function returns a Promise<SystemInfo<T>>
(async () => {
try {
// Example 1: CPU Temperature
const tempInfo = await getCPUTemperatureAsync();
if (tempInfo.error) {
console.error("Failed to retrieve CPU temperature:", tempInfo.error);
} else {
console.log(`CPU Temperature: ${tempInfo.data}°C`);
}
// Example 2: Memory Usage
const memInfo = await getMemoryUsageAsync();
if (memInfo.error) {
console.error("Failed to retrieve memory usage:", memInfo.error);
} else {
console.log("Memory usage:", memInfo.data);
}
} catch (error) {
console.error(error);
}
})();
All callback-based functions receive a single parameter of type SystemInfo<T>:
interface SystemInfo<T> {
data: T | null;
error: string | null;
}
data contains the successfully retrieved value (e.g. number, object, or array) if everything went well, otherwise null.error is a string describing the problem if something failed, otherwise null.Similarly, all promise-based functions resolve with SystemInfo<T> instead of just the raw data or throwing an error.
Hence, if error is non-null, you can handle it accordingly in your async flow.
Signature (Callback):
getCPUTemperature(callback: (info: SystemInfo<number>) => void): void;
vcgencmd measure_temp.SystemInfo<number>.
info.data is the temperature (in °C) if successful, otherwise null.info.error contains an error message if something went wrong, otherwise null.Signature (Async):
getCPUTemperatureAsync(): Promise<SystemInfo<number>>;
SystemInfo<number>—check info.error to see if it succeeded.Signature (Callback):
getCPUUsage(callback: (info: SystemInfo<number>) => void): void;
top repeatedly (e.g., 10 iterations at 0.1-second intervals) and gathers the CPU usage values.SystemInfo<number>.
info.data is the CPU usage or null if it fails.info.error is an error message if it fails.Signature (Async):
getCPUUsageAsync(): Promise<SystemInfo<number>>;
SystemInfo<number>—check info.error to see if it succeeded.Signature (Callback):
getMemoryUsage(callback: (info: SystemInfo<MemoryUsageResult>) => void): void;
Where MemoryUsageResult is:
interface MemoryUsageResult {
total: number;
used: number;
free: number;
shared: number;
buffCache: number;
available: number;
}
free command.SystemInfo<MemoryUsageResult>.
info.data is a MemoryUsageResult object if successful, otherwise null.info.error is an error message if something went wrong, otherwise null.Signature (Async):
getMemoryUsageAsync(): Promise<SystemInfo<MemoryUsageResult>>;
SystemInfo<MemoryUsageResult>—check info.error to see if it succeeded.Signature (Callback):
getDiskUsage(callback: (info: SystemInfo<DiskUsageResult[]>) => void): void;
Where DiskUsageResult is:
interface DiskUsageResult {
filesystem: string;
oneKBlocks: number;
used: number;
available: number;
usePercentage: number;
mountedOn: string;
}
df command.SystemInfo<DiskUsageResult[]>.
info.data is an array of disk usage objects if successful, otherwise null.info.error is an error message if it fails.Signature (Async):
getDiskUsageAsync(): Promise<SystemInfo<DiskUsageResult[]>>;
SystemInfo<DiskUsageResult[]>—check info.error on result.Signature (Callback):
getVoltage(callback: (info: SystemInfo<number>) => void): void;
vcgencmd measure_volts.SystemInfo<number>.
info.data is the voltage (in Volts) if successful, otherwise null.info.error is an error message if it fails.Signature (Async):
getVoltageAsync(): Promise<SystemInfo<number>>;
SystemInfo<number>—check info.error to see if it succeeded.Signature (Callback):
getClockFrequencies(
callback: (info: SystemInfo<ClockFrequencyResult[]>) => void
): void;
Where ClockFrequencyResult is:
interface ClockFrequencyResult {
clock: string;
frequency: number | null; // in Hz
}
vcgencmd measure_clock.SystemInfo<ClockFrequencyResult[]>.
info.data is an array of clock/frequency objects if successful, otherwise null.info.error is an error message if it fails.Signature (Async):
getClockFrequenciesAsync(): Promise<SystemInfo<ClockFrequencyResult[]>>;
SystemInfo<ClockFrequencyResult[]>—check info.error on result.Signature (Callback):
getClockFrequency(
clock: Clock,
callback: (info: SystemInfo<number>) => void
): void;
Where Clock is an enum:
enum Clock {
ARM = "arm",
CORE = "core",
H264 = "h264",
ISP = "isp",
V3D = "v3d",
UART = "uart",
PWM = "pwm",
EMMC = "emmc",
PIXEL = "pixel",
VEC = "vec",
HDMI = "hdmi",
DPI = "dpi",
}
vcgencmd measure_clock.SystemInfo<number>.
info.data is the frequency (in Hz) if successful, otherwise null.info.error is an error message if it fails.Signature (Async):
getClockFrequencyAsync(clock: Clock): Promise<SystemInfo<number>>;
SystemInfo<number>—check info.error on result.Signature (Callback):
getUptime(callback: (info: SystemInfo<number>) => void): void;
awk '{print $1 * 1000}' /proc/uptime.SystemInfo<number>.
info.data is the uptime in milliseconds if successful, otherwise null.info.error is an error message if something went wrong.Signature (Async):
getUptimeAsync(): Promise<SystemInfo<number>>;
SystemInfo<number>—check info.error on result.Note: The uptime is returned in milliseconds but is based on the system’s uptime in seconds.
Because all the functions return a SystemInfo<T> object, there is no more "rejecting" or passing null—the callback or promise resolves with an object which may contain an error message:
info.error.info.error is not null, an error occurred; otherwise info.data contains the good value..error property.error is non-empty, handle it accordingly; if not, .data contains the requested information.Example:
// Async example: getCPUTemperatureAsync
(async () => {
const info = await getCPUTemperatureAsync();
if (info.error) {
// something went wrong
console.error("Failed to read CPU temperature:", info.error);
} else {
// success
console.log(`CPU Temperature: ${info.data}°C`);
}
})();
Feel free to open issues, PRs, or contribute in any way you see fit!
FAQs
A lightweight Node.js utility for gathering essential performance metrics from your Raspberry Pi—such as CPU temperature, memory usage, and more.
We found that raspberry-stats demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.
Security News
The Axios compromise shows how time-dependent dependency resolution makes exposure harder to detect and contain.