菜单

📚T-JSON跨平台网络通信协议

下载

©️版权声明
本协议是 瞳赋® Tofu Intelligence® 独家财产,受版权法和条约的保护,未经授权不得转载或复制他用。
协议提供对接测试客户端与源码,方便客户快速应用。

0.测试程序与源码下载

TJSON测试软件说明:

部分功能说明:
🟢图像抓拍: 点选“显示抓拍图像”,并启动“抓拍上传开”后抓拍图像存储到软件所在目录中,如下图所示。

🟢保存数据: 开始接收/发送数据后点选“保存数据”,数据将保存到软件所在目标 log文件夹下,可查看数据发送/接收的16进制原始数据。

🟢数据透传: 透传数据包括PELCO_D,VISCA,VISCA_IR三种模式,分别对应云台、可见光相机、热红外相机通道,详细说明请查看本页4.2.2章节。
支持数据循环发送。

1. 必读

本协议规定了AI端与操控端、AI端与吊舱之间的通信方式和协议。

⚠️注意,本协议中所指的吊舱专指Tofu型号吊舱,其他吊舱与云台不适用PV协议通信方式。

本协议适用于任何操作系统,可用于客户端软件的二次开发。

(非吊舱用户请忽略此部分🔻)
AI端在运行过程中直接控制云台和镜头。AI端作为服务器端(Server端),吊舱与镜头控制端作为客户端(Client端),AI端口号为8090。采用PelcoD协议与VISCA协议,以下简称PV协议。控制与查询周期默认为200ms一次。若您使用云台相机,此部分可忽略,只需要使用JSON协议即可,网络通信全部基于TCP/IP方式。
(非吊舱用户请忽略此部分🔺)

操控端中支持AI端的算法模式切换与参数配置;识别、跟踪过程中信息接收;云台与镜头的手动控制,AI端作为服务器端(Server端),操控端作为客户端(Client端),AI端口号为8089。采用JSON协议。所有JSON数据上下帧间隔不得小于100毫秒

AI端采用 RTSP 协议传输视频,视频默认采用H.264编码(可通过T-JSON协议控制修改为H.265),端口号为554。当AI相机节点开机时即启动RTSP Server等待视频点播。操控终端需要查看视频时,通过 RTSP URL 的形式点播视频。T-JSON协议不包含视频流部分,视频流解析请自行使用RTSP视频解析方式,暂不提供此部分相关代码与技术支持。

网络链路中,所有连接到AI端的设备都必须遵循心跳帧规则。

2. PV通信协议

(非吊舱用户请忽略此节)

AI端与吊舱采用PV协议通信,其中云台运动与查询相关指令采用PelcoD协议,镜头变倍、聚焦、查询相关指令采用VISCA协议。

通信不包含其他指令之外的数据,直接通过网络端口发送接收即可。此处列举几个常用协议指令,完整协议请参考 PelcoD云台控制与VISCA镜头控制协议文档。若您使用云台相机,此部分可忽略,只需要使用JSON协议即可。

3. T-JSON通信协议

T-JSON通信协议适用于客户端与AI端之间的通信,用于控制和配置AI端,获取AI端的状态消息,以及手动控制云台和镜头,获取目标截图。
T-JSON协议分为JSON指令协议图像抓拍协议,均通过同一个8089端口进行通信。

以下数据帧说明中,Tofu产品代表服务器端,客户端软件/平台软件代表客户端。


🟢 JSON指令 协议格式:

标识码1 标识码2 帧类型 帧长度 帧内容
1Byte 1Byte 1Byte 4Byte N
0xEC 0x91 见帧类型表 帧内容长度N JSON

帧类型表:

帧类型 类型名 格式
0x01(设备到客户端) 状态帧 JSON
0x03(客户端到设备) 控制指令 JSON
0x04(设备到客户端) 图像抓拍,协议见图像抓拍协议格式 JPEG Socket
0x05(客户端到设备) 图像信息查询 JSON
0x06(客户端到设备) 设置目标检测区域 JSON
0x07(客户端到设备) 设置显示模式 JSON
0x08(客户端到设备) 设置算法模型 JSON
0x09(客户端到设备) 设置目标截图状态 JSON
0x11(双向) 心跳 Socket
0x12(双向) ACK Socket

🟢 图像抓拍 协议格式:

开启图像抓拍(目标截图)功能后,识别后的目标区域截图会以Socket方式与JSON同一个端口实时发送。 目标图像抓拍为每个目标单独组包,发送周期为300ms。例如,图像中有3个目标,协议将发送三个独立的Socket包。

