zgclient

v1.0.0

Published

6 months ago

地面站客户端模块

0High
0Medium
0Low

tangfei0629

zgclient SDK 使用文档

简介

zgclient 是一个基于 TypeScript 实现的地面站客户端通信 SDK，主要用于通过 WebSocket 与平台进行属性（Prop）读写、订阅等操作。SDK 封装了属性的协议、数据结构、消息收发等底层细节，便于上层业务快速集成。

目录结构

src/index.ts：SDK 入口，导出 zgclient 主对象。
src/zgclient.ts：核心通信逻辑，包括 WebSocket 连接、消息处理、属性订阅等。
src/protos/platformMessage.ts：protobuf 协议定义及数据结构。
src/PROP_ONE1E_WRITE.ts、src/PROP_ONET_WRITE.ts 等：不同平台/模块的属性读写接口。
src/common.ts：通用常量、枚举等。
src/CUSTOM_PROP_READ.ts：自定义属性的读取逻辑，包含 SSPC 配电盒状态等自定义属性的处理。

快速开始

安装

npm install zgclient

初始化 WebSocket 连接

import zgclient from 'zgclient';

// 初始化 WebSocket 连接（默认 127.0.0.1:18686）
zgclient.InitZgcWs('127.0.0.1', 18686);

关闭连接

zgclient.CloseZgcWs();

属性写入（下发）

以 src/PROP_ONE1E_WRITE.ts 为例，每个属性有对应的写入函数：

import { SET_ZGC_COMMAND_MSG } from 'zgclient/src/PROP_ONE1E_WRITE';

// 发送地面站控制指令
SET_ZGC_COMMAND_MSG(1);

每个 SET_XXX_MSG 函数会自动构造协议消息并通过 WebSocket 下发。
参数类型根据属性定义（如 number、number[]、string 等）。

不同模块属性写入示例

ONET 模块

import { SET_ZGC_POWER_MSG } from 'zgclient/src/PROP_ONET_WRITE';

// 发送动力油门指令
SET_ZGC_POWER_MSG(50); // 动力油门值为 50

ZGC 模块

import { SET_CT_CHANGE_MACHINE_MSG } from 'zgclient/src/PROP_ZGC_WRITE';

// 切换机型为 ZGONE 台架
SET_CT_CHANGE_MACHINE_MSG(0x10);

属性读取（订阅）

SDK 支持属性订阅，自动推送属性变化：

zgclient.Subscribe(
  new Set(['ZGC_COMMAND']), // 订阅属性名集合
  false,                    // 是否清空历史
  200,                      // 轮询间隔(ms)
  (maps) => {
    // maps: Map<string, any>，属性名到最新值的映射
    console.log(maps);
  }
);

取消订阅：

zgclient.UnSubscribe(handler); // handler 为 Subscribe 返回的定时器

订阅告警信息

zgclient.SubscribeAlarm(
  new Set(['CT_ALARM']), // 订阅告警属性名集合
  false,                 // 是否清空历史
  200,                   // 轮询间隔(ms)
  (maps) => {
    console.log(maps);
  }
);

取消告警订阅：

zgclient.UnSubscribeAlarm(handler); // handler 为 SubscribeAlarm 返回的定时器

按名称发送属性

zgclient.SendProp('ZGC_COMMAND', 1);

自动查找属性类型并封装协议。

协议说明

协议结构定义见 src/protos/platformMessage.ts 和 src/protos/platformMessage.proto。主要结构：

PlatformMessage：顶层消息体，包含 cmd、config、value 等字段。
PlatformPropConfig：属性配置，包含属性名、访问权限等。
PlatformValue：属性值，支持多种类型（int32、float、string、数组等）。
PlatformCmd：命令类型（GET_PROP、SET_PROP、SUBSCRIBE_PROP 等）。
ValueType：值类型枚举。

属性定义与扩展

