SDK Development
===============

This section summarises how to set up and develop applications for the Unitree A2 using the official SDKs. It
is based on Unitree's
`A2 SDK Development Guide <https://support.unitree.com/home/en/A2_SDK_Development_Guide>`_ and the public
Unitree repositories. Always treat the official guide as the authoritative reference for your firmware version.

Overview
--------

The A2 is controlled through Unitree's DDS-based communication stack. Two primary SDKs are available:

- **unitree_sdk2** — the C++ SDK for high- and low-level control, state subscription, and sensor access.
  Repository: `unitree_sdk2 <https://github.com/unitreerobotics/unitree_sdk2>`_.

- **unitree_ros2** — ROS 2 packages that bridge the same DDS interface into ROS 2 topics and messages.
  Repository: `unitree_ros2 <https://github.com/unitreerobotics/unitree_ros2>`_.

All Unitree open-source SDKs are published under the
`Unitree Robotics GitHub organisation <https://github.com/unitreerobotics>`_.

Requirements
------------

+-------------------------------+----------------------------------------------+
| **Item**                      | **Requirement**                              |
+===============================+==============================================+
| Operating System              | Ubuntu 20.04 LTS                             |
+-------------------------------+----------------------------------------------+
| Compiler                      | GCC 9.4.0 (C++17)                            |
+-------------------------------+----------------------------------------------+
| Build System                  | CMake 3.10+                                  |
+-------------------------------+----------------------------------------------+
| Architecture                  | x86_64 or aarch64                            |
+-------------------------------+----------------------------------------------+
| Transport                     | DDS (CycloneDDS)                             |
+-------------------------------+----------------------------------------------+

Installing Dependencies
-----------------------

Install the build toolchain and required libraries:

.. code-block:: bash

   sudo apt update
   sudo apt install -y cmake g++ build-essential \
       libyaml-cpp-dev libeigen3-dev libboost-all-dev \
       libspdlog-dev libfmt-dev

Building and Installing unitree_sdk2
------------------------------------

Clone and build the C++ SDK:

.. code-block:: bash

   git clone https://github.com/unitreerobotics/unitree_sdk2.git
   cd unitree_sdk2
   mkdir build && cd build
   cmake ..
   make

To install the SDK system-wide (recommended for use in your own CMake projects):

.. code-block:: bash

   cd unitree_sdk2/build
   cmake .. -DCMAKE_INSTALL_PREFIX=/opt/unitree_robotics
   sudo make install

Network Configuration
---------------------

The A2 communicates with a development PC over Gigabit Ethernet using DDS. Unitree robots use the
``192.168.123.x`` subnet by convention. Configure your PC's wired interface to a static address on the same
subnet (for example ``192.168.123.222``) and verify connectivity before running any example.

.. code-block:: bash

   # Example: set a static IP on the wired interface (replace eth0 with your NIC)
   sudo ip addr add 192.168.123.222/24 dev eth0
   sudo ip link set eth0 up

   # Confirm the robot is reachable
   ping 192.168.123.<robot>

.. important::

   The exact robot IP address and network setup are documented in the official
   `A2 SDK Development Guide <https://support.unitree.com/home/en/A2_SDK_Development_Guide>`_. Confirm the
   address for your unit before configuring your PC.

Specifying the Network Interface
--------------------------------

``unitree_sdk2`` examples and applications must be told which network interface is connected to the robot. The
interface name (for example ``eth0``) is passed as a command-line argument when launching an example:

.. code-block:: bash

   # Run a built example, passing the network interface name
   ./example_program eth0

In your own code, the interface is supplied when initialising the DDS channel factory:

.. code-block:: cpp

   #include <unitree/robot/channel/channel_factory.hpp>

   int main(int argc, char** argv)
   {
       // argv[1] is the network interface connected to the A2 (e.g. "eth0")
       unitree::robot::ChannelFactory::Instance()->Init(0, argv[1]);
       // ... create publishers / subscribers and control the robot ...
       return 0;
   }

ROS 2 Driver (unitree_ros2)
---------------------------

For ROS 2 integration, use `unitree_ros2 <https://github.com/unitreerobotics/unitree_ros2>`_, which exposes the
A2's DDS interface as ROS 2 topics. The package relies on a CycloneDDS RMW configured to bind to the network
interface connected to the robot. After sourcing the workspace, set the DDS configuration and interface as
described in the repository README, then launch the bridge.

.. code-block:: bash

   git clone https://github.com/unitreerobotics/unitree_ros2.git
   # Build and source per the repository instructions, then configure
   # CYCLONEDDS_URI to bind the RMW to the robot-facing interface.

.. note::

   ROS 2 distribution support and exact build steps are version-dependent. Follow the ``unitree_ros2`` README
   for the supported distribution and the current CycloneDDS configuration.

Safety When Developing
----------------------

.. warning::

   Custom control code can command the robot into unsafe states. Always test new control software with the robot
   safely supported or in a clear, open area, keep the emergency stop within reach, and validate joint commands
   against the documented limits before deployment.

Further Resources
-----------------

- `A2 SDK Development Guide (official) <https://support.unitree.com/home/en/A2_SDK_Development_Guide>`_
- `unitree_sdk2 (C++ SDK) <https://github.com/unitreerobotics/unitree_sdk2>`_
- `unitree_ros2 (ROS 2 packages) <https://github.com/unitreerobotics/unitree_ros2>`_
- `Unitree Robotics on GitHub <https://github.com/unitreerobotics>`_
- `Unitree Document Center <https://support.unitree.com/home/en/developer>`_