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:

Reading /etc/nv_tegra_release
Reading version in nvidia-l4t-core package

Note B

The CUDA version is read depend of the version in:

On /usr/local/cuda/version.txt
Running nvcc --version

Reference

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

Reference

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)

Reference

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

Reference

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

Jetson Xavier NX and Jetson Orin NX - Output VDD_IN
Jetson Nano - Output POM_5V_IN

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

Reference

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)

Reference

https://man7.org/linux/man-pages/man5/proc.5.html

Returns:: list of all GPU processes
Return type:: list

restore(max_counter=10)¶

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

Switch off, disable on boot jetson_clocks and remove configuration file(reference JetsonClocks)
Set all fan to default profile and all speed to zero (reference Fan)
Set to default nvpmodel (reference NVPModel)
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

Reference

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