jtop

class jtop.jtop(interval=1.0)

Bases: Thread

This class control the access to your board, from here you can control your NVIDIA Jetson board or read the jetson_clocks status or change the nvp model.

__init__(interval=1.0)

When you initialize your jtop you can setup a communication speed interval, if there is another jtop running this speed will be not used.

When jtop is started you can read the server speed in interval property.

Parameters:

interval (float, optional) – Interval to setup the jtop speed (in seconds), defaults to 1.0

attach(observer)

Attach an observer to read the status of jtop. You can add more observer that you want.

The function must be with this format:

def observer(jetson):
    pass

The input of your callback will be the jetson object.

To detach a function, please look detach()

Parameters:

observer (function) – The function to call

property board

Board status, in this property where are available all information about your device.

The output is a dictionary with 3 keys:

  • platform

  • hardware

  • libraries

platform (If you are running in docker this output is extracted from your container)

Name

Type

Description

Machine

platform.machine()

Mapped output: machine type

System

platform.system()

Mapped output: Type system

Distribution

platform.linux_distribution()

Mapped output: Linux distribution

Release

platform.release()

Mapped output: Release kernel

Python

platform.python_version()

Mapped output: Python version is running jtop

hardware (If you are running in docker this output is extracted from your host)

Name

Type

Description

Model

str

Model name from /sys/firmware/devicetree/base/model

699-level Part Number

str

699 part number (read reference)

P-Number

str

Part number (read reference)

BoardIDs

str

(Optional) Board ID in /proc/device-tree/nvidia,boardids

Module

str

Conversion from P-Number to Module name

SoC

str

System on Chip /proc/device-tree/compatible

CUDA Arch BIN

str

Cuda Architecture

Codename

str

(Optional) Codename architecture

Serial Number

str

Serial Number board /sys/firmware/devicetree/base/serial-number

L4T

str

Linux 4 Tegra A

Jetpack

str

From L4T is evaluated the Jetpack running on your NVIDIA Jetson

libraries (If you are running in docker this output is extracted from your container)

Name

Type

Description

CUDA

str

CUDA version B

OpenCV

str

OpenCV version use opencv_version

OpenCV-Cuda

bool

Check running opencv_version --verbose

cuDNN

str

Check and read the version with dpkg -l

TensorRT

str

Check and read the version with dpkg -l

VPI

str

Check and read the version with dpkg -l

Vulkan

str

Run and read which vulkaninfo

Note

Note A
The Linux For Tegra (L4T) is extracted in two ways:
  1. Reading /etc/nv_tegra_release

  2. Reading version in nvidia-l4t-core package

Note B
The CUDA version is read depend of the version in:
  1. On /usr/local/cuda/version.txt

  2. Running nvcc --version

Returns:

Status board, hardware and libraries

Return type:

dict

close()

This method close the jtop server.

This method is not needed to close jtop if you have open jtop using with like:

with jtop() as jetson:
    pass
property cpu

this property return a dictionary with all information for each core about frequency, idle, and other.

This dictionary is made:

  • total - The aggregate values for all cores of (user, nice, system, idle)

  • cpu - a list with a dictionary for each core

For each core the dictionary is defined:

Name

Type

Description

online

bool

Status core

governor

str

Type of governor running on the core

freq

dict

Frequency of the core A

info_freq

dict

Frequency of the core A

idle_state

dict

All Idle state running

user

float

User percentage utilization B

nice

float

Nice percentage utilization B

system

float

System percentage utilization B

idle

float

Idle percentage B

model

str

Model core running

Note

Note A

The frequency dictionary is defined like below:

Name

Type

Description

min

int

Minimum frequency of the core in kHz

max

int

Maximum frequency of the core in kHz

cur

int

Current frequency of the core in kHz

Note B

If a core is offline, this data is not key is not available

Returns:

A dictionary with the aggregate status and a list of all CPUs, described above.

Return type:

dict

detach(observer)

Detach an observer from jtop

To attach a function, please look attach()

Parameters:

observer (function) – The function to detach

property disk

Disk status properties, in dictionary are included

  • total - Total disk space in GB

  • available - Space available in GB

  • used - Disk space used in GB

  • available_no_root

Returns:

Disk information

Return type:

dict

property engine

Engine status, in this property you can find like: APE, DLA, NVDEC, NVENC, and other

The output of this property is a dictionary:

  • name group X - In this group are collected all engines similar
    • name engine a - In this key there is a dictionary with engine status

    • name engine b - Same like above, there is the dictionary status engine

For each engine the dictionary is defined like the table below:

Name

Type