标识码1 标识码2 帧类型 帧长度 位置信息 帧内容 帧校验 帧尾标识1 帧尾标识2
1Byte 1Byte 1Byte 4Byte 8Byte N Byte 1Byte 1Byte 1Byte
0xEB 0x92 0x04 JPEG Size Location JPEG Sum 0xFB 0x92

位置信息: 截取图像在原始图像中的坐标位置,其中按顺序包括左X-coordinate(2Byte)、上Y-coordinate(2Byte),截取图像的宽Width(2Byte)、高Height(2Byte)。Coordinate坐标原点在画面的左上角,为(X=1,Y=1)。
帧长度: JPEG图像数据的Byte数量,对应上表的 N。
帧校验: 0xEB+0x92+0x04+帧长度 的7Byte 合校验。


4. JSON帧内容说明

4.1 服务器端到客户端帧内容

AI运行过程信息推送包括算法信息设备状态信息

4.1.1 算法信息

算法信息数据结构说明:

Key Disp. Value Type
ControlType 控制类型 AIInfo String
WorkMode 工作模式 0x00:关闭AI
0x01:识别
0x02:自动跟踪
0x03:点选跟踪
0x04:波门/框选跟踪🪄
Int
ObjectCount 目标总数 N Int
Object 目标信息 见下表 JSON

🪄
波门跟踪是固定尺寸大小正方形区域的框选跟踪。


Object格式说明:

Key Disp. Value Type
Class 目标类型🪄

0xA1:人/飞机,0xA2:车/直升机,

0xA3:船/鸟,0xA4:无人机,

0xB1:跟踪正常,

0xB2:跟踪丢失

Int
Point 位置信息✏️

Left:左X,

Top:上Y,

Right:右X,

Bottom:下Y

Int
Distance 距离信息 N Double

🪄
目标类型最多为4个类,编号对应名称根据选择的模型变化。

✏️
Point目标框的位置,左上角为零点0,0。
取值范围:
可见光:Left、Right 0-1919;Top、Bottom 0-1079。
热红外:Left、Right 0-719;Top、Bottom 0-575。
当跟踪状态时只推送跟踪目标的坐标,当跟踪丢失时坐标均为0,0,0,0。

⚠️非所有设备具备Distacne信息,若有,单位为 m(米)。

JSON示例:

JSON 复制代码
{
  "ControlType": "AIInfo", // 控制类型,表示这是一个 AI 算法信息推送
  "WorkMode": 1,           // 工作模式,0x01 表示识别模式
  "ObjectCount": 2,        // 目标总数,表示当前检测到的目标数量

  "Object": {              // 目标信息集合,每个目标用一个唯一的 ID 标识
    "01": {                // 目标 ID 为 "01"
      "Class": 161,        // 目标类型,0xA1 表示人
      "Points": {          // 目标在图像中的位置信息(坐标框)
        "Left": 100,       // 目标框左上角的 X 坐标
        "Top": 100,        // 目标框左上角的 Y 坐标
        "Right": 200,      // 目标框右下角的 X 坐标
        "Bottom": 200      // 目标框右下角的 Y 坐标
      },
      "Distance": 1066.0   // 目标距离(单位:米)
    },
    "02": {                // 目标 ID 为 "02"
      "Class": 162,        // 目标类型,0xA2 表示车
      "Points": {          // 目标在图像中的位置信息(坐标框)
        "Left": 300,       // 目标框左上角的 X 坐标
        "Top": 100,        // 目标框左上角的 Y 坐标
        "Right": 400,      // 目标框右下角的 X 坐标
        "Bottom": 200      // 目标框右下角的 Y 坐标
      },
      "Distance": 1182.0   // 目标距离(单位:米)
    }
  }
}

在跟踪过程中JSON示例:

JSON 复制代码
{
  "ControlType": "AIInfo", // 控制类型,表示这是一个 AI 算法信息推送
  "WorkMode": 2,           // 工作模式,0x02 表示自动跟踪模式
  "ObjectCount": 1,        // 目标总数,表示当前检测到的目标数量为 1
  
  "Object": {              // 目标信息集合,包含每个检测到的目标的详细信息
    "01": {                // 目标 ID 为 "01",表示第一个目标
      "Class": 177,        // 目标类型,0xB1 表示跟踪正常(具体分类需根据实际定义)
      "Points": {          // 目标在图像中的位置信息(坐标框)
        "Left": 220,       // 目标框左上角的 X 坐标
        "Top": 450,        // 目标框左上角的 Y 坐标
        "Right": 250,      // 目标框右下角的 X 坐标
        "Bottom": 490      // 目标框右下角的 Y 坐标
      },
      "Distance": 1055.0   // 目标距离(单位:米),表示目标距离相机的距离
    }
  }
}