属性枚举、读写接口分模块维护（如 ONE1E、ONET、T6T、T6B、CUSTOM 等）。
每个属性有详细的元数据（名称、类型、说明、映射等），可通过各自的 MAP 查询。
新增属性需在对应的 ENUMS、READ/WRITE 文件中注册。

自定义属性处理（以 `src/CUSTOM_PROP_READ.ts` 为例）

该文件处理了 SSPC 配电盒状态相关的自定义属性。通过定义映射关系和使用 RxJS 操作符，对属性值进行处理和转换。例如：

const SSPC_SYSTEM_STATE_1_MAPPING = new Map<any, any>();
SSPC_SYSTEM_STATE_1_MAPPING.set(0, '关断');
SSPC_SYSTEM_STATE_1_MAPPING.set(1, '开通');

const SSPC_SYSTEM_STATE_SUB = new Subject<any>();
const SSPC_SYSTEM_STATE_OBS = SSPC_SYSTEM_STATE_SUB.asObservable().pipe(
    distinctUntilChanged(),
    map(m => {
        const ch = m[0];
        m[1] = SSPC_SYSTEM_STATE_MAPPING.get(1)?.get(m[1])
        m[2] = SSPC_SYSTEM_STATE_MAPPING.get(2)?.get(m[2])
        m[3] = Number(m[3]).toFixed(2.0);
        m[4] = Number(m[4]).toFixed(2.0);
        for (const i in m) {
            const key = `SSPC_SYSTEM_STATE_${ch}_${i}`;
            CUSTOM_SUBJECT_MAP.get(key)?.next(m[i])
        }
        return m;
    })
);

典型用法举例

1. 写入属性

import { SET_CDU_COMMAND_MSG } from 'zgclient/src/PROP_ONE1E_WRITE';

SET_CDU_COMMAND_MSG(1); // 发送一键起飞指令

2. 订阅属性

zgclient.Subscribe(
  new Set(['CDU_COMMAND']),
  false,
  200,
  (maps) => {
    console.log('CDU_COMMAND:', maps.get('CDU_COMMAND'));
  }
);

3. 发送自定义属性

zgclient.SendProp('CDU_COMMAND', 1);

4. 处理自定义属性（SSPC 配电盒状态）

import { CUSTOM_OBSERVABLE_MAP } from 'zgclient/src/CUSTOM_PROP_READ';

CUSTOM_OBSERVABLE_MAP.get('SSPC_SYSTEM_STATE')?.subscribe((value) => {
    console.log('SSPC_SYSTEM_STATE:', value);
});

进阶说明

支持多平台、多模块属性管理，属性名、类型、说明等均自动生成。
支持 protobuf 二进制高效通信。
支持属性值映射、枚举、批量订阅等高级功能。
详细属性列表及说明请参考各模块的 *_WRITE.ts 和 *_READ.ts 文件。

参考

如需详细属性列表或扩展用法，请查阅源码或联系维护者。

常用属性列表

⚠️ 由于完整属性定义分布在各平台/模块的 PROP_XXX_WRITE.ts 和 PROP_XXX_READ.ts 文件，以下为常见属性举例。实际项目请查阅源码或相关 MAP 文件获取全部属性及详细说明。

如何查找全部属性

打开 src 目录下的 PROP_*.ts 文件。
查找所有以 export function SET_ 或 export const ...MAP 开头的定义。
结合注释和 MAP 字段，整理属性名、说明、类型、单位、映射等。

示例：属性 MAP 结构

属性定义文件中通常有如下结构：

export const PROP_ONE1E_MAP = {
  CDU_COMMAND: {
    NAME: "一键起飞指令",
    VALUE_TYPE: "number",
    UNIT: "",
    MAPPING: { 0: "停止", 1: "起飞" }
  },
  CDU_MODE: {
    NAME: "控制模式",
    VALUE_TYPE: "number",
    UNIT: "",
    MAPPING: { 0: "手动", 1: "自动" }
  },
  // ... 其他属性
}

