# dji-sdk/payload-sdk architecture

> Architecture diagram of the GitHub repository dji-sdk/payload-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dji-sdk/payload-sdk
- Repository: https://github.com/dji-sdk/payload-sdk

## Overview

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: [`psdk_lib/include`](https://github.com/dji-sdk/payload-sdk/tree/master/psdk_lib/include) (SDK APIs), [`samples/sample_c/module_sample`](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/module_sample) (C Modules), [`samples/sample_c/platform/linux/common`](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/common) (Linux HAL), [`samples/sample_c++/module_sample`](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample) (C++ Modules)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo_root["Payload SDK"]
  node_top_level["Payload SDK<br/>distribution"]
end

subgraph group_sdk["SDK"]
  node_sdk_headers["SDK APIs<br/>headers"]
  node_sdk_binaries[("SDK libs<br/>prebuilt binaries")]
end

subgraph group_samples_c["C Samples"]
  node_sample_c_apps["C Modules<br/>sample suite"]
end

subgraph group_samples_cpp["C++ Samples"]
  node_sample_cpp_apps["C++ Modules<br/>sample suite"]
  node_cpp_liveview["Liveview<br/>media pipeline"]
  node_cpp_camera["Camera Manager<br/>module sample"]
  node_cpp_fc["Flight Controller<br/>module sample"]
  node_cpp_gimbal["Gimbal<br/>module sample"]
  node_cpp_hms["HMS Manager<br/>module sample"]
  node_cpp_widget["Widget Manager<br/>module sample"]
end

subgraph group_platform["Platform Support"]
  node_linux_glue["Linux Glue<br/>host platform layer"]
  node_rtos_glue["RTOS Stack<br/>embedded platform layer"]
  node_linux_hal["Linux HAL<br/>hardware abstraction"]
  node_rtos_hal["RTOS HAL<br/>board support"]
  node_bootloader["Bootloader<br/>firmware update"]
  node_linux_manifold2["Manifold 2<br/>linux target"]
  node_linux_manifold3["Manifold 3<br/>linux target"]
  node_linux_jetson["Jetson<br/>linux target"]
  node_linux_pi["Raspberry Pi<br/>linux target"]
  node_rtos_board_app["Board App<br/>rtos application"]
end

subgraph group_tools_docs["Tools & Docs"]
  node_tools_build["DPK Build<br/>packaging scripts"]
  node_tools_file2c["File to C<br/>asset conversion"]
  node_docs_ref["Reference Docs<br/>schematics and templates"]
end

node_top_level -->|"exposes"| node_sdk_headers
node_top_level -->|"ships"| node_sdk_binaries
node_sample_c_apps -->|"calls"| node_sdk_headers
node_sample_cpp_apps -->|"calls"| node_sdk_headers
node_sample_c_apps -->|"runs on"| node_linux_glue
node_sample_c_apps -->|"runs on"| node_rtos_glue
node_sample_cpp_apps -->|"runs on"| node_linux_glue
node_linux_glue -->|"contains"| node_linux_hal
node_rtos_glue -->|"contains"| node_rtos_hal
node_rtos_glue -->|"includes"| node_bootloader
node_linux_manifold2 -->|"uses"| node_linux_hal
node_linux_manifold3 -->|"uses"| node_linux_hal
node_linux_jetson -->|"uses"| node_linux_hal
node_linux_pi -->|"uses"| node_linux_hal
node_rtos_board_app -->|"uses"| node_rtos_hal
node_rtos_board_app -->|"updates via"| node_bootloader
node_cpp_liveview -->|"uses"| node_sdk_headers
node_cpp_liveview -->|"requires"| node_linux_glue
node_cpp_camera -->|"uses"| node_sdk_headers
node_cpp_fc -->|"uses"| node_sdk_headers
node_cpp_gimbal -->|"uses"| node_sdk_headers
node_cpp_hms -->|"uses"| node_sdk_headers
node_cpp_widget -->|"uses"| node_sdk_headers
node_sample_c_apps -->|"built with"| node_tools_build
node_sample_c_apps -->|"uses"| node_tools_file2c
node_sample_cpp_apps -->|"built with"| node_tools_build
node_sample_cpp_apps -->|"guided by"| node_docs_ref

click node_sdk_headers "https://github.com/dji-sdk/payload-sdk/tree/master/psdk_lib/include"
click node_sdk_binaries "https://github.com/dji-sdk/payload-sdk/tree/master/psdk_lib/lib"
click node_sample_c_apps "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/module_sample"
click node_sample_cpp_apps "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample"
click node_linux_glue "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux"
click node_rtos_glue "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos"
click node_linux_hal "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/common"
click node_rtos_hal "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board"
click node_bootloader "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board/bootloader"
click node_linux_manifold2 "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/manifold2"
click node_linux_manifold3 "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/manifold3"
click node_linux_jetson "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/nvidia_jetson"
click node_linux_pi "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/raspberry_pi"
click node_rtos_board_app "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board/application"
click node_cpp_liveview "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/liveview"
click node_cpp_camera "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/camera_manager"
click node_cpp_fc "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/flight_controller"
click node_cpp_gimbal "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/gimbal"
click node_cpp_hms "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/hms_manager"
click node_cpp_widget "https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/widget_manager"
click node_tools_build "https://github.com/dji-sdk/payload-sdk/tree/master/tools/build_dpk"
click node_tools_file2c "https://github.com/dji-sdk/payload-sdk/tree/master/tools/file2c"
click node_docs_ref "https://github.com/dji-sdk/payload-sdk/tree/master/doc"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_top_level toneBlue
class node_sdk_headers,node_sdk_binaries toneAmber
class node_sample_c_apps toneMint
class node_sample_cpp_apps,node_cpp_liveview,node_cpp_camera,node_cpp_fc,node_cpp_gimbal,node_cpp_hms,node_cpp_widget toneRose
class node_linux_glue,node_rtos_glue,node_linux_hal,node_rtos_hal,node_bootloader,node_linux_manifold2,node_linux_manifold3,node_linux_jetson,node_linux_pi,node_rtos_board_app toneIndigo
class node_tools_build,node_tools_file2c,node_docs_ref toneTeal
```

## Components

### Payload SDK

Vendor payload SDK distribution with samples, platform layers, and tooling.

- **Payload SDK**: distribution · DJI Payload SDK package for host-side payload integration.

### SDK

Public API surface and prebuilt DJI payload runtime libraries.

- [SDK APIs](https://github.com/dji-sdk/payload-sdk/tree/master/psdk_lib/include): headers · Feature-oriented public headers for flight control, camera, gimbal, liveview, waypoint, HMS, positioning, power, upgrade, channels, cloud, widget, and collaboration. · `psdk_lib/include`
- [SDK libs](https://github.com/dji-sdk/payload-sdk/tree/master/psdk_lib/lib): prebuilt binaries · Target-specific static libraries for host toolchains and architectures. · `psdk_lib/lib`

### C Samples

Embedded-oriented sample applications and feature modules.

- [C Modules](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/module_sample): sample suite · 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](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample): sample suite · C++ module samples for camera manager, flight controller, gimbal, HMS, liveview, perception, positioning, and widget manager. · `samples/sample_c++/module_sample`
- [Liveview](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/liveview): media pipeline · Stream decoding, camera image handling, and on-device object detection using shipped model assets. · `samples/sample_c++/module_sample/liveview`
- [Camera Manager](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/camera_manager): module sample · Camera manager integration sample. · `samples/sample_c++/module_sample/camera_manager`
- [Flight Controller](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/flight_controller): module sample · Flight control command and telemetry sample. · `samples/sample_c++/module_sample/flight_controller`
- [Gimbal](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/gimbal): module sample · Gimbal control sample. · `samples/sample_c++/module_sample/gimbal`
- [HMS Manager](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/hms_manager): module sample · Health and message reporting sample. · `samples/sample_c++/module_sample/hms_manager`
- [Widget Manager](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c++/module_sample/widget_manager): module sample · 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](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux): host platform layer · Shared Linux OSAL plus platform-specific host integration for DJI samples. · `samples/sample_c/platform/linux`
- [RTOS Stack](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos): embedded platform layer · FreeRTOS-based board support, HAL drivers, bootloader, and upgrade path for MCU-class payloads. · `samples/sample_c/platform/rtos_freertos`
- [Linux HAL](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/common): hardware abstraction · Network, UART, USB bulk, and OS services used by Linux targets. · `samples/sample_c/platform/linux/common`
- [RTOS HAL](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board): board support · UART, I2C, USB, LEDs, CAN, PWM, flash, and PPS support for RTOS boards. · `samples/sample_c/platform/rtos_freertos/gd32f527_development_board`
- [Bootloader](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board/bootloader): firmware update · Standalone bootloader and YMODEM-based upgrade path for RTOS targets. · `samples/sample_c/platform/rtos_freertos/gd32f527_development_board/bootloader`
- [Manifold 2](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/manifold2): linux target · Linux sample target with network, UART, and USB bulk integration. · `samples/sample_c/platform/linux/manifold2`
- [Manifold 3](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/manifold3): linux target · Linux sample target centered on USB bulk payload connectivity. · `samples/sample_c/platform/linux/manifold3`
- [Jetson](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/nvidia_jetson): linux target · NVIDIA Jetson sample target with host connectivity and device I/O. · `samples/sample_c/platform/linux/nvidia_jetson`
- [Raspberry Pi](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/linux/raspberry_pi): linux target · Raspberry Pi sample target with network, UART, USB, and I2C support. · `samples/sample_c/platform/linux/raspberry_pi`
- [Board App](https://github.com/dji-sdk/payload-sdk/tree/master/samples/sample_c/platform/rtos_freertos/gd32f527_development_board/application): rtos application · 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](https://github.com/dji-sdk/payload-sdk/tree/master/tools/build_dpk): packaging scripts · Scripts for building payload packages. · `tools/build_dpk`
- [File to C](https://github.com/dji-sdk/payload-sdk/tree/master/tools/file2c): asset conversion · Converts binaries and config assets into embedded C arrays. · `tools/file2c`
- [Reference Docs](https://github.com/dji-sdk/payload-sdk/tree/master/doc): schematics and templates · Code-style templates and reference payload schematics. · `doc`

## Connections

- 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.