4.1.2 设备状态信息

设备状态信息数据结构说明:

Key Name Value Type Disp.
ControlType 控制类型 ZoomInfo String
ZoomInfo 镜头倍率 精确到小数点后一位/两位 Double
ZoomInfoIR 热红外镜头倍率 精确到小数点后一位/两位 Double 非双光输入设备,无此项
PTZInfoH 云台横向角度 精确到小数点后一位/两位 Double 需串口服务器
PTZInfoV 云台垂直角度 精确到小数点后一位/两位 Double 需串口服务器
LaserRange 测距 精确到小数点后一位 Double 部分设备支持
CamShowMode 相机显示模式 0:彩色;1:黑白 Int 部分设备支持
Latitude 纬度 精确到小数点后六位 String 部分设备支持
Longitude 经度 精确到小数点后六位 String 部分设备支持
Height 测距 精确到小数点后一位 Double 部分设备支持

JSON示例:

JSON 复制代码
{
  "ControlType": "ZoomInfo", // 控制类型,表示这是一个设备状态信息推送
  "ZoomInfo": 3.6,           // 镜头倍率
  "ZoomInfoIR": 1.5,         // 热红外镜头倍率,非双光输入无此项
  "PTZInfoH": -50.3,         // 云台横向角度
  "PTZInfoV": 16.4,          // 云台垂直角度
  "LaserRange": 810.0,       // 测距信息,表示激光测距的结果,单位为米
  "CamShowMode": 0,          // 相机显示模式,0 表示彩色模式
  "Latitude": "39.836502N",  // 纬度信息,N 表示北纬
  "Longitude": "116.287451E",// 经度信息,E 表示东经
  "Height": 888.0            // 高度信息
}

4.2 客户端到服务器端帧内容

包含工作模式配置与数据透传。

4.2.1 工作模式

工作模式配置指令格式:

Key Disp. Value Type
ControlType 控制类型 SetWorkMode String
SetWorkMode 工作模式

0x00:关闭AI

0x01:识别

0x02:自动跟踪

0x03:点选跟踪

0x04:波门/框选跟踪

0x05:自动变焦开🪄

0x06:自动变焦关

Int
P2Track 配置 下表说明 Int

🪄
自动变焦功能是指跟踪过程中随目标大小自动变焦的功能。

P2Track配置在点选跟踪、波门/框选跟踪时需要。具体说明如下表。

Key Disp. Value Type
Center 🪄中心点 X:横坐标,Y:纵坐标 Int
Distance 搜索范围/区域大小 N Int
DistanceX 搜索范围/区域大小 N Int
DistanceY 搜索范围/区域大小 N Int

🪄
画面左上为1,1源点;Center对应目标中心点坐标。
点选跟踪模式下默认Distacne=30;
波门/框选跟踪模式下可使用Distance(跟踪框为正方形)或DistanceX/Y(跟踪框为任意大小长方形)。

JSON示例:

JSON 复制代码
{
  "ControlType": "SetWorkMode", // 控制类型
  "SetWorkMode": 1             // 设置的工作模式,0x01 表示识别模式
}

P2Track信息仅在点选跟踪模式与波门跟踪模式下输入,点选跟踪需要提供点击的坐标,Distance默认用30,如果坐标在识别到的目标区域内即会锁定跟踪。

波门跟踪提供的是中心坐标与跟踪框宽度(高度)信息。

点选跟踪JSON示例:

JSON 复制代码
{
  "ControlType": "SetWorkMode", // 控制类型
  "SetWorkMode": 3,             // 设置的工作模式,0x03 表示点选跟踪模式
  "P2Track": {                  // 点选跟踪配置
    "Center": {                 // 目标中心点的坐标
      "X": 310,                 // 目标中心点的 X 坐标
      "Y": 660                  // 目标中心点的 Y 坐标
    },
    "Distance": 64              // 搜索范围,表示以中心点为中心的搜索半径
  }
}

框选跟踪JSON示例:

