Metadata-Version: 2.4
Name: rockchip-stats
Version: 0.1.3
Summary: Interactive system-monitor and process viewer for Rockchip SoC devices [RK3588, RK3588S, RK3568, RK3566, RK3399]
Author-email: Batuhan Berkay Aydın <batuhanberkayaydin@gmail.com>
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/batuhanberkayaydin/rockchip_stats
Project-URL: Repository, https://github.com/batuhanberkayaydin/rockchip_stats
Project-URL: Bug Tracker, https://github.com/batuhanberkayaydin/rockchip_stats/issues
Project-URL: Examples, https://github.com/batuhanberkayaydin/rockchip_stats/tree/master/examples
Keywords: rockchip_stats,rtop,python,system-monitor,docker,rockchip,RK3588,RK3588S,RK3568,RK3566,RK3399,Mali,NPU,RGA,MPP,process,viewer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: User Interfaces
Classifier: Topic :: System :: Hardware
Classifier: Topic :: System :: Logging
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Operating System
Classifier: Topic :: System :: Operating System Kernels
Classifier: Topic :: System :: Shells
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Classifier: Programming Language :: Unix Shell
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: distro
Dynamic: license-file

<h1 align="center">

<b>rockchip-stats</b>

</h1>

**rockchip-stats** is a package for **monitoring** and **control** of Rockchip SoC devices [RK3588, RK3588S, RK3576, RK3568, RK3566, RK3399] series.

rockchip-stats is a powerful tool to analyze your board, you can use it as a stand alone application with `rtop` or import it in your python script. The main features are:

- Decode hardware, SoC model, board identification
- Monitor CPU, GPU (Mali), NPU, RGA, MPP, Memory, Temperature, Fan
- Control fan speed, CPU governor
- Importable in a python script
- Dockerizable in a container
- Auto-detects available hardware (graceful degradation)
- Works with multiple Rockchip SoC variants

## Supported Hardware

| SoC | CPU | GPU | NPU | Status |
|-----|-----|-----|-----|--------|
| RK3588 / RK3588S | 4x A76 + 4x A55 | Mali-G610 | 6 TOPS (3 cores) | ✅ Primary |
| RK3576 | 4x A72 + 4x A53 | Mali-G52 | 6 TOPS | ✅ Supported |
| RK3588M | 4x A76 + 4x A55 | Mali-G610 | 6 TOPS (3 cores) | ✅ Supported |
| RK3582 | 2x A76 + 4x A55 | Mali-G610 | - | ✅ Supported |
| RK3568 / RK3568J | 4x A55 | Mali-G52 | - | ✅ Supported |
| RK3566 | 4x A55 | Mali-G52 | - | ✅ Supported |
| RK3399 / RK3399Pro | 2x A72 + 4x A53 | Mali-T860 | 3 TOPS (Pro only) | ✅ Supported |

## Monitoring Sources

| Component | Source Path | Notes |
|-----------|-------------|-------|
| CPU Load | `/proc/stat` | Per-core and total |
| CPU Freq | `/sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq` | Per-core |
| GPU Load | `/sys/class/devfreq/fb000000.gpu/load` | Format: `load@freq` |
| GPU Freq | `/sys/class/devfreq/fb000000.gpu/cur_freq` | |
| NPU Load | `/sys/kernel/debug/rknpu/load` | Per-core, requires root |
| NPU Freq | `/sys/class/devfreq/fdab0000.npu/cur_freq` | |
| RGA Load | `/sys/kernel/debug/rkrga/load` | Requires root |
| RGA Freq | `/sys/kernel/debug/clk/clk_summary` | Requires root |
| MPP Sessions | `/proc/mpp_service/sessions-summary` | Video enc/dec cores |
| Temperature | `/sys/class/thermal/thermal_zone*/temp` | Multiple zones |
| Fan | `/sys/class/thermal/cooling_device*/cur_state` | + PWM hwmon |
| Device ID | `/sys/firmware/devicetree/base/compatible` | SoC identification |

## Install

```console
sudo apt update
sudo apt install python3-pip python3-setuptools -y
```

### Option 1: Install with pip (requires superuser)
```console
sudo pip3 install -U rockchip-stats
```

### Option 2: Install from source
```console
git clone https://github.com/batuhanberkayaydin/rockchip_stats.git
cd rockchip_stats
sudo pip3 install .
```

### Option 3: Ubuntu 24.04+
```console
sudo pip3 install --break-system-packages -U rockchip-stats
```

---

## Development / Debug

Run directly from source without installing:

```console
cd rockchip_stats
python3 -m rtop
```

Run with debug log output:

```console
python3 -m rtop --debug
```

Run without service (no socket connection):

```console
python3 -m rtop --no-service --debug
```

Start the service manually:

```console
sudo python3 -m rtop --force
```

---

## Run

Start rtop by simply typing `rtop`:

```console
rtop
```

An interactive curses-based interface will appear with 8 pages:

| Key | Page | Description |
|-----|------|-------------|
| `1` | ALL | Overview dashboard |
| `2` | CPU | Per-core CPU details |
| `3` | GPU | Mali GPU details |
| `4` | NPU | NPU per-core details |
| `5` | ENG | RGA, MPP engines |
| `6` | MEM | RAM, Swap, CMA |
| `7` | CTRL | Fan & governor control |
| `8` | INFO | Board & system info |

## Library

You can use rtop as a Python library to integrate into your software:

```python
from rtop import rtop

with rtop() as rockchip:
    while rockchip.ok():
        # Read stats
        print(rockchip.stats)
```

### Quick Read Example

```python
from rtop import rtop

with rtop() as rockchip:
    if rockchip.ok():
        # CPU
        cpu = rockchip.cpu
        print(f"CPU: {cpu.get('total', 0):.1f}%")

        # GPU
        gpu = rockchip.gpu
        if gpu:
            print(f"GPU: {gpu.get('load', 0)}%")

        # NPU
        npu = rockchip.npu
        if npu:
            for i, core in enumerate(npu.get('cores', [])):
                print(f"NPU Core{i}: {core.get('load', 0)}%")

        # Temperature
        for name, val in rockchip.temperature.items():
            if isinstance(val, (int, float)):
                print(f"{name}: {val / 1000:.1f}°C")
```

## Docker

You can run rtop directly in Docker:

1. Install rockchip-stats on your **host**
2. Install rockchip-stats in your container
3. Pass `/run/rtop.sock:/run/rtop.sock` to your container

You can pull the pre-built image from GitHub Container Registry (GHCR):

```console
docker run --rm -it -v /run/rtop.sock:/run/rtop.sock ghcr.io/batuhanberkayaydin/rockchip_stats:latest
```
## Architecture

rockchip-stats uses a client-server model:

```
┌─────────────────┐     Unix Socket      ┌─────────────────┐
│   rtop (client)  │◄──────────────────►│  rtop (service)  │
│   curses GUI     │    /run/rtop.sock   │  data collector  │
└─────────────────┘                      └─────────────────┘
                                                  │
                                          ┌───────┴───────┐
                                          │  sysfs/procfs  │
                                          │  debugfs       │
                                          └───────────────┘
```

The background service (`rtop.service`) runs as root to access debugfs paths (NPU load, RGA load) and serves data via a Unix domain socket. The client connects and displays the data.

## Examples

The [`examples/`](https://github.com/batuhanberkayaydin/rockchip_stats/tree/master/examples) directory contains ready-to-run scripts:

| File | Description |
|------|-------------|
| `quick_read.py` | Read all stats in a single snapshot |
| `rtop_cpu.py` | Monitor CPU load and frequency per core |
| `rtop_npu.py` | Monitor NPU core utilization |
| `rtop_server.py` | Run rtop as a background data server |

## License

This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE) file for details.

Inspired by jetson_stats by rbonghi
https://github.com/rbonghi/jetson_stats
