大疆 Dock3 基于 PSDK 接入喊话器方案Dji-cloud-api-tool · 技术干货全面解析 Dock3 PSDK 喊话器的硬件接口、通信协议与云端集成1. 引言本周已经将大疆PSDK喊话器功能全部集成到Dji-cloud-api-tool工具中并且功能调试通过特意整理了一下对接完整方案希望能帮助到你。2. 概述本文档调研基于大疆 Dock3配套 Matrice 4D/4TD 飞行平台通过 PSDKPayload SDK接入喊话器负载设备的完整方案涵盖硬件接口、PSDK 端开发、Cloud API 通信协议、以及第三方平台集成架构。2.1 核心产品关系组件说明DJI Dock 3第三代无人机机场/机巢支持 24/7 远程无人值守作业Matrice 4D/4TDDock3 配套飞行平台提供 E-PortPSDK 扩展接口E-PortM4D 系列飞机上的负载扩展接口供电 通信一体化PSDKDJI 提供的负载设备软件开发套件当前最新 V3.12.0Cloud APIDJI 提供的云端 API基于 MQTT 实现设备-云端双向通信2.2 两种接入路径喊话器可通过以下两种方式接入 Dock3 系统路径说明适用场景路径 A官方/第三方 PSDK 喊话器直接通过 E-Port 挂载符合 PSDK 规范的喊话器硬件快速部署开箱即用路径 B自定义 PSDK 喊话器基于 PSDK 自行开发喊话器负载含硬件 固件定制需求深度集成3. 硬件层E-Port 接口规格3.1 电气规格参数规格输出电压16.8V – 25.5V飞机电池直供最大电流3A保护电流4A超过则断电保护负载电容限制≤ 500 µF超过触发短路保护PPS 引脚电压≤ 3.3V通信协议USB 2.0 / UART 3.3V TTL3.2 物理接口M4D 系列 E-Port 支持以下挂载方式E-Port 直连推荐直接连接 PSDK 负载设备SkyPort V2 转接环标准云台接口兼容旧款负载X-Port 标准云台一体化标准云台3.3 关键约束⚠️单负载限制同一时间飞机只能与一个 PSDK 负载设备通信。如果 E-Port 已被占用无法通过分线器同时接入多个负载。⚠️安装后需重新校准飞机罗盘。⚠️负载会增加飞机功耗降低飞行续航和抗风能力。4. 系统架构端到端通信链路4.1 整体架构图┌─────────────────────────────────────────────────┐ │ 第三方云端平台 │ │ (Dji-cloud-api-tool / 其他) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ 喊话器 UI │ │ TTS 引擎 │ │ 音频文件管理 │ │ │ └────┬─────┘ └────┬─────┘ └───────┬───────┘ │ │ └──────────────┼───────────────┘ │ │ │ MQTT │ └──────────────────────┼───────────────────────────┘ │ ┌────────┴────────┐ │ DJI Cloud API │ │ (MQTT Broker) │ └────────┬────────┘ │ ┌────────┴────────┐ │ DJI Dock 3 │ │ (机场/机巢) │ └────────┬────────┘ │ OcuSync/SDR ┌────────┴────────┐ │ Matrice 4D/4TD │ │ (飞行平台) │ └────────┬────────┘ │ E-Port (USB/UART) ┌────────┴────────┐ │ PSDK 喊话器 │ │ (负载设备) │ │ │ │ ┌─────────────┐ │ │ │ MCU / Linux │ │ │ │ 音频PA │ │ │ │ 扬声器 │ │ │ └─────────────┘ │ └─────────────────┘4.2 通信协议分层层次协议说明云端 → DockMQTTDock-to-Cloud Protocolservices/services_replytopicJSON 格式Dock → 飞机OcuSync / SDRDJI 私有协议透明传输飞机 → PSDKUSB_BULK / UARTPSDK 协议C 语言 APIPSDK → 扬声器I2S / I2C / GPIO硬件相关4.3 扩展架构机载计算平台中转如果需要同时接入喊话器和其他负载设备如探照灯、RTK 等推荐使用机载计算平台统一接入Matrice 4D E-Port │ └── 机载计算平台 (如品立 17F1 / NVIDIA Jetson) ├── PSDK 主程序与飞机通信 ├── 喊话器负载I2S/UART 音频输出 ├── 探照灯负载GPIO/PWM 控制 └── 其他传感器串口/SPI/I2C5. PSDK 喊话器开发硬件端5.1 PSDK 喊话器核心 APIPSDK 喊话器功能通过dji_widget.h提供的接口实现核心是注册T_DjiWidgetSpeakerHandler回调函数集回调函数方向功能GetSpeakerState飞控→负载上报播放状态、工作模式、播放模式、音量SetWorkMode飞控→负载设置 TTS / 语音工作模式SetPlayMode飞控→负载设置单次播放 / 循环播放SetVolume飞控→负载设置音量0-100StartPlay飞控→负载开始播放StopPlay飞控→负载停止播放ReceiveTtsData飞控→负载接收 TTS 文本数据ReceiveAudioData飞控→负载接收 Opus 编码的语音数据5.2 喊话器状态机SetWorkMode / SetPlayMode │ ▼ ┌──────┐ StartPlay ┌─────────┐ 播放完成 ┌──────┐ │ IDLE │────────────▶│ PLAYING │───────────▶│ IDLE │ └──────┘ └─────────┘ └──────┘ ▲ │ │ StopPlay │ └────────────────────┘工作模式DJI_WIDGET_SPEAKER_WORK_MODE_TTS— TTS 文字转语音DJI_WIDGET_SPEAKER_WORK_MODE_VOICE— 语音喊话实时/录音播放模式DJI_WIDGET_SPEAKER_PLAY_MODE_SINGLE_PLAY— 单次播放DJI_WIDGET_SPEAKER_PLAY_MODE_LOOP_PLAY— 循环播放5.3 音频参数规范参数规格采样率16 kHz声道单声道 (Mono)量化格式16 bit编码格式Opus 16 kbps单帧数据160 字节最大录音时长3 分钟导入音频格式MP3 / WAV / AAC导入音频大小限制10 MB音频文件最大数量20 个TTS 文本字符限制1000 字符汉字计为 1 字符5.4 初始化示例代码T_DjiReturnCodeSpeaker_Init(void){T_DjiReturnCode returnCode;T_DjiOsalHandler*osalHandlerDjiPlatform_GetOsalHandler();// 1. 注册回调函数s_speakerHandler.GetSpeakerStateSpeaker_GetState;s_speakerHandler.SetWorkModeSpeaker_SetWorkMode;s_speakerHandler.SetPlayModeSpeaker_SetPlayMode;s_speakerHandler.SetVolumeSpeaker_SetVolume;s_speakerHandler.StartPlaySpeaker_StartPlay;s_speakerHandler.StopPlaySpeaker_StopPlay;s_speakerHandler.ReceiveTtsDataSpeaker_ReceiveTtsData;s_speakerHandler.ReceiveAudioDataSpeaker_ReceiveAudioData;// 2. 创建互斥锁保护状态osalHandler-MutexCreate(s_speakerMutex);// 3. 注册喊话器 HandlerreturnCodeDjiWidget_RegSpeakerHandler(s_speakerHandler);// 4. 初始化状态s_speakerState.stateDJI_WIDGET_SPEAKER_STATE_IDEL;s_speakerState.workModeDJI_WIDGET_SPEAKER_WORK_MODE_VOICE;s_speakerState.playModeDJI_WIDGET_SPEAKER_PLAY_MODE_SINGLE_PLAY;// 5. 启动后台播放任务线程osalHandler-TaskCreate(speaker_task,Speaker_BackgroundTask,STACK_SIZE,NULL,s_speakerThread);returnDJI_ERROR_SYSTEM_MODULE_CODE_SUCCESS;}5.5 控件配置 JSON{main_interface:{floating_window:{is_enable:true},speaker:{is_enable_tts:true,is_enable_voice:true}}}6. 上云API通信协议云端 ↔ DockDock3 通过 MQTT 与云端通信喊话器相关 API 分为以下两组6.1 Services云端 → 设备下行指令所有下行指令发送到 topicthing/product/{gateway_sn}/services设备回复在 topicthing/product/{gateway_sn}/services_reply6.1.1 指令汇总Method功能关键参数speaker_play_volume_set设置音量psdk_index,play_volume(0–100)speaker_play_mode_set设置播放模式psdk_index,play_mode(0单次, 1循环)speaker_play_stop停止播放psdk_indexspeaker_replay重新播放psdk_indexspeaker_tts_play_startTTS 文本播放psdk_index,tts.name,tts.text,tts.md5speaker_audio_play_start音频文件播放psdk_index,file.name,file.url,file.md5,file.format6.1.2 设置音量Topic: thing/product/{gateway_sn}/services Method: speaker_play_volume_set[14:46:59]设置音量 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:9e29ce43-a386-4c89-9320-2b794225069e,data:{play_volume:54,psdk_index:2},method:speaker_play_volume_set,tid:940ec08d-a0f6-427e-a897-35539f473860,timestamp:1785307619550}响应:{bid:9e29ce43-a386-4c89-9320-2b794225069e,data:{result:0},method:speaker_play_volume_set,tid:940ec08d-a0f6-427e-a897-35539f473860,timestamp:1785307623339}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引0–3play_volumeint是音量值0–1000 为静音100 为最大音量6.1.3 设置播放模式Topic: thing/product/{gateway_sn}/services Method: speaker_play_mode_set[14:49:23]设置播放模式 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:d56d07b3-737c-423b-b38f-c7a40c535f05,data:{play_mode:1,psdk_index:2},method:speaker_play_mode_set,tid:05eb6bf9-56e2-4d0c-b453-a4e838842b2e,timestamp:1785307763832}响应:{bid:d56d07b3-737c-423b-b38f-c7a40c535f05,data:{result:0},method:speaker_play_mode_set,tid:05eb6bf9-56e2-4d0c-b453-a4e838842b2e,timestamp:1785307767493}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引0–3play_modeint是播放模式0 单次播放播完停止1 循环播放重复播放6.1.4 停止播放Topic: thing/product/{gateway_sn}/services Method: speaker_play_stop[14:53:02]停止播放 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:6920c62c-526e-4ac8-9cde-006df03a9a90,data:{psdk_index:2},method:speaker_play_stop,tid:334d3823-cde7-43fa-a007-b8df8d2eccc9,timestamp:1785307982361}响应:{bid:6920c62c-526e-4ac8-9cde-006df03a9a90,data:{result:0},method:speaker_play_stop,tid:334d3823-cde7-43fa-a007-b8df8d2eccc9,timestamp:1785307985515}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引0–3说明停止当前正在进行的 TTS 或音频文件播放对应 PSDK 端StopPlay回调。停止后喊话器回到 IDLE 状态可接收新的播放指令。6.1.5 重新播放Topic: thing/product/{gateway_sn}/services Method: speaker_replay[14:53:08]重新播放 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:92bd80d9-8601-49a3-be9a-2cce25c49f1e,data:{psdk_index:2},method:speaker_replay,tid:dbabed3e-ca8e-47f0-bd5e-5f87d958117a,timestamp:1785307988390}响应:{bid:92bd80d9-8601-49a3-be9a-2cce25c49f1e,data:{result:0},method:speaker_replay,tid:dbabed3e-ca8e-47f0-bd5e-5f87d958117a,timestamp:1785307991565}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引0–3说明重新播放上一次通过speaker_tts_play_start或speaker_audio_play_start发送的音频内容无需重新上传音频数据。6.1.6 TTS 文本播放Topic: thing/product/{gateway_sn}/services Method: speaker_tts_play_start[14:51:32]TTS文本喊话 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:dc8da309-f96e-4f17-b8b0-538c46f9d141,data:{psdk_index:2,tts:{md5:3dc5fa788a1a0f687e8350ce9019f5ac,name:测试文本喊话,text:先帝创业未半而中道崩殂今天下三分益州疲弊此诚危急存亡之秋也。然侍卫之臣不懈于内忠志之士忘身于外者盖追先帝之殊遇欲报之于陛下也。诚宜开张圣听以光先帝遗德恢弘志士之气不宜妄自菲薄引喻失义以塞忠谏之路也}},method:speaker_tts_play_start,tid:705fe0d9-4d91-48bb-b0a7-f12337c4bd9c,timestamp:1785307892599}响应:{bid:dc8da309-f96e-4f17-b8b0-538c46f9d141,data:{result:0},method:speaker_tts_play_start,tid:705fe0d9-4d91-48bb-b0a7-f12337c4bd9c,timestamp:1785307895946}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引0–3tts.nametext是文件名用于在机场侧标识tts.texttext是TTS 文本内容≤1000 字符tts.md5text是文本内容的 MD5 校验和TTS 播放进度事件上行Topic: thing/product/{gateway_sn}/events Method: speaker_tts_play_start_progress进度阶段step_keystep_key说明change_work_mode切换工作模式upload机场上传音频到 PSDKplay开始播放6.1.7 音频文件播放Topic: thing/product/{gateway_sn}/services Method: speaker_audio_play_start[17:24:49]音频文件喊话 ✅成功(result0)Topic:thing/product/8UUXXXXXXXXXXX/services下发:{bid:222cd9f1-15fa-4cc9-9b8f-f6d19a2a67d8,data:{file:{format:pcm,md5:8cfa8d06fa2707332a7a319d98d975a4,name:audio_172449,url:http://127.0.0.1:8888/file/get?iddomp-track-binary:psdk:short_pcm_s16le.pcm},psdk_index:2},method:speaker_audio_play_start,tid:265d9172-901e-44d3-984f-2e68fc9beccd,timestamp:1785317089694}响应:{bid:222cd9f1-15fa-4cc9-9b8f-f6d19a2a67d8,data:{result:0},method:speaker_audio_play_start,tid:265d9172-901e-44d3-984f-2e68fc9beccd,timestamp:1785317088714}字段说明字段类型必填说明psdk_indexint是PSDK 负载设备索引file.nametext是文件名file.urltext是音频文件下载链接公网可访问file.md5text是音频文件的 MD5 校验和file.formatenum_string是目前仅支持pcm音频播放进度事件上行Topic: thing/product/{gateway_sn}/events Method: speaker_audio_play_start_progress进度阶段step_keystep_key说明change_work_mode切换工作模式download从云端下载音频文件到机场encoding编码 PCM 为 Opusupload机场上传音频到 PSDKplay开始播放6.2 Events设备 → 云端上行通知所有上行事件在 topicthing/product/{gateway_sn}/eventsMethod功能speaker_tts_play_start_progressTTS 播放进度通知speaker_audio_play_start_progress音频播放进度通知psdk_floating_window_textPSDK 浮窗文本推送6.2.1 播放进度事件通用结构{bid:1740d345-1d70-4a8c-b49a-feae3308d569,data:{output:{md5:8cfa8d06fa2707332a7a319d98d975a4,progress:{percent:100,step_key:change_work_mode},psdk_index:2,status:in_progress},result:0},gateway:8UUXXXXXXXXXXX,method:speaker_audio_play_start_progress,need_reply:0,tid:71b96927-504a-47f7-8485-e448bd55c5c2,timestamp:1785376016406}status 枚举值说明in_progress处理中ok播放成功6.3 完整指令时序图云端 Dock3/飞机 PSDK喊话器 │ │ │ │── speaker_tts_play_start ──▶│ │ │ │── SetWorkMode(TTS) ────────▶│ │ │── ReceiveTtsData(text) ────▶│ │ │── StartPlay ───────────────▶│ │ │ │── TTS合成 │ │ │── 音频播放 │◀── speaker_tts_play_start │ │ │ _progress(in_progress) ──│ │ │◀── speaker_tts_play_start │ │ │ _progress(ok) ───────────│ │ │ │ │ │── speaker_play_stop ───────▶│ │ │ │── StopPlay ────────────────▶│── 停止播放 │◀── services_reply(result) ──│ │ │ │ │7. 云端集成方案7.1 音频文件准备云端需要为speaker_audio_play_start指令准备机场可访问的 PCM 音频文件参数规格格式PCM未压缩原始音频采样率16 kHz声道单声道位深16 bit托管方式OSS / S3 / CDN需生成可公开下载的 URLPCM 文件生成示例FFmpeg# 将任意音频文件转换为 PSDK 喊话器兼容的 PCM 格式ffmpeg-iinput.mp3\-acodecpcm_s16le\-ar16000\-ac1\-fs16le\output.pcm# 计算 MD5用于 API 调用md5sum output.pcm7.2 OSS 上传临时凭证如果云端需要接收 PSDK UI 资源包上传结果可使用storage_config_get获取临时凭证Topic: thing/product/{gateway_sn}/requests Method: storage_config_get{bid:...,data:{module:1},gateway:4TADKAQ000002J,method:storage_config_get,tid:...,timestamp:1689911314560}返回临时 OSS 凭证有效期 3600 秒支持阿里云/AWS/MinIO。7.3 MQTT 消息处理流程1. 构造 MQTT 消息 ├── 生成唯一 tid消息追踪 ID ├── 生成唯一 bid业务追踪 ID ├── 填充 method 和 data └── 设置 timestamp毫秒级 Unix 时间戳 2. 发布到 thing/product/{gateway_sn}/services 3. 监听 thing/product/{gateway_sn}/services_reply ├── 匹配 tid → 确认指令是否被 Dock 接收 └── result0 表示成功 4. 监听 thing/product/{gateway_sn}/events ├── 匹配 method → 确认正在监听的进度事件 ├── 检查 statusin_progress / ok └── 解析 progress.percent 和 step_key8. 参考资料DJI Cloud API 文档DJI PSDK 开发教程PSDK Speaker Widget 文档DJI Dock 3 产品页Glider WR-01 Dock3 喊话器FlytBase Speaker Spotlight 集成DJI Zenmuse V1 喊话器Dji-cloud-api-tool· 专注大疆 Cloud API 开发者工具githubhttps://github.com/damon-liu/Dji-cloud-api-toolgiteehttps://gitee.com/damon123-liu/dji-cloud-api-tool如有疑问或合作意向欢迎交流探讨