JSON 复制代码
{
  "ControlType": "SetWorkMode", // 控制类型
  "SetWorkMode": 4,             // 设置的工作模式,0x04 表示波门/框选跟踪模式
  "P2Track": {                  // 波门/框选跟踪配置
    "Center": {                 // 目标中心点的坐标
      "X": 240,                 // 目标中心点的 X 坐标
      "Y": 330                  // 目标中心点的 Y 坐标
    },
    "DistanceX": 36,            // 跟踪区域的宽度
    "DistanceY": 28             // 跟踪区域的高度
  }
}

4.2.2 数据透传

数据透传指令格式:

Key Disp. Value Type
ControlType 控制类型 SerialControl String
SerialType 串口选择🪄

PELCO_D

VISCA

VISCAIR✏️

String
SerialData 数据

Lens:数据长度

Data:数据内容

Int

String

🪄
可见光设备中SerialType选择PELCO_D则数据会发送至云台,选择VISCA则数据发送至相机。

✏️
在使用Tofu提供的LIR热红外机芯时, 使用 SerialType=VISCA,
实际指令采用PELCO_D协议发送,此时注意发送的PELCO_D协议的 ID号需要改为 0x02。

双光单变焦输入的设备中 SerialType=VISCA 则给当前主画面的相机发送透传指令。
双光双变焦输入(Tofu6)的设备中,热红外机芯透传请使用 SerialType=VISCAIR。

Pelco-D与VISCA指令协议详见,[PELCO-D云台控制与VISCA镜头控制协议]
Pelco-D透传接口也可以用来发送[非标ExPelco-D高精度云台控制协议] (需云台支持)。

JSON示例:

JSON 复制代码
{
  "ControlType": "SerialControl", // 控制类型,表示这是一条用于串口通信控制的指令
  "SerialType": "PELCO_D",        // 串口协议类型,指定使用 PELCO-D 协议
  "SerialData": {                 // 串口数据内容
    "Lens": 7,                    // 数据长度,表示后续数据的字节数
    "Data": "FF01000800FF08"      // 实际发送的串口数据,以十六进制字符串表示
  }
}
/*
指令 FF01000800FF08 的具体含义是:
• 设备地址:0x01
• 操作:向上移动(Up),垂直速度为最大速度,水平速度为停止。
• 校验和:0x08
*/

JSON控制热红外镜头变倍加示例:

JSON 复制代码
{
  "ControlType": "SerialControl", // 控制类型,表示这是一条用于串口通信控制的指令
  "SerialType": "VISCA",          // 串口协议类型,指定使用 VISCA 协议
  "SerialData": {
    "Lens": 7,                    // 数据长度,表示后续数据的字节数
    "Data": "FF020020000022"      // 实际发送的串口数据,以十六进制字符串表示
    /* 
    • FF:同步字节(固定值)。
    • 02:设备地址(这里为 0x02)。
    • 00:命令类别(控制命令)。
    • 20:具体命令(变倍加操作)。
    • 22:校验和
    */
  }
}

4.3 客户端查询图像参数信息

查询帧发送格式如下,长度为7Byte。

标识码 帧类型 帧内容
0xEC 0x91 0x05 0x00 0x00 0x00 0x00

查询信息反馈:

Key Name Value Type Disp.
ControlType 控制类型 ImageSetting String
ImageSize 图像分辨率 0:1080P
1:720P
2:D1
3:1440P
int 请勿使用比实际分辨率更高的分辨率配置
ImageBit 图像码率 512~4096 Int 单位为Kb/S
ImageCode 编码格式 0:H264
1:H265
int
WorkMode 工作模式

0x00:关闭AI

0x01:识别

0x02:自动跟踪

0x03:点选跟踪

0x04:波门/框选跟踪

Int 部分设备支持输出

JSON示例:

JSON 复制代码
{
  "ControlType": "ImageSetting", // 控制类型,表示这是一条用于设置图像参数的指令
  "ImageSize": 0,                // 图像分辨率设置,0 表示 1080P (1920x1080)
  "ImageBit": 4096,              // 图像码率设置,4096 表示码率为 4096 Kb/S
  "ImageCode": 0,               // 图像编码格式设置,0 表示使用 H.264 编码
  "WorkMode": 1                  // 当前工作模式,部分设备支持查询输出
}

4.4 客户端设置目标检测区域

设置目标检测区域

Key Disp. Value Type
ControlType 控制类型 SetValue String
WarnArea 区域设置🪄

AreaItem:区域标记

AreaPoint:X、Y坐标

Int

🪄
区域设置时,画面左上角坐标为(1,1),AreaPoint最多为6个。

