diff --git a/docs/_03_aerial_platforms/_dji_psdk/index.rst b/docs/_03_aerial_platforms/_dji_psdk/index.rst index 648af0aa..c0871867 100644 --- a/docs/_03_aerial_platforms/_dji_psdk/index.rst +++ b/docs/_03_aerial_platforms/_dji_psdk/index.rst @@ -5,22 +5,23 @@ DJI Matrice Series PSDK ======================= .. contents:: Table of Contents - :depth: 3 + :depth: 2 :local: - .. _aerial_platform_dji_matrice_psdk_introduction: ------------ Introduction ------------ -DJI Matrice Series using `DJI Onboard PSDK `_ has compatibility with DJI M300, DJI M350 and DJI M30T. +The DJI Matrice Series using `DJI Onboard PSDK `_ +is compatible with **DJI M300, DJI M350, and DJI M30T**. .. figure:: resources/DJI_M300.jpg :scale: 15 :class: with-shadow + :alt: DJI Matrice M300 .. _aerial_platform_dji_matrice_psdk_installation: @@ -31,57 +32,60 @@ Installation .. _aerial_platform_matrice_psdk_installation_prerequisites: -Prerequisites to configure any Xavier/Orin NX/AGX board to connect to PSDK, These steps are only done **once** -============================================================================================================== + +Prerequisites (One-Time Setup on Xavier/Orin NX/AGX Boards) +============================================================= + .. _aerial_platform_dji_matrice_psdk_installation_prerequisites_software_once: +1. Clone configuration repository +--------------------------------- -Clone configuration repository to grab the necessary files ------------------------------------------------- .. code-block:: console cd ~ git clone git@github.com:aerostack2/psdk_config_files.git cd psdk_config_files -Disable l4t-device-mode auto start ----------------------------------------------- +2. Disable ``l4t-device-mode`` auto start +----------------------------------------- .. code-block:: console sudo systemctl disable nv-l4t-usb-device-mode.service -Replace system device-mode script ---------------------------------- +3. Replace system device-mode script +------------------------------------ Copy your custom startup script into place and make it executable: .. code-block:: console - sudo cp ./nv-l4t-usb-device-mode-start.sh /opt/nvidia/l4t-usb-device-mode/nv-l4t-usb-device-mode-start.sh + sudo cp ./nv-l4t-usb-device-mode-start.sh \ + /opt/nvidia/l4t-usb-device-mode/nv-l4t-usb-device-mode-start.sh chmod +x ./nv-l4t-usb-device-mode-start.sh -Customize the script program --------------------------------- -You need to modify the script to use the correct USB-UDC port. +4. Customize the script +----------------------- -For the AGX: +Update the script to use the correct **USB-UDC port**: -.. code-block:: console +- **For AGX:** - sed -i 's/3550000\.xudc/3550000.usb/g' nv-l4t-usb-device-mode-start.sh + .. code-block:: console -For the NX: + sed -i 's/3550000\.xudc/3550000.usb/g' nv-l4t-usb-device-mode-start.sh -.. code-block:: console +- **For NX:** - sed -i 's/3550000\.usb/3550000.xudc/g' nv-l4t-usb-device-mode-start.sh + .. code-block:: console + sed -i 's/3550000\.usb/3550000.xudc/g' nv-l4t-usb-device-mode-start.sh -Grab bulk-mode program folder ------------------------------- +5. Grab bulk-mode program folder +-------------------------------- -Download and unzip the reference package into `~/Desktop/startup_bulk`: +Download and unzip the reference package into ``~/Desktop/startup_bulk``: .. code-block:: console @@ -90,56 +94,59 @@ Download and unzip the reference package into `~/Desktop/startup_bulk`: && mv startup_bulk/ ~/Desktop/ \ && chmod +x ~/Desktop/startup_bulk/* +6. Reboot +--------- -Reboot ------- - -Load necessary kernel modules on boot ------------------------------------- +7. Load necessary kernel modules on boot +---------------------------------------- -Append to `/etc/modules` (ensure the file remains correctly formatted): +Append to ``/etc/modules`` (ensure correct formatting): .. code-block:: console echo -e "configfs\nlibcomposite\nusb_f_fs\ntegra-xudc" | sudo tee -a /etc/modules -Test the setup --------------- +8. Test the setup +----------------- .. code-block:: console - cd /opt/nvidia/l4t-usb-device-mode/ + cd /opt/nvidia/l4t-usb-device-mode/ ./nv-l4t-usb-device-mode-start.sh -If it works, re-enable the service ------------------------------------ +9. Re-enable the service (if successful) +---------------------------------------- .. code-block:: console sudo systemctl enable /opt/nvidia/l4t-usb-device-mode/nv-l4t-usb-device-mode.service -Now both bulk mode and network mode are configured. +Now both **bulk mode** and **network mode** are configured. -Prerequisites to configure any Xavier/Orin NX/AGX board to connect to PSDK, These steps are only done **every time the board boots up** -======================================================================================================================================= -.. _aerial_platform_dji_matrice_psdk_installation_prerequisites_software_every_time: + +Prerequisites (Every Boot on Xavier/Orin NX/AGX Boards) +================================================================= + +.. _aerial_platform_dji_matrice_psdk_installation_prerequisites_software_every_time: M300 ---- **Hardware** -Use the Type-C port supporting both bulk and usbnet mode -- Onboard computer = host -- E-Port = device. +- Onboard computer = **host** +- E-Port = **device** +- Use the Type-C port supporting both bulk and usbnet mode. -.. image:: resources/device_mode.jpg - :alt: E-Port in device mode +|m300_pic1| |m300_pic2| -- On the AGX, connections as shown: +.. |m300_pic1| image:: resources/device_mode.jpg + :width: 45% + :alt: E-Port in device mode -.. image:: resources/agx_connections.jpg - :alt: AGX USB connections +.. |m300_pic2| image:: resources/agx_connections.jpg + :width: 45% + :alt: AGX USB connections (device) **Software** @@ -149,23 +156,26 @@ Enable host mode on the onboard computer: echo host | sudo tee /sys/class/usb_role/usb2-0-role-switch/role -You should now see `/dev/ttyACM0` when powering on the drone. +You should now see ``/dev/ttyACM0`` when powering on the drone. + M350 ---- **Hardware** -Use the Type-C port supporting both bulk and usbnet mode -- Onboard computer = device -- E-Port = host. +- Onboard computer = **device** +- E-Port = **host** +- Use the Type-C port supporting both bulk and usbnet mode. -.. image:: resources/host_mode.jpg - :alt: E-Port in host mode +|m350_pic1| |m350_pic2| -- On the AGX, connections as shown: +.. |m350_pic1| image:: resources/host_mode.jpg + :width: 45% + :alt: E-Port in host mode -.. image:: resources/agx_connections.jpg +.. |m350_pic2| image:: resources/agx_connections.jpg + :width: 45% :alt: AGX USB connections (host) **Software** @@ -176,36 +186,40 @@ Enable device mode on the onboard computer: echo device | sudo tee /sys/class/usb_role/usb2-0-role-switch/role -Bring up the `l4tbr0` interface: +Bring up the ``l4tbr0`` interface: .. code-block:: console sudo ifconfig usb0 192.168.1.1 netmask 255.255.255.0 up -Then verify with: +Verify with: .. code-block:: console ifconfig -You should see an entry for `l4tbr0`. If not, repeat the above steps. +You should see an entry for ``l4tbr0``. +If not, repeat the above steps. + M30T ---- **Hardware** -Use the Type-C port supporting both bulk and usbnet mode -- Onboard computer = device -- E-Port = host. +- Onboard computer = **device** +- E-Port = **host** +- Use the Type-C port supporting both bulk and usbnet mode. -.. image:: resources/host_mode.jpg - :alt: E-Port in host mode +|m30t_pic1| |m30t_pic2| -- On the NX, connections as shown: +.. |m30t_pic1| image:: resources/host_mode.jpg + :width: 45% + :alt: E-Port in host mode -.. image:: resources/nx_connections.jpg - :alt: NX USB connections +.. |m30t_pic2| image:: resources/nx_connections.jpg + :width: 45% + :alt: NX USB connections (host) **Software** @@ -215,64 +229,87 @@ Enable device mode on the onboard computer: echo device | sudo tee /sys/class/usb_role/usb2-0-role-switch/role -Bring up the `l4tbr0` interface: +Bring up the ``l4tbr0`` interface: .. code-block:: console sudo ifconfig usb0 192.168.1.1 netmask 255.255.255.0 up -Then verify with: +Verify with: .. code-block:: console ifconfig -You should see an entry for `l4tbr0`. If not, repeat the above steps. +You should see an entry for ``l4tbr0``. +If not, repeat the above steps. .. note:: -This leaves both bulk and network mode enabled. You can switch between them by running the appropriate command. In -order to connect to the drone, either in bulk or network mode, you need to run the platform with the following JSON parameter values: - -.. code-block:: json - - . - . - . - "uart_config": { - "uart1_device_name": "/dev/ttyUSB0", - "uart2_device_enable": "true", - "uart2_device_name": "/dev/ttyACM0" - }, - "network_config": { - "network_device_name": "l4tbr0", - "network_usb_adapter_vid": "0x0B95", - "network_usb_adapter_pid": "0x1790" - } - + Both bulk and network mode remain enabled. + The ``link_select`` parameter in the platform configuration should be + ``use_uart_and_usb_bulk_device`` for M300 and + ``use_uart_and_network_device`` for M350 and M30T. + To connect to the drone, run the platform with the following JSON parameters: + + .. code-block:: json + + { + "dji_sdk_link_config": { + "link_available": "use_only_uart/use_uart_and_usb_bulk_device/use_uart_and_network_device", + "link_select": "use_uart_and_network_device", + "uart_config": { + "uart1_device_name": "/dev/ttyUSB0", + "uart2_device_enable": "true", + "uart2_device_name": "/dev/ttyACM0" + }, + "network_config": { + "network_device_name": "l4tbr0", + "network_usb_adapter_vid": "0x0B95", + "network_usb_adapter_pid": "0x1790" + }, + "usb_bulk_config": { + "usb_device_vid": "0x0B95", + "usb_device_pid": "0x1790", + "usb_bulk1_device_name": "/dev/usb-ffs/bulk1", + "usb_bulk1_interface_num": "2", + "usb_bulk1_endpoint_in": "0x83", + "usb_bulk1_endpoint_out": "0x02", + "usb_bulk2_device_name": "/dev/usb-ffs/bulk2", + "usb_bulk2_interface_num": "3", + "usb_bulk2_endpoint_in": "0x84", + "usb_bulk2_endpoint_out": "0x03" + } + } + } + + .. _aerial_platform_dji_matrice_psdk_installation_package: -Install platform package + +Install Platform Package ======================== -* For binary installation, install by running: +Binary installation +------------------- .. code-block:: bash sudo apt install ros-humble-as2-platform-dji-psdk - -* For source installation, follow the steps below: +Source installation +------------------- .. code-block:: bash - # If you have installed Aerostack2 from sources we recommend to clone the package in the src folder of your workspace otherwise you can clone it in any ROS 2 workspace you want. - cd ~/aerostack2_ws/src/aerostack2/as2_aerial_platforms - git clone git@github.com:aerostack2/as2_platform_dji_psdk.git - cd ~/aerostack2_ws - rosdep install as2_platform_dji_psdk --from-paths src --ignore-src -r -y - colcon build --packages-up-to as2_platform_dji_psdk + # If Aerostack2 was installed from sources, clone into the src folder of your workspace. + cd ~/aerostack2_ws/src/aerostack2/as2_aerial_platforms + git clone git@github.com:aerostack2/as2_platform_dji_psdk.git + cd ~/aerostack2_ws + rosdep install as2_platform_dji_psdk --from-paths src --ignore-src -r -y + colcon build --packages-up-to as2_platform_dji_psdk + .. _aerial_platform_dji_matrice_psdk_as2_common_interface: @@ -280,18 +317,14 @@ Install platform package Aerostack2 Common Interface --------------------------- -For more details about platform control modes and sensors, see :ref:`Aerostack2 Aerial Platform Concepts `. - +For more details about platform control modes and sensors, see +:ref:`Aerostack2 Aerial Platform Concepts `. -.. _aerial_platform_dji_matrice_psdk_as2_common_interface_control_modes: - Control Modes ============= -These are supported control modes: - -.. list-table:: Control Modes DJI PSDK Platform +.. list-table:: Supported Control Modes for DJI PSDK Platform :widths: 50 50 50 :header-rows: 1 @@ -303,14 +336,10 @@ These are supported control modes: - ENU -.. _aerial_platform_dji_matrice_psdk_as2_common_interface_sensors: - Sensors ======= -These are supported sensors: - -.. list-table:: Sensors DJI PSDK Platform +.. list-table:: Supported Sensors for DJI PSDK Platform :widths: 50 50 50 :header-rows: 1 @@ -346,10 +375,12 @@ Aerostack2 provides a launch file for this platform: ros2 launch as2_platform_dji_psdk as2_platform_dji_psdk.launch.py -Also, `ROS 2 PSDK Wrapper `_ must be launched before the platform: +Additionally, the `ROS 2 PSDK Wrapper `_ +must be launched before the platform: .. code-block:: bash ros2 launch as2_platform_dji_psdk psdk_wrapper.launch.py -To see all the **available parameters**, use the **'-s'** flag to show the description of each parameter in the launch file. +To view all **available parameters**, use the ``-s`` flag to show descriptions +in the launch file.