目前页面是按照 0x100 字段进行显示在页面上的，我不想换字段，帮我写一个映射字段数据方法，传入 0x100 类型，把这个类型字段的数据匹配到 0x100 字段上，有一个是6个旋翼的，你只要匹配1-6就行了

不同机型电机相关字段

zgt6-ET2 电机 0x202

// 转速
T6B_ESC1_ACTUAL_SPEED_OF_MOTOR
T6B_ESC2_ACTUAL_SPEED_OF_MOTOR
T6B_ESC2_ACTUAL_SPEED_OF_MOTOR
T6B_ESC2_ACTUAL_SPEED_OF_MOTOR
T6B_ESC2_ACTUAL_SPEED_OF_MOTOR
T6B_ESC2_ACTUAL_SPEED_OF_MOTOR

// 电调芯片温度
T6B_ESC1_CONTROLLER_TEMP
T6B_ESC2_CONTROLLER_TEMP
T6B_ESC3_CONTROLLER_TEMP
T6B_ESC4_CONTROLLER_TEMP
T6B_ESC5_CONTROLLER_TEMP
T6B_ESC6_CONTROLLER_TEMP

// 电机温度
T6B_ESC1_MOTOR_TEMP
T6B_ESC2_MOTOR_TEMP
T6B_ESC3_MOTOR_TEMP
T6B_ESC4_MOTOR_TEMP
T6B_ESC5_MOTOR_TEMP
T6B_ESC6_MOTOR_TEMP

// 母线输入电压
T6B_ESC1_BUS_VOLTAGE
T6B_ESC2_BUS_VOLTAGE
T6B_ESC3_BUS_VOLTAGE
T6B_ESC4_BUS_VOLTAGE
T6B_ESC5_BUS_VOLTAGE
T6B_ESC6_BUS_VOLTAGE

// 母线输入电流
T6B_ESC1_BUS_CURRENT
T6B_ESC2_BUS_CURRENT
T6B_ESC3_BUS_CURRENT
T6B_ESC4_BUS_CURRENT
T6B_ESC5_BUS_CURRENT
T6B_ESC6_BUS_CURRENT

zgone-ET0 电机 0x100

// 转速
FCU_ESC1_OUTPUT_FREQUENCY_EXP
FCU_ESC2_OUTPUT_FREQUENCY_EXP
FCU_ESC3_OUTPUT_FREQUENCY_EXP
FCU_ESC4_OUTPUT_FREQUENCY_EXP
FCU_ESC5_OUTPUT_FREQUENCY_EXP
FCU_ESC6_OUTPUT_FREQUENCY_EXP
FCU_ESC7_OUTPUT_FREQUENCY_EXP
FCU_ESC8_OUTPUT_FREQUENCY_EXP
FCU_ESC9_OUTPUT_FREQUENCY_EXP
FCU_ESC10_OUTPUT_FREQUENCY_EXP
FCU_ESC11_OUTPUT_FREQUENCY_EXP
FCU_ESC12_OUTPUT_FREQUENCY_EXP

// 电调芯片温度
FCU_ESC1_CHIP_TEMP
FCU_ESC2_CHIP_TEMP
FCU_ESC3_CHIP_TEMP
FCU_ESC4_CHIP_TEMP
FCU_ESC5_CHIP_TEMP
FCU_ESC6_CHIP_TEMP
FCU_ESC7_CHIP_TEMP
FCU_ESC8_CHIP_TEMP
FCU_ESC9_CHIP_TEMP
FCU_ESC10_CHIP_TEMP
FCU_ESC11_CHIP_TEMP
FCU_ESC12_CHIP_TEMP

// 电机温度
FCU_ESC1_MOTOR_TEMP
FCU_ESC2_MOTOR_TEMP
FCU_ESC3_MOTOR_TEMP
FCU_ESC4_MOTOR_TEMP
FCU_ESC5_MOTOR_TEMP
FCU_ESC6_MOTOR_TEMP
FCU_ESC7_MOTOR_TEMP
FCU_ESC8_MOTOR_TEMP
FCU_ESC9_MOTOR_TEMP
FCU_ESC10_MOTOR_TEMP
FCU_ESC11_MOTOR_TEMP
FCU_ESC12_MOTOR_TEMP

// 母线输入电压
FCU_ESC1_INPUT_VOLTAGE
FCU_ESC2_INPUT_VOLTAGE
FCU_ESC3_INPUT_VOLTAGE
FCU_ESC4_INPUT_VOLTAGE
FCU_ESC5_INPUT_VOLTAGE
FCU_ESC6_INPUT_VOLTAGE
FCU_ESC7_INPUT_VOLTAGE
FCU_ESC8_INPUT_VOLTAGE
FCU_ESC9_INPUT_VOLTAGE
FCU_ESC10_INPUT_VOLTAGE
FCU_ESC11_INPUT_VOLTAGE
FCU_ESC12_INPUT_VOLTAGE

// 母线输入电流
FCU_ESC1_INPUT_CURRENT
FCU_ESC2_INPUT_CURRENT
FCU_ESC3_INPUT_CURRENT
FCU_ESC4_INPUT_CURRENT
FCU_ESC5_INPUT_CURRENT
FCU_ESC6_INPUT_CURRENT
FCU_ESC7_INPUT_CURRENT
FCU_ESC8_INPUT_CURRENT
FCU_ESC9_INPUT_CURRENT
FCU_ESC10_INPUT_CURRENT
FCU_ESC11_INPUT_CURRENT
FCU_ESC12_INPUT_CURRENT

zgone-ET1 电机 0x101

// 转速
ESC1_MOTOR_SPEED
ESC2_MOTOR_SPEED
ESC3_MOTOR_SPEED
ESC4_MOTOR_SPEED
ESC5_MOTOR_SPEED
ESC6_MOTOR_SPEED
ESC7_MOTOR_SPEED
ESC8_MOTOR_SPEED
ESC9_MOTOR_SPEED
ESC10_MOTOR_SPEED
ESC11_MOTOR_SPEED
ESC12_MOTOR_SPEED

// 电调芯片温度
ESC1_MCU_TEMP
ESC2_MCU_TEMP
ESC3_MCU_TEMP
ESC4_MCU_TEMP
ESC5_MCU_TEMP
ESC6_MCU_TEMP
ESC7_MCU_TEMP
ESC8_MCU_TEMP
ESC9_MCU_TEMP
ESC10_MCU_TEMP
ESC11_MCU_TEMP
ESC12_MCU_TEMP

// 电机温度
ESC1_MOTOE_TEMP
ESC2_MOTOE_TEMP
ESC3_MOTOE_TEMP
ESC4_MOTOE_TEMP
ESC5_MOTOE_TEMP
ESC6_MOTOE_TEMP
ESC7_MOTOE_TEMP
ESC8_MOTOE_TEMP
ESC9_MOTOE_TEMP
ESC10_MOTOE_TEMP
ESC11_MOTOE_TEMP
ESC12_MOTOE_TEMP

// 母线输入电压
ESC1_BUS_VOLTAGE
ESC2_BUS_VOLTAGE
ESC3_BUS_VOLTAGE
ESC4_BUS_VOLTAGE
ESC5_BUS_VOLTAGE
ESC6_BUS_VOLTAGE
ESC7_BUS_VOLTAGE
ESC8_BUS_VOLTAGE
ESC9_BUS_VOLTAGE
ESC10_BUS_VOLTAGE
ESC11_BUS_VOLTAGE
ESC12_BUS_VOLTAGE

// 母线输入电流
ESC1_BUS_CURRENT
ESC2_BUS_CURRENT
ESC3_BUS_CURRENT
ESC4_BUS_CURRENT
ESC5_BUS_CURRENT
ESC6_BUS_CURRENT
ESC7_BUS_CURRENT
ESC8_BUS_CURRENT
ESC9_BUS_CURRENT
ESC10_BUS_CURRENT
ESC11_BUS_CURRENT
ESC12_BUS_CURRENT