JSON示例:

1.设置检测区域:

JSON 复制代码
{
  "ControlType": "SetAreaDot", // 控制类型,表示这是一条用于设置目标检测区域的指令
  "WarnArea": {                // 目标检测区域的配置
    "AreaItem": 1,             // 区域标记,表示这是第一个检测区域
    "AreaPoint": [             // 区域的四个顶点坐标,定义一个矩形检测区域
      {
        "X": 120,              // 第一个顶点的 X 坐标
        "Y": 100               // 第一个顶点的 Y 坐标
      },
      {
        "X": 310,              // 第二个顶点的 X 坐标
        "Y": 100               // 第二个顶点的 Y 坐标
      },
      {
        "X": 310,              // 第三个顶点的 X 坐标
        "Y": 360               // 第三个顶点的 Y 坐标
      },
      {
        "X": 120,              // 第四个顶点的 X 坐标
        "Y": 360               // 第四个顶点的 Y 坐标
      }
    ]
  }
}

2.取消检测区域:

JSON 复制代码
{
  "ControlType": "SetAreaDot", // 控制类型,表示这是一条用于设置或取消目标检测区域的指令
  "WarnArea": {                // 目标检测区域的配置
    "AreaItem": 0              // 区域标记,0 表示取消所有检测区域
  }
}

4.5 客户端设置显示模式

Key Name Value Type Disp.
ControlType 控制类型 PipShowSetting String
PipShow 显示类型 0:大图可见光,小图红外
1:红外
2:可见光
3:融合
16:大图红外,小图可见光
Int 非双光设备不支持此协议

JSON示例:

JSON 复制代码
{
  "ControlType": "PipShowSetting", // 控制类型,表示这是一条用于设置显示模式的指令
  "PipShow": 0                    // 显示模式设置,0 表示“大图显示可见光,小图显示红外”
}

4.6 客户端设置算法模型

Key Name Value Type Disp.
ControlType 控制类型 ModelSetting String
Model 算法模型🪄 0:可见光混合模型
1:红外混合模型
2:人车识别
3:船识别
4:无人机识别
5:飞机,直升机识别
6:鸟识别
Int

🪄
1)2,3,4模型为标准提供的模型,0,1,5,6模型为非标准提供的模型,详情请咨询。
2)0,1模型为混合模型,即识别类别为4类或5类,波段与模型不匹配时自动切换成匹配的混合模型。

JSON示例:

JSON 复制代码
{
  "ControlType": "ModelSetting", // 控制类型,表示这是一条用于设置算法模型的指令
  "Model": 3                     // 算法模型设置,3 表示“船识别”模型
}

4.7 客户端设置目标截图状态

Key Name Value Type Disp
ControlType 控制类型 ImageUpload String
Upload 目标截图状态 0:目标抓拍关闭
1:目标抓拍开启
Int

JSON示例:

JSON 复制代码
{
  "ControlType": "ImageUpload", // 控制类型,表示这是一条用于设置目标截图状态的指令
  "Upload": 1                   // 目标截图状态设置,1 表示开启目标截图功能
}

5. ACK与心跳帧

5.1 ACK帧

服务器端与客户端均要在收到帧后进行ACK回复。如果15秒内没有ACK则会服务器会强制下线客户端,客户端需重新连接服务器。
给的例子程序中客户端每5秒回一次心跳,此时客户端不用对服务器端数据回ACK也可以保持连接状态。
标识码 标识码 帧类型 帧长度 状态码
1Byte 1Byte 1Byte 4Byte 2Byte
0xEC 0x91 0x12 0x00 00 00 02 0x00 XX

状态码类型见下表。

状态码 描述
0x00 00 执行正常
0x00 01 包不完整
0x00 02 协议内容错误

5.2 心跳帧

标识码 标识码 帧类型 帧长度
1Byte 1Byte 1Byte 4Byte
0xEC 0x91 0x11 0x00 00 00 00

客户端在15秒之内需要给服务器端发送心跳帧,当服务器收到客户端心跳帧后,将在1s内回复心跳,若客户端超时未收到回复,客户端需重新发送该帧。

当服务器连续15s内未收到客户端的心跳帧时,服务器将判定客户端已自动离线,将停止数据发送和接收。

当客户端连续15s内未收到服务器回复时,应判定本次连接已被中断,需重新连接。


上一个
⚠️必读 各接口协议说明
下一个
📚T-Ser串口控制与报警协议
最近修改: 2025-09-11