This section provides pointers on how to get started with developing and running Isaac applications.
There is a Isaac Webinar available that explains how to develop an application by writing a codelet and creating an application graph.
There are over 30 tutorials and samples provided with Isaac SDK to get you started. You can learn more about sample applications in the Sample Applications section.
For example, a sample application can be run a easily as executing the following command:
bob@desktop:~/isaac/sdk$ bazel build //apps/samples/stereo_dummy
This section explains how to run the stereo_dummy sample application on your desktop. All other applications can be run in a similar matter by using the corresponding bazel target name of the application.
A bazel target name for example has the following form:
//app/samples/stereo_dummy. This refers to
stereo_dummy in the folder
app/samples/stereo_dummy. If you want to run a
different application you have to change the target name correspondingly.
Note that all bazel build and bazel run commands should be executed at the root folder of your
repository. For example if your root folder is
/home/bob/isaac you first go to the directory
/home/bob/isaac and then run the commands mentioned below.
- Build the sample application with the following command on the host system:
bob@desktop:~/isaac/sdk$ bazel build //apps/samples/stereo_dummy
- Run the sample application with the following command:
bob@desktop:~/isaac/sdk$ bazel run //apps/samples/stereo_dummy
bazel run command first builds and then runs the application. If you want to run an application
bazel run is enough. Remember to run
bazel run at the root folder of your repository as explained above.
3. Once you have an application running, open the visualization frontend by opening
http://localhost:3000 in a browser.
In case you want to run an application with additional configuration parameters you can pass these configuration files on the command line as follows:
bob@desktop:~/isaac/sdk$ bazel run //apps/samples/stereo_dummy -- --config more_config.json
Note the double dash
-- to separate arguments to bazel from arguments to the application.
The following bazel commands are useful:
Build and run an application in GDB for debugging (in this example, pose_tensorrt_inference) with the following commands:
bob@desktop:~/isaac/sdk$ bazel build -c dbg //apps/samples/pose_tensorrt_inference bob@desktop:~/isaac/sdk$ gdb --args bazel-bin/engine/alice/tools/main --app apps/samples/pose_tensorrt_inference/pose_tensorrt_inference.app.json
bob@desktop:~/isaac/sdk$ bazel build ...
Build only one target:
bob@desktop:~/isaac/sdk$ bazel build //engine/gems/filters/examples:ekf_sin_exp
Run all tests:
bob@desktop:~/isaac/sdk$ bazel test ... --jobs=1
Run one test:
bob@desktop:~/isaac/sdk$ bazel test //engine/gems/optimization/tests:pso_ackley
Run linter checks:
bob@desktop:~/isaac/sdk$ bazel test --config=lint ...
The linter requires Python 2.7. If all files fail the linter tests, the Python path is probably the issue. Try:
bob@desktop:~/isaac/sdk$ bazel test --python_path=/usr/bin/python2.7 --config=lint ...
Application Console Options
C++ applications are run by the Isaac Alice engine, which provides the following console options
bazel run -- <app_path> <options>.
Applications that are written in Python or C may have unique console options, rather than
those shown below. Unique options can be retrieved using
bazel run -- <app_path> --help.
--max_duration: The maximum duration to run the app for in
--app: The filename of a JSON file for app definition
--application_backup: The filename under which to store the whole application JSON just before the application is stopped
--asset_path: The path in which to search for assets
--component_info_out: If enabled, a JSON object with information about all registered components is written to the specified file.
--configA comma-separated list of configuration files in JSON format that specify additional configuration. Configuration parameters are written in the order in which they are loaded, so the latest file takes precedence. Optionally, you can specify a prefix that will be applied to all node names. The format is
--config_backup: The filename under which to store the current configuration just before the application is stopped.
--graph: A comma-separated list of node graph files in JSON format. This can be used to create additional nodes. Note that this option may have unexpected side effects depending on which nodes are already loaded.
--localeThe application locale
--minidump_path: The path to write the minidump file in case of a crash
--module_paths: A comma-separated list of paths from which to load shared libs for modules
--more: A comma-separated list of additional app files in JSON format to load
--performance_report_out: The filename under which a performance report will be written just before the application is stopped
This section briefly explains how to deploy an application from your desktop machine to the robot and how to run it.
The Isaac SDK fully supports cross-compilation for Jetson. Compiling the source code on Jetson itself is not recommended.
The following two steps need to be run only once:
- Make sure you have an SSH key on your desktop machine.
- Copy your SSH identity to the robot using the user name and IP you use to login on the robot with a command similar to the following:
bob@desktop:~/isaac/sdk$ ssh-copy-id <username_on_robot>@<robot_ip> where <username_on_robot> is your user name on the robot, and <robot_ip> is the IP address of the robot.
You might need to connect the robot to a screen to get its IP address.
To run the stereo_dummy sample application on the robot, first deploy the package to the robot with the following command:
bob@desktop:~/isaac/sdk$ ./../engine/engine/build/deploy.sh --remote_user <username_on_robot> -p //apps/samples/stereo_dummy:stereo_dummy-pkg -d jetpack45 -h <robot_ip>
where <robot_ip> is the IP address of the robot and <username_on_robot> is your user name on the robot.Note
If a username is not specified with the –remote_user option, the default username used is
-d jetpack45option specifies that we are building and deploying to a Jetson device with Jetpack version 4.5.1.
Login to the robot to run the application:
bob@jetson:~/isaac$ ssh ROBOTUSER@ROBOTIP
- Go to the deployment folder and run the application:
bob@jetson:~/$ cd deploy/bob/stereo_dummy-pkg bob@jetson:~/deploy/bob/stereo_dummy-pkg$ ./apps/samples/stereo_dummy/stereo_dummy Here "bob" is the user name you use on your host system. You can deploy under a different folder by specifying :code:`-u OTHER_USER` to :code:`deploy.sh` in step 3.
To automatically run the application on the robot after deployment, run deploy.sh with
the --run (or -r) option, as follows (from the
./../engine/engine/build/deploy.sh --remote_user <username_on_robot> -p //apps/samples/stereo_dummy:stereo_dummy-pkg \ -d jetpack45 -h <robot_ip> --run
Using the --run option in step 3 causes deploy.sh to effectively perform steps 4 and 5 for you.
- Once the application is running, connect to it in your browser and inspect the running
application with websight. To do so navigate to
http://ROBOTIP:3000in your browser.
In case you want to run an application with additional configuration parameters you can pass these
configuration files on the command line with the the
--config option as follows:
bob@desktop:~/isaac/sdk$ ./apps/samples/stereo_dummy/stereo_dummy --config more_config.json
The Isaac SDK provides basic Python support. However support for Python is in an experimental state in this release. The API is not stable or feature complete.
The tutorial in
//apps/samples/ping_python is similar to the ping tutorial for C++ but
implemented in Python. It is available on all platforms and does not require any hardware.
Running a Python application on a desktop system is identical to running a C++ application as explained in section Running an Application. Deploying a Python app to Jetson is identical to deploying a C++ application as explained in Application Console Options.
However running a Python application on Jetson is slightly different. Using the
is necessary to set certain environment variables required for Python. In step 5 of Deploying and
Running on Jetson, use the following commands to run an application:
bob@jetson:~/$ cd deploy/bob/ping_python-pkg bob@jetson:~/deploy/bob/ping_python-pkg$ ./run ./apps/tutorials/ping_python/ping_python.py
Where “bob” is you username on your desktop system.
To manage your code in separate workspace, see the example
https://github.com/nvidia-isaac/velodyne_lidar and fork it as starting point, if desired,
with the following steps:
- Download Isaac SDK and extract the TAR archive to a preferred folder.
- Download the velodyne_lidar repository at the link above or fork it as desired.
- Open the
WORKSPACEfile in the velodyne_lidar repository, change the workspace name as desired and specify the path to the Isaac SDK workspaces for
- Test the setup by building and running the workspace with the following commands:
bob@desktop:~/velodyne_lidar$ bazel build ... bob@desktop:~/velodyne_lidar$ bazel run //packages/velodyne_lidar/apps:vlp16_sample
- Write more code!
Isaac SDK development can be done in Docker container, allowing teams to use a standard environment, and use that environment inside of non-Linux operating systems, such as Windows and Mac OS. This section describes how to build and run an Isaac SDK Docker container.
- Install off-the-shelf docker with the following command:
- Install NVIDIA docker over off-the-shelf Docker by following the steps in the Installation Guide.
Creating an Isaac SDK Development Image
After installing dependencies, run the following script to create the
isaacbuildimage for Isaac SDK development:
Create a cache volume for faster builds with the following command:
bob@desktop:~/isaac$ docker volume create isaac-sdk-build-cache
Run the container with the following command:
bob@desktop:~/isaac$ docker run --mount source=isaac-sdk-build-cache,target=/root -v `pwd`:`pwd` -w `pwd`/sdk --runtime=nvidia -it isaacbuild:latest /bin/bash
Run the following command inside the container to build Isaac SDK:
bob@docker-container:~/isaac/sdk$ bazel build ...