Metadata-Version: 2.4
Name: rockchip-stats
Version: 0.1.9
Summary: Interactive system-monitor and process viewer for Rockchip SoC devices [RK3588, RK3588S, RK3568, RK3566, RK3399]
Home-page: https://github.com/batuhanberkayaydin/rockchip_stats
Author: Batuhan Berkay Aydın
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: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<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 (AGPL-3.0).
See the [LICENSE](LICENSE) file for the full license text.

---

## Acknowledgements

This project is based on and inspired by **jetson_stats** by rbonghi:
https://github.com/rbonghi/jetson_stats

The original project provides monitoring and control utilities for NVIDIA Jetson devices.
This repository extends similar concepts and functionality to support Rockchip SoCs.

Significant modifications, refactoring, and new features have been implemented to adapt the design for Rockchip platforms.