Description

online

bool

Status of the engine

min

int

Minimum frequency of the core in kHz A

max

int

Maximum frequency of the core in kHz A

cur

int

Current frequency of the core in kHz

Note

Note A

Some engines doesn’t have a min and max frequency

Returns:

Dictionary of all active engines

Return type:

dict

property fan

Fan status and control. This property show speed, rpm and control every fan on your board

The Fan class is readable such a dict where for each key are colleted all metrics for each Fan.

Name

Type

Description

speed

list

List of speed between [0, 100]

rpm

list

(Optional) List of RPM for each fan

profile

str

Fan Profile, read all_profiles()

governor

str

(Jetson with JP5+) Governor fan

control

str

(Jetson with JP5+) Type of controller

If you are working with Jetpack 5 or higher, the fan profile map nvfancontrol nvfancontrol

you can also control your fan with:

with jtop() as jetson:
    if jetson.ok():
        # Print profile
        print(jetson.fan.profile)
        # Set new profile
        jetson.fan.profile = 'quiet'
        # Read speed
        print(jetson.fan.speed)
        # Set new speed
        jetson.fan.speed = 90

Full documentation on Fan

Returns:

Status Fan

Return type:

Fan

Raises:

JtopException – Wrong speed fan name, profile or speed

property gpu

This property show in a simple way all GPU available on your board.

You can also use this attribute to enable/disable 3D scaling:

with jtop() as jetson:
    if jetson.ok():
        # change 3D scaling status
        jetson.gpu.set_scaling_3D = not jetson.gpu.set_scaling_3D

The GPU class is readable such a dict where for each key are colleted all metrics for each GPU.

Name

Type

Description

type

str

Type of GPU (integrated, discrete)

status

dict

Status of GPU A

freq

dict

Frequency GPU B

power_control

dict

(Optional) Type of power control

Note

Note A

Status GPU, from current load to features

Name

Type

Description

railgate

bool

Status Railgate

tpc_pg_mask

bool

Status TPC PG Mask (for NVP model)

3d_scaling

bool

Status 3D scaling

load

float

Current GPU load

Note B

The frequency dictionary is defined like below:

Name

Type

Description

governor

str

Name GPU governor

min

int

Minimum GPU frequency in kHz

max

int

Maximum GPU frequency in kHz

cur

int

Current GPU frequency in kHz

GPC

list

List GPC frequency in kHz (Available for Orin series)

Returns:

current status of your GPU.

Return type:

GPU

property interval

Speed jtop service. This speed can be different compare the speed specified in jtop() constructor

Returns:

jtop interval (in seconds)

Return type:

float

property interval_user

This is the same speed specified in jtop() constructor

Returns:

jtop user interval (in seconds)

Return type:

float

property jetson_clocks

jetson_clocks is a tool provided for all NVIDIA Jetson to maximize all performance, read reference for more information.

You can use this attribute like a simple boolean or use the advanced features in JetsonClocks

with jtop() as jetson:
    if jetson.ok():
        # Change status jetson_clocks
        jetson.jetson_clocks = not jetson.jetson_clocks
        # Set on board boot
        jetson.jetson_clocks.boot = True
        # Read status jetson_clocks service
        print(jetson.jetson_clocks.status)
Returns:

status jetson_clocks script

Return type:

JetsonClocks or None

Raises:

ValueError – Wrong jetson_clocks value

json(stats=False, **json_args)

This method export all metrics in a json readable output.

You can export all metrics or the same output in stats depending of the parameter input.

Parameters:
  • stats (bool, optional) – json with same output of stats, defaults to False

  • json_args (Any) – additional keyword arguments passed to json.dumps

Returns:

json output requested

Return type:

str

property local_interfaces

Local interfaces information and hostname

This dictionary the status of your local network

  • hostname - Hostname board

  • interfaces - A dictionary with name and IP address for all interfaces listed

Returns:

Local interfaces and hostname

Return type:

dict

loop_for_ever()

This blocking method is needed when you design your python code to work only by callback.

Before to run this method remember to attach a callback using attach()

A simple example to use this method is below

def read_stats(jetson):
    stats = jetson.stats

jetson = jtop()
jetson.attach(read_stats)
# Blocking method
jetson.loop_for_ever()
property memory

This property show in a simple way all memories available, the main output is available in this way:

  • RAM - It is a dictionary with all information about RAM A

  • SWAP - It is a dictionary with all information about SWAP

  • EMC - It is a dictionary with EMC data, not in all boards this data is available

  • IRAM - It is a dictionary with SWAP data, not in all boards this data is available

You can also use this property to set a new swap, deactivate or clear cache, read all methods available Memory

example:

with jtop() as jetson:
    if jetson.ok():
        # Print memory status
        print(jetson.memory)
        # make a new 10Gb swap
        jetson.memory.swap_set(10, on_boot=False)

For each dictionary there are specific outputs

RAM A

Name

Type

Description

tot

int

Total RAM in KB

used

int

Total used RAM in KB

free

int

Free RAM in KB

buffers

int

Buffered RAM in KB

cached

int

Cached RAM in KB

shared

int

Shared RAM in KB, for NVIDIA Jetson the RAM used from GPU

lfb

int

Large Free Block in 4MB

SWAP

Name

Type

Description

tot

int

Total SWAP in KB

used

int

Total used SWAP in KB

cached

int

Cached RAM in KB

table

dict

Dictionary with all swap available B

EMC (if available on your device)

Name

Type

Description

online

bool

Status EMC

val

int

Percentage of bandwidth used relative to running frequency

cur

int

Current working frequency in kHz

max

int

Max EMC frequency usable in kHz

min

int

Min EMC frequency usable in kHz

IRAM (if available on your device)

Name

Type

Description

tot

int

Total IRAM in KB

used

int

Total used IRAM in KB

lfb

int

Large Free Block in 4MB

Note

Note A

The RAM is measured reading the file /proc/meminfo for each field is read:

Name

Description

tot

MemTotal

used

MemTotal - (Buffers + Cached)

free

MemFree

buffers

Buffers

cached

Cached + SReclaimable

Note B

The swap table is a list of dictionary with this data

Name

Type

Description

type

str

Type of partition

prio

int

Priority partition

size

int

Size partition in KB

used

int

Used part of this partition in KB

boot

bool

Check if this swap start on boot

Returns:

memory status

Return type:

Memory

property nvpmodel

The NVP Model control voltage regulators, and power tree to optimize power efficiency. It supports three optimized power budgets, such as 10 watts, 15 watts, and 30 watts. For each power budget, several configurations are possible with various CPU frequencies and number of cores online.

Capping the memory, CPU, and GPU frequencies, and number of online CPU, GPU TPC, DLA and PVA cores at a prequalified level confines the module to the target mode.

This method simplify in a set of functions and variables this controller.

with jtop() as jetson:
    if jetson.ok():
        # Read current nvpmodel name
        print(jetson.nvpmodel)
        # List of all nvpmodel available
        models = jetson.nvpmodel.models
        print(models)
        # You can write a string for a name
        jetson.nvpmodel = models[0]
        # or an the ID name is also allowed
        jetson.nvpmodel = 0

You can also increase/decrease the ID

with jtop() as jetson:
    if jetson.ok():
        jetson.nvpmodel += 1
        # or
        jetson.nvpmodel = jetson.nvpmodel + 1

Advanced features are available in NVPModel

Returns:

Return the name of NV Power Mode

Return type:

NVPModel or None

Raises:

JtopException – if the nvp model does not exist

ok(spin=False)

This method is needed when you start jtop using with like below

with jtop() as jetson:
    while jetson.ok():
        stats = jetson.stats

This method is usually blocking, and is not needed to add in your script a sleep function, when a new data will be available the function will release and you will read a new fresh data

Parameters:

spin (bool, optional) – If True, this function will be not blocking, defaults to False

Raises:

ex_value – if jtop client fail, will be raise here

Returns:

status jtop client

Return type:

bool

property power

All NVIDIA Jetson have one ore more integrate three-channel INA3221 to measure the power consumption.

This jtop attribute collect and show the output from each rail in a simple view.

Name

Type

Description

rail

dict

A dictionary with all thermal rails

tot

dict

Total estimate board power

The total power is the sum of all rails or

For each rail there are different values available

Name

Type

Description

online

bool

If sensor is online

type

str

Type of sensors (For NVIDIA Jetson is INA3221)

status

str

(if available) Status sensor

volt

int

Gets rail voltage in millivolts

curr

int

Gets rail current in milliamperes

power

int

Gets rail power in milliwatt

avg

int

Gets rail power average in milliwatt

warn

int

(if available) Gets rail average current limit in milliamperes

crit

int

(if available) Gets rail instantaneous current limit in milliamperes

Returns:

A dictionary with a list of power and the total

Return type:

dict

property processes

Return a list with all processing running in GPU.

For each item are collected all information about the process.

Item

Type

Description

0

int

PID process running

1

str

User start the process

2

str

GPU used E

3

str

Type of process F

4

int

Priority

5

str

State process A

6

float

CPU percent utilization B

7

int

Memory occupied C

8

int

GPU Memory occupied D

9

str

Process name

Note

Note A
This field indicating the status process:
  • R Running

  • S Sleeping in an interruptible wait

  • D Waiting in uninterruptible disk sleep

  • Z Zombie

  • T Stopped (on a signal)

  • t Tracing stop

  • X Dead

Note B
Measure the CPU percent utilization are read live the values from /proc/[PID]/stat:
  • #14 utime - CPU time spent in user code, measured in clock ticks

  • #15 stime - CPU time spent in kernel code, measured in clock ticks

  • #22 starttime - Time when the process started, measured in clock ticks

Where clock ticks is SC_CLK_TCK

It is also used /proc/uptime to know the system up time.

The CPU percent is:

    total_time = utime + stime
    total_time = uptime - (starttime / clock_ticks)
    cpu_usage = 100 * (total_time / clock_ticks)
Note C
Extract resident set size (VmRSS) (Second field) in /proc/[PID]/statm:

VmRSS is the resident set size of the process, which is the portion of the process’s memory that is held in RAM and is not swapped out to disk. This is the amount of memory that the process is currently using.

Note D

This value is the GPU memory occupied from the process.

Note E
GPU used:
  • I: Integrated GPU

  • dX: Discrete GPU with number graphic card (next release)

Note F
Type of process:
  • Graphic: Graphic process

  • System: System process (next release)

Returns:

list of all GPU processes

Return type:

list

restore(max_counter=10)

This block method will restore all jtop configuration, in order:

  1. Switch off, disable on boot jetson_clocks and remove configuration file(reference JetsonClocks)

  2. Set all fan to default profile and all speed to zero (reference Fan)

  3. Set to default nvpmodel (reference NVPModel)

  4. clear the configuration jtop file

with jtop() as jetson:
    if jetson.ok():
        for status, message in jetson.restore():
            if status:
                print(message)
            else:
                print("Fail")
Parameters:

max_counter (int, optional) – Counter time for each test before fail, defaults to 10

Yield:

Generator of all operations to restore your NVIDIA Jetson

Return type:

bool, str

Raises:

JtopException – if the connection with the server is lost, not active or your user does not have the permission to connect to jtop.service

start()

The start() function start your jtop and you can start to read the NVIDIA Jetson status.

This method is not needed to close jtop if you have open jtop using with like:

with jtop() as jetson:
    pass
Raises:

JtopException – if the connection with the server is lost, not active or your user does not have the permission to connect to jtop.service

property stats

This property return a simplified version of tegrastats, it is simple to use if you want log the NVIDIA Jetson status with pandas or in a csv file.

This property is a simplified version of all data collected from your NVIDIA Jetson, if you need more detailed information, please use the other jtop properties

The field listed are:

Name

Type

Reference

Description

time

datetime.datetime

local time in your board

uptime

datetime.timedelta

uptime

up time on your board

cpu X

float

cpu

The status for each cpu in your board, if disabled OFF

RAM

float

memory

RAM used / total

SWAP

float

memory

SWAP used / total

EMC

float

memory

(Optional) EMC Percentage of bandwidth

IRAM

float

memory

(Optional) IRAM used / total

GPU

float

gpu

(Optional) Status of your GPU

engine X

float

engine

(Optional) Frequency for each engine, if disabled OFF

fan

float

fan

(Optional) Fan speed

Temp X

float

power

(Optional) Current power from rail X

Temp TOT

float

power

(Optional) Total power

jetson_clocks

str

jetson_clocks

(Optional) Status of jetson_clocks, human readable

nvpmodel

str

nvpmodel

(Optional) NV Power Model name active

Returns:

Compacts jetson statistics

Return type:

dict

property temperature

BSP thermal management features are part of the firmware running on BPMP for Jetson platforms running any host operating system (host OS) on the CPU.

this attribute provide a dictionary with a list of all thermal rail available on your board.

All temperatures are in Celsius

Name

Type

Description

online

bool

If sensor is online

temp

int

Gets rail voltage in Celsius. (If offline show -256)

max

int

(if available) Gets rail average current limit in Celsius

crit

int

(if available) Gets rail instantaneous current limit in Celsius

Note

all measures are with a 0.5 °C precision margin

Not all values are available, jtop hide some values usually not available:

  • PMIC - For NVIDIA Jetson TX/Nano

Returns:

Temperature dictionary

Return type:

dict

property uptime

Up time, The time since the board is turned on.

This command read the value in /proc/uptime .

Returns:

Board up time

Return type:

datetime.timedelta