Getting started
Configuration
There are two main configuration files needed to correctly run the psdk_ros2 wrapper.
link_config.json (default path: psdk_wrapper/cfg)
A json file similar to the one used within the Payload-SDK samples which allows you to configure the type of connection/link you are using to connect to the DJI drone. This is related to the hardware you are using to connect to the drone.psdk_params.yaml (default path: psdk_wrapper/cfg)
A yaml file which defines all ROS 2 parameters used by the wrapper. The information regarding the App configuration (e.g. app_id, app_ket, etc) can be configured here as a ROS 2 parameter.
Hardware connection
Before launching the psdk_ros2 wrapper, you must ensure that you are using the proper hardware connection to the DJI drone you are using. Various methods exist for establishing connections between DJI drones and companion computers. The approach may vary depending on the drone model and the companion computer in use. Below is a summary table illustrating each device port name and the DJI development kit that can be used. For the most recent updates, please refer to the latest version of the table.
Aircraft |
Port Name |
Adapted Development Kit |
|---|---|---|
Matrice 3D/3TD |
E-Port |
E-Port Development Kit |
E-Port Lite |
- |
|
FlyCart 30 |
E-Port Lite |
- |
M350 RTK |
E-Port |
E-Port Development Kit / SDK Round Ribbon Cable |
PSDK Port (Gimbal Port) |
SkyPort V2 Development Kit / SkyPort V2 Production Suit / DJI X-Port |
|
Mavic 3E/3T |
E-Port |
E-Port Development Kit |
Matrice 30/30T |
E-Port |
E-Port Development Kit / SDK Round Ribbon Cable / PSDK Mounting Bracket |
M300 RTK |
OSDK Port |
E-Port Development Kit / SDK Round Ribbon Cable / OSDK Expansion Module |
PSDK Port (Gimbal Port) |
SkyPort V1/V2 Development Kit / X-port / SkyPort V1/V2 Production Suit |
Once you’ve established the hardware connection between your board and the DJI drone, you can configure the psdk_ros2 wrapper to utilize that setup through the psdk_wrapper/cfg/link_config.json file. One important parameter when filling in the link_config.json is to properly select what type of connection you are using. From all the possible configurations, the following have been (so far) tested and validated with the psdk_ros2 wrapper.
Aircraft |
Port Name |
Adapted Development Kit |
psdk_ros2 link config |
|---|---|---|---|
M350 RTK |
E-Port |
SDK Round Ribbon Cable |
use_uart_and_network_device |
Matrice 30/30T |
E-Port |
SDK Round Ribbon Cable |
use_uart_and_network_device |
M300 RTK |
OSDK Port |
OSDK Expansion Module |
use_uart_and_usb_bulk_device |
The link configurations represent the different channels DJI uses to send information from the drone to 3rd party development platforms. In very generic terms, these channels are used for:
UART serial: used to send commands to the drone and receive most of the information
USB Bulk / Network device : used to retrive and send different cameras stream (e.g. main camera, FPV, perception) and perform media file management
Usually the serial interface is supported out-of-the-box by most systems, thus the basic functionalities of the psdk_ros2 wrapper are guaranteed. However, to interact with the different cameras on-board the drone, the USB bulk or Network device interface needs to be enabled on your computer. DJI offers a series of instructions and scripts to set-up the E-Port connection and enable the USB Bulk function for the Jetson Nano and Raspberry Pi 4B boards:
Jetson Nano instructions - Jetson Nano scripts
If you want to enable the Ethernet interface, you can try to follow the instructions provided in the readme.txt file that comes within the scripts folder
Raspberry 4B instructions - Raspberry 4B scripts
For any other board, you must make sure to enable either the USB Bulk or the Network interface to be able to access the camera stream via the psdk_ros2 wrapper. Please check the Basic Concepts page to know more about this topic.
Example of DJI M300 - OKSD Port - OSDK Expansion Module connection
This connection is compatible exclusively with the M300 RTK drone. Upon establishing the connection, two devices will be recognized by the computer, usually /tty/USB0 and /tty/ACM0. To maintain consistent device naming across sessions, refer to the ‘Udev rules’ section, which provides guidance on preventing device name alterations each time the devices are connected.
Steps:
Connect the FTDI adapter to the designated pins on the OSDK Exapansion module for serial communication:
Use a mini-USB A to USB A cable (this cable is different depending on the ftdi module you use) to connect the FTDI adapter to the computer’s USB 2.0 port
Connect the USB A to USB A from the OSDK Expansion module to the USB port of the computer
Connect the power cable from the OSDK Expansion module to supply power to the companion computer
Use the default link_config.json file to run the psdk_ros2 wrapper
Caution: The OSDK expansion module outputs 24V. Ensure that your companion computer can tolerate this voltage level. If not, you must use an appropriate step-down module to reduce the voltage to a safe level for your device.
ROS 2 Parameter configuration
The following parameters can be configured in the psdk_wrapper/cfg/psdk_params.yaml file:
Parameter |
Data Type |
Default Value |
Comments |
|---|---|---|---|
app_name |
String |
- |
Add your App name |
app_id |
String |
- |
Add your App id |
app_key |
String |
- |
Add your App key |
app_license |
String |
- |
Add your App license |
developer_account |
String |
- |
Add your developer account (not mandatory) |
baudrate |
String |
921600 |
- |
num_of_initialization_retries |
Int |
1 |
Num of retries to init the PSDK app |
tf_frame_prefix |
String |
TF frame prefix |
Add prefix before the frame name |
imu_frame |
String |
“psdk_imu_link” |
- |
body_frame |
String |
“psdk_base_link” |
- |
map_frame |
String |
“psdk_map_enu” |
- |
gimbal_frame |
String |
“psdk_gimbal_link” |
- |
camera_frame |
String |
“psdk_camera_link” |
- |
mandatory_modules |
|||
- telemetry |
Bool |
True |
Trigger node failure, if module not loaded |
- flight_control |
Bool |
True |
Trigger node failure, if module not loaded |
- camera |
Bool |
False |
Trigger node failure, if module not loaded |
- gimbal |
Bool |
False |
Trigger node failure, if module not loaded |
- liveview |
Bool |
False |
Trigger node failure, if module not loaded |
- hms |
Bool |
False |
Trigger node failure, if module not loaded |
data_frequency |
Object |
- |
Options are: 1, 5, 10, 50, 100, 200, 400 Hz |
- imu |
Integer |
100 |
- |
- attitude |
Integer |
100 |
- |
- acceleration |
Integer |
50 |
- |
- velocity |
Integer |
50 |
- |
- angular_velocity |
Integer |
100 |
- |
- position |
Integer |
50 |
- |
- altitude |
Integer |
50 |
- |
- gps_data |
Integer |
1 |
- |
- rtk_data |
Integer |
1 |
- |
- magnetometer |
Integer |
50 |
- |
- rc_channels_data |
Integer |
1 |
- |
- gimbal_data |
Integer |
1 |
- |
- flight_status |
Integer |
1 |
- |
- battery_level |
Integer |
1 |
- |
- control_information |
Integer |
1 |
- |
- esc_data_frequency |
Integer |
1 |
- |
Running the psdk_ros2 wrapper
Debian packages for ROS 2 Humble
# Install debians
sudo apt install ros-humble-psdk-wrapper ros-humble-psdk-interfaces
source /opt/ros/humble/setup.bash
# Launch the node
# Default link_config_file_path = /opt/ros/humble/share/psdk_wrapper/cfg/link_config.json
# Default psdk_params_file_path = /opt/ros/humble/share/psdk_wrapper/cfg/psdk_params.yaml
# If using parameter and config files different than the default ones, you can point to them as:
ros2 launch psdk_wrapper wrapper.launch.py link_config_file_path:=/absolute/path/to/config.json psdk_params_file_path:=/absolute/path/to/params.yml
Compile from source
To use the psdk_ros2 wrapper you will need to create a new workspace in which you clone both the wrapper as well as the Payload-SDK libraries.
mkdir -p ~/psdk_ros2_ws/src
cd ~/psdk_ros2_ws/src
# Clone the psdk_ros2 wrapper
git clone https://github.com/umdlife/psdk_ros2.git
# Before building, check the Dependencies section and make sure you have everything installed
# You can also run rosdep to automatically install the dependencies
rosdep update
rosdep keys --from-paths . --ignore-src --rosdistro humble | \
xargs rosdep resolve --rosdistro humble | \
awk '/#apt/{getline; print}' > ./rosdep_requirements.txt
sudo apt install -y --no-install-recommends $(cat ./rosdep_requirements.txt)
# Build the code
cd ~/psdk_ros2_ws
colcon build
# Launch the node
ros2 launch psdk_wrapper wrapper.launch.py
# Default link_config_file_path = psdk_wrapper/cfg/link_config.json
# Default psdk_params_file_path = psdk_wrapper/cfg/psdk_params.yml
# If using parameter and config files different than the default ones, you can point to them as:
ros2 launch psdk_wrapper wrapper.launch.py link_config_file_path:=/absolute/path/to/config.json psdk_params_file_path:=/absolute/path/to/params.yml
Udev rules
To avoid changing the device name each time you run the psdk application, you can use the following udev rules
# DJI Serial Comm
SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ATTRS{idVendor}=="YourVendor", ATTRS{idProduct}=="YourProduct", MODE="0666", SYMLINK+="dji_serial"
# DJI Advanced Sensing
SUBSYSTEM=="tty", SUBSYSTEMS=="usb", ATTRS{idVendor}=="YourVendor", ATTRS{idProduct}=="YourProduct", MODE="0666", SYMLINK+="dji_advanced_sensing"
Dependencies
ROS 2 packages
The following ROS 2 packages are needed to successfully build the wrapper:
rclcpp
rclcpp_lifecycle
tf2
tf2_ros
sensor_msgs
geometry_msgs
std_msgs
nav_msgs
std_srvs
Other libraries
The following libraries are needed to enable the access to USB devices and handling the video streaming:
libusb-1.0-0-dev
libopus-dev
ffmpeg
libavcodec-dev
libavformat-dev
libavfilter-dev
The following library is used to work with JSON:
nlohmann-json-dev