📖 API Reference#

class jtop.jtop(interval=0.5)#

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.

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) – Interval to setup the jtop speed (in seconds)

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 you can find:

  • platform (from jtop library is running)

    • Machine

    • System

    • Distribution

    • Release

    • Python

  • hardware (from service is running)

    • Model

    • 699-level Part Number

    • P-Number

    • Module

    • SoC

    • CUDA Arch BIN

    • Codename (Optional)

    • Serial Number

    • L4T (Linux for Tegra)

    • Jetpack

  • libraries (from jtop library is running)

    • CUDA

    • OpenCV

    • OpenCV-Cuda (boolean)

    • cuDNN

    • TensorRT

    • VPI

    • Vulkan

Returns:

Status board, hardware and libraries

Return type:

dict

close()#

This method will 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 cluster#

Cluster status of your board.

If this data is not available in your board will return an empty string

Returns:

Status cluster in your board

Return type:

string

property cpu#

CPU status. From this dictionary you can read the status of the CPU.

For each CPU all fields are:

  • min_freq - Minimum frequency in kHz

  • max_freq - Maximum frequency in kHz

  • frq - Running frequency in kHz

  • governor - Governor selected

  • val - Status CPU, value between [0, 100]

  • model - Model Architecture

  • IdleStates

Returns:

CPU configuration, frequencies and speed

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

  • use - Disk space used in GB

  • available_no_root

Returns:

Disk information

Return type:

dict

property emc#

EMC is the external memory controller, through which all sysmem/carve-out/GART memory accesses go.

If your board have the EMC, the fields are:

  • min_freq - Minimum frequency in kHz

  • max_freq - Maximum frequency in kHz

  • frq - Running frequency in kHz

  • val - Status EMC, value between [0, 100]

  • FreqOverride - Status override

Returns:

emc status

Return type:

dict

property engine#

Engine status, in this property you can find:

APE, DLA, NVDEC, NVENC, and other

Returns:

Dictionary of all active engines

Return type:

dict

property fan#

Fan status and control. From this property you can setup your board

If your board does not support a fan, the output will be None

The variable available are:

  • auto - boolean with fan control.

    • True = Automatic speed control enabled

    • False = Automatic speed control disabled

  • speed - Speed set. Value between [0, 100] (float)

  • measure - Speed measured. Value between [0, 100] (float)

  • rpm - Revolution Per Minute. This number can be 0 if the hardware does not implement this feature

  • mode - Mode selected for your fan

If you want set a new speed, change the mode or know how many configurations are available you can use:

jetson.fan.speed = value

where value is a number between [0, 100] (float)

jetson.fan.mode = name

where name is a string of the mode that you want use

configs = jetson.fan.configs

Return a list of all available configurations:

  • default - The fan is not manage, when jetson_clocks start will follow the jetson_clocks configurations

  • system - The fan speed will be manage from the OS

  • manual - The fan speed is the same that you have set in jetson.fan.speed

Returns:

Status Fan

Return type:

Fan

Raises:

ValueError – Wrong speed number or wrong mode name

property gpu#

GPU engine. The fields are:

  • min_freq - Minimum frequency in kHz

  • max_freq - Maximum frequency in kHz

  • frq - Running frequency in kHz

  • val - Status GPU, value between [0, 100]

Returns:

GPU engine, frequencies and speed

Return type:

dict

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 iram#

IRAM is memory local to the video hardware engine. If your board have the IRAM, the fields are:

  • use - status iram used

  • tot - Total size IRAM

  • unit - Unit size IRAM, usually in kB

  • lfb - Largest Free Block (lfb) is a statistic about the memory allocator

    • size - Size of the largest free block

    • unit - Unit size lfb

Largest Free Block (lfb) is a statistic about the memory allocator. It refers to the largest contiguous block of physical memory that can currently be allocated: at most 4 MB. It can become smaller with memory fragmentation. The physical allocations in virtual memory can be bigger.

Returns:

iram status

Return type:

dict

property jetson_clocks#

Status jetson_clocks, if you want change the jetson_clocks status you can simply write:

jetson.jetson_clocks = value

where value is a boolean value

There are available other extra properties:

  • boot - You can enable and disable on boot jetson_clocks

  • status - A string with the current jetson_clocks status

    • running - The service is running

    • booting - jetson_clocks is in booting (When your board boot, jetson_clocks wait 60s before to start)

    • activating - jetson_clocks is activating

    • deactivating - jetson_clocks is deactivating

You can change and edit using this property:

# Read jetson_clocks boot property
print(jetson.jetson_clocks.boot)
# Set a new value
jetson.jetson_clocks.boot = value  # True or False

Written jetson_clocks status

# Status jetson_clocks
print(jetson.jetson_clocks.status)
Returns:

status jetson_clocks script

Return type:

JetsonClocks

Raises:

ValueError – Wrong jetson_clocks value

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 mts#

MTS foreground and background tasks.

If your board support the MTS variable, the output will be:

  • fg - foreground tasks

  • bg - background tasks

Returns:

mts status

Return type:

dict

property nvpmodel#

From this function you set and read NV Power Mode. If your NVIDIA Jetson does not use nvpmodel will return None

If you want set a new nvpmodel you can follow the NVIDIA Jetson documentation and write a string like below

# You can write a string for a name or an integer for the ID
jetson.nvpmodel = name_or_id

If you need to increase or decrease the ID you can use

jetson.nvpmodel += 1
# or
jetson.nvpmodel = jetson.nvpmodel + 1

There are other properties:

  • name - mode name

  • id - ID name

  • modes - A list with all mode available in your board

  • status - A list of status for each NVP model (False if the nvpmodel is in failure)

  • is_running - Status updating NVP model service

The access of this properties is available like below

# NVP model name
print(jetson.nvpmodel.name)
# NVP model id
print(jetson.nvpmodel.id)
# NVP model list
print(jetson.nvpmodel.modes)
# NVP model status
print(jetson.nvpmodel.status)
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) – If True, this function will be not blocking

property power#

Two power dictionaries:

  • total - The total power estimated is not available of the NVIDIA Jetson power consumption

  • power - A dictionary with all power consumption

For each power consumption there are two fields:

  • avg - Average power consumption in milliwatt

  • cur - Current power consumption in milliwatt

Returns:

Two dictionaries, total and a list of all power consumption available from the board

Return type:

dict, dict

property ram#

RAM available on your board.

  • use - status iram used

  • shared - status of shared memory used from GPU

  • tot - Total size RAM

  • unit - Unit size RAM, usually in kB

  • lfb - Largest Free Block (lfb) is a statistic about the memory allocator

    • nblock - Number of block used

    • size - Size of the largest free block

    • unit - Unit size lfb

Largest Free Block (lfb) is a statistic about the memory allocator. It refers to the largest contiguous block of physical memory that can currently be allocated: at most 4 MB. It can become smaller with memory fragmentation. The physical allocations in virtual memory can be bigger.

Returns:

ram status

Return type:

dict

restore(max_counter=10)#

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

  • switch off jetson_clocks

  • Disable jetson_clocks on boot

  • fan

    • set to default, please follow the fan reference fan()

    • set fan speed to 0 (This operation can require time)

  • If active disable the jtop swap

  • Clear the internal jtop configuration file

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

max_counter (int) – Counter time for each test before fail

Returns:

Generator of all operations to restore your NVIDIA Jetson

Return type:

generator

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:

  • time - A datetime variable with the local time in your board

  • uptime - A timedelta with the up time of your board, same from uptime()

  • jetson_clocks - Status of jetson_clocks, human readable jetson_clocks()

  • nvp model - If exist, the NV Power Model name active nvpmodel()

  • cpu X - The status for each cpu in your board, if disabled you will read OFF

  • GPU - Status of your GPU gpu()

  • MTS FG - Foreground tasks mts()

  • MTS BG - Background tasks mts()

  • RAM - Used ram ram()

  • EMC - If exist, the used emc emc()

  • IRAM - If exist, the used iram iram()

  • SWAP - If exist, the used swap swap()

  • APE - Frequency APE engine engine()

  • NVENC - Frequency NVENC engine engine()

  • NVDEC - Frequency NVDEC engine engine()

  • NVJPG - Frequency NVJPG engine engine()

  • fan - Status fan speed fan()

  • Temp X - X temperature temperature()

  • power cur - Total current power power()

  • power avg - Total average power power()

Returns:

Compacts jetson statistics

Return type:

dict

property swap#

SWAP manager and reader

If you want read the status of your board will return a dictionary with

  • use - Amount of SWAP in use

  • tot - Total amount of SWAP available for applications

  • unit - Unit SWAP, usually in MB

  • cached

    • size - Cache size

    • unit - Unit cache size

This property has other extra methods show below

  • If you want know how many swap are active you can run this extra method

all_swap = jetson.swap.all

The output will be a dictionary, where for each swap:

  • used - Used Swap in kB

  • size - Size in kB

  • type - Type

  • prio - Priority

  • The method inside this property enable a new swap in your board. To work need to write a size in GB and if you want this swap enable in boot you can set on_boot on True (default False). This method will create a new swap located usually in “/” and called “swfile”

jetson.swap.set(size, on_boot=False)

  • If you want disable the swap created you can run this method

jetson.swap.deactivate()

  • This method will show the status of your SWAP created

status = jetson.swap.is_enable

  • This method will show the current swap size created

size = jetson.swap.size()

  • If you need to clear the cache in your NVIDIA Jetson you can run this extra call

jetson.swap.clear_cache()
Returns:

swap status

Return type:

dict

property temperature#

A dictionary with all NVIDIA Jetson temperatures.

All temperatures are in Celsius

Returns:

Temperature dictionary

Return type:

dict

property uptime#

Up time, The time since you turned on the NVIDIA Jetson

Returns:

Board up time

Return type:

timedelta