How dji-sdk/payload-sdk works
1. What this repo is
This is DJI’s Payload SDK (PSDK) distribution. It is not a single application; it is a vendor SDK plus example payload applications for mounting on DJI aircraft through X-Port, SkyPort, or adapter-based payload interfaces.
2. Core SDK boundary
The real SDK surface lives in psdk_lib/include, which exposes feature-oriented APIs such as flight controller, camera manager, gimbal, liveview, waypoint, HMS, positioning, power management, upgrade, time sync, data channels, cloud API, widget, and payload collaboration.
The implementation is delivered as prebuilt static libraries under psdk_lib/lib, keyed by target toolchain/architecture.
3. Primary runtime flow
Sample applications call PSDK APIs → PSDK talks to the aircraft/payload link → telemetry, media, and control data come back into the app.
The repo’s architecture is centered on this host-side integration pattern: the app layer owns business logic, while the SDK and platform layers hide the transport and hardware details.
4. C vs. C++ sample stacks
The repository has two parallel sample families:
- samples/sample_c: broader coverage, more embedded/RTOS-oriented examples, including camera emulation, FC subscription, data transmission, MOP channel, upgrade, widget, waypoint, perception, and payload control.
- samples/sample_c++: module samples for camera manager, flight controller, gimbal, HMS manager, liveview, perception, positioning, and widget manager.
These are separate integration styles built on the same underlying SDK.
5. Feature-module architecture
Samples are organized by capability rather than by product. Each module maps to an SDK subsystem:
- flight control and FC subscription: command/telemetry control
- camera manager/liveview: imaging, stream handling, and media management
- gimbal and gimbal manager: motion control
- HMS: health and message reporting
- waypoint v2/v3: mission planning
- widget/widget manager: payload UI/interaction
- upgrade: firmware and payload update flows
- data transmission / MOP / xport: payload communication channels
6. Platform abstraction layer
Platform-specific code is isolated under samples/.../platform/... and acts as the glue between the SDK and the underlying OS/hardware.
Linux targets include Manifold 2, Manifold 3, NVIDIA Jetson, and Raspberry Pi. These provide hal_network, hal_uart, hal_usb_bulk, and a shared osal layer for sockets, filesystem, and threading-ish runtime services.
7. RTOS/embedded stack
The RTOS samples under samples/sample_c/platform/rtos_freertos are more vertically integrated. They bundle:
- board-specific application code
- HAL drivers for UART, I2C, USB, LEDs, CAN, PWM, etc.
- FreeRTOS and vendor MCU libraries
- bootloader and upgrade logic
This layer is the hardware/firmware boundary for MCU-class payloads.
8. Bootloader and upgrade path
Several RTOS targets include a separate bootloader, plus update utilities such as YMODEM transfer and platform-specific upgrade hooks.
Architecturally, this means firmware update is treated as a first-class subsystem, not just an app feature: the sample app delegates update transport/flash handling to dedicated bootloader and BSP code.
9. Vision/media pipeline in liveview
The C++ liveview sample is a distinct media-processing pipeline. It includes stream decoding, camera image handling, and object-detection-oriented processing.
The repo ships model/data assets alongside the code, including TensorFlow and YOLO-Fastest files plus a face cascade, showing that the liveview example is meant to ingest the DJI video stream and run on-device inference.
10. Build, packaging, and asset conversion
Top-level CMake drives builds, with platform-specific CMake files under sample targets.
The tools directory supports packaging and asset conversion:
- build_dpk scripts for building payload packages
- file2c for converting binaries/config assets into C arrays used by embedded samples
doc provides code-style templates and reference schematics, which support integration on real payload hardware but are not part of the runtime path.
11. Important architectural boundary
The clearest diagram boundary is:
application logic and sample modules on one side, vendor SDK binary + platform HAL/OSAL + board/RTOS or Linux services in the middle, and DJI aircraft/payload interface on the other side.
The repo is fundamentally a payload-integration SDK: most complexity is in adapting diverse hardware platforms to a shared DJI feature API.
Main entry points: include SDK APIs · sample_c/module_sample C Modules · common Linux HAL · sample_c++/module_sample C++ Modules
Components 24
Payload SDK
Vendor payload SDK distribution with samples, platform layers, and tooling.
- Payload SDK · DJI Payload SDK package for host-side payload integration.
SDK
Public API surface and prebuilt DJI payload runtime libraries.
C Samples
Embedded-oriented sample applications and feature modules.
- C Modules · Capability-based C sample applications, including camera emulation, FC subscription, data transmission, MOP, upgrade, widget, waypoint, perception, and payload control.
samples/sample_c/module_sample
C++ Samples
Module samples built around DJI SDK subsystems.
- C++ Modules · C++ module samples for camera manager, flight controller, gimbal, HMS, liveview, perception, positioning, and widget manager.
samples/sample_c++/module_sample - Liveview · Stream decoding, camera image handling, and on-device object detection using shipped model assets.
samples/sample_c++/module_sample/liveview - Camera Manager · Camera manager integration sample.
samples/sample_c++/module_sample/camera_manager - Flight Controller · Flight control command and telemetry sample.
samples/sample_c++/module_sample/flight_controller - Gimbal · Gimbal control sample.
samples/sample_c++/module_sample/gimbal - HMS Manager · Health and message reporting sample.
samples/sample_c++/module_sample/hms_manager - Widget Manager · Payload widget and interaction sample.
samples/sample_c++/module_sample/widget_manager
Platform Support
Linux and RTOS abstraction layers, HALs, and board support.
- Linux Glue · Shared Linux OSAL plus platform-specific host integration for DJI samples.
samples/sample_c/platform/linux - RTOS Stack · FreeRTOS-based board support, HAL drivers, bootloader, and upgrade path for MCU-class payloads.
samples/sample_c/platform/rtos_freertos - Linux HAL · Network, UART, USB bulk, and OS services used by Linux targets.
samples/sample_c/platform/linux/common - RTOS HAL · UART, I2C, USB, LEDs, CAN, PWM, flash, and PPS support for RTOS boards.
samples/sample_c/platform/rtos_freertos/gd32f527_development_board - Bootloader · Standalone bootloader and YMODEM-based upgrade path for RTOS targets.
samples/sample_c/platform/rtos_freertos/gd32f527_development_board/bootloader - Manifold 2 · Linux sample target with network, UART, and USB bulk integration.
samples/sample_c/platform/linux/manifold2 - Manifold 3 · Linux sample target centered on USB bulk payload connectivity.
samples/sample_c/platform/linux/manifold3 - Jetson · NVIDIA Jetson sample target with host connectivity and device I/O.
samples/sample_c/platform/linux/nvidia_jetson - Raspberry Pi · Raspberry Pi sample target with network, UART, USB, and I2C support.
samples/sample_c/platform/linux/raspberry_pi - Board App · FreeRTOS payload application entrypoint and board-specific runtime logic.
samples/sample_c/platform/rtos_freertos/gd32f527_development_board/application
Tools & Docs
Build helpers, packaging scripts, and reference documentation.
- DPK Build · Scripts for building payload packages.
tools/build_dpk - File to C · Converts binaries and config assets into embedded C arrays.
tools/file2c - Reference Docs · Code-style templates and reference payload schematics.
doc
Connections 27
- Payload SDK → SDK APIs: exposes · Public SDK APIs define the integration surface.
- Payload SDK → SDK libs: ships · Prebuilt runtime libraries implement the SDK.
- C Modules → SDK APIs: calls · C samples use the DJI feature APIs.
- C++ Modules → SDK APIs: calls · C++ samples use the DJI feature APIs.
- C Modules → Linux Glue: runs on · Most C samples depend on Linux or RTOS platform glue.
- C Modules → RTOS Stack: runs on · Embedded samples depend on RTOS board support.
- C++ Modules → Linux Glue: runs on · C++ samples rely on Linux host services.
- Linux Glue → Linux HAL: contains · Linux OSAL and HAL bridge to sockets, files, serial, and USB.
- RTOS Stack → RTOS HAL: contains · RTOS board support provides MCU peripheral drivers.
- RTOS Stack → Bootloader: includes · Firmware update is split into application and bootloader.
- Manifold 2 → Linux HAL: uses · Manifold 2 target bindings.
- Manifold 3 → Linux HAL: uses · Manifold 3 target bindings.
- Jetson → Linux HAL: uses · Jetson target bindings.
- Raspberry Pi → Linux HAL: uses · Raspberry Pi target bindings.
- Board App → RTOS HAL: uses · Board application is built on HAL and BSP drivers.
- Board App → Bootloader: updates via · Application delegates firmware update handling to the bootloader path.
- Liveview → SDK APIs: uses · Liveview sample drives live video and media APIs.
- Liveview → Linux Glue: requires · Liveview depends on host decoding and OS services.
- Camera Manager → SDK APIs: uses · Camera manager sample exercises imaging APIs.
- Flight Controller → SDK APIs: uses · Flight controller sample exercises control and telemetry APIs.
- Gimbal → SDK APIs: uses · Gimbal sample exercises motion control APIs.
- HMS Manager → SDK APIs: uses · HMS sample exercises health/status APIs.
- Widget Manager → SDK APIs: uses · Widget manager sample exercises payload UI APIs.
- C Modules → DPK Build: built with · C samples are packaged with repository build scripts.
- C Modules → File to C: uses · Embedded C samples convert assets into compiled arrays.
- C++ Modules → DPK Build: built with · C++ samples share the same build and packaging boundary.
- C++ Modules → Reference Docs: guided by · Reference schematics and templates support integration work.