Appearance
1 API列表
1.smaReceivePilotData
2.smaReceivePayloadData
3.smaStartProcess
4.smaStopProcess
5.smaUpdateFuncMask
6.smaGetMediaList
7.smaGetMediaInfo
8.smaGetServerConfig
9.smaGetAIRelated
10.smaSetServerConfig
11.smaUploadAIModelFile
12.smaAddAnnotationElements
13.smaDeleteAnnotationElements
14.smaUploadAIOnnxFile
15.smaStartOnnxtoEngine
16.smaGetOnnxtoEnginePercent
17.smaRequestAiAssistTrack
18.smaStartMultiProcess
19.smaSaveSnapShot
20.smaUpdateArTowerHeight
21.smaUpdateAIPosCor
22.smaSetSeekPercent
23.smaSetVideoPause
24.smaPlaybackMarkRecord
25.pushStreamUrl
26.distributeCfg
2 返回约定
返回值统一为json字符串,样式如下
json
{
"code":int,
"msg":string,
"id":string
}其中,id为处理的视频流任务唯一ID,该ID会在调用API"SmastartProcess"时返回。Code的含义如下:
java
{
NotFound = -500,//未找到
Exception = -400,//代码抛异常
InvalidArgs = -300,//参数不合法
SqlFailed = -200,//sql执行失败
AuthFailed = -100,//鉴权失败
OtherFailed = -1,//业务代码执行失败,
Success = 0//执行成功
}msg为结果信息,API使用者只需要显示msg即可。
3 调用示意图

4 API详解
前言
协议文档里的api接口都是rpc接口,以下所有api接口对外均提供http、mqtt接口,规则如下:
http调用:
url为:http://ip:port/index/api/sma/接口名;POST方式
只有paramsStr,则放到body中以json传输;
若还有其它文件如ar_camera等,则paramsStr和其它文件都以form-data传输,json形式的参数列表key为param_json。
边应用平台上云http消息体里新增target(目标站点)、pilot_id(飞控ID)字段,都是非必填,字段详细请看边应用平台上云规范文档
示例:发给地面边应用平台消息 http://127.0.0.1:8102/index/api/sma/smaGetMediaList
body里
plain
{
"secret": "035c73f7-bb6b-4889-a715-d9eb2d1925ee",
"target": "hdsjdskj", //目标站点(地面站点编号),非必填
"pilot_id": "123456" //飞控ID,非必填
}该http回复也是调用hook api,ground_edge_response这个字段代码的就是地面边应用给云边应用的回复,消息体里新增from(接口名)、interface(接口名)、pilot_id字段(使用的飞控ID),都是非必填
mqtt调用:
topic为:/joeap/sma/指控终端/站点编号/cmd;
指控终端id:user_id,给各指控终端分配的id
站点编号:给各边应用平台分配的GUID编号,如3FFBCE3D-5BB2-A800-FA8E-586770BF9793
若只有paramsStr,则按照paramsStr示例正常传输;
若还有其它如ar的kml等,则在paramsStr中增加url字段"ar_vector_url"和"ar_camera_url",用来http下载ar的kml文件和camera文件。
mqtt消息体定义
| { interface:接口名 type:request/response,请求还是回复 target:目标站点 from:源站点 pilot_id:使用的飞控ID message://实际的消息体 { ...... } } |
|---|
smaReceivePilotData
描述:接收机载元数据
参数:如“metadata-pilot.txt”所示
smaReceivePayloadData
描述: 接收机载元数据
参数:如“metadata-payload.txt”
smaStartProcess
描述:开始任务
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| ar_file | std::map<std::string, std::string> | 以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空 |
paramsStr示例如下:
json
{
"secret":string,//鉴权码
"pull_url":string, //拉流地址
"push_url":string, //推流地址
"func_mask":string, //功能掩码
}功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能
cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000ar_file示例如下:
| Key | Value |
|---|---|
| ar_vector | 矢量文件kml或kmz |
| ar_camera | 相机的config文件 |
注(本文中所有接口以此为例)
http调用:
url为:http://127.0.0.1:8080/index/api/sma/smaReceivePilotData;只有paramsStr,则放到body中以json传输,若还有其它文件如ar_camera等,则paramsStr和其它文件都以form-data传输,json形式的参数列表key为param_json。
mqtt调用:
topic为:/index/api/sma/smaReceivePilotData;若只有paramsStr,则按照paramsStr示例正常传输;若还有其它如ar的kml等,则在paramsStr中增加url字段"ar_vector_url"和"ar_camera_url",用来http下载ar的kml文件和camera文件。
若是微服务之间,通过主服务传递调用rpc接口,则将paramsStr和ar_file组合成为一个json传递,如下所示:
json
{
"secret":string,//鉴权码
"pull_url":string, //拉流地址
"push_url":string, //推流地址
"func_mask":string, //功能掩码
"ar_vector": string, //kml文件
"ar_camera":string //camera.config文件
}smaStartMultiProcess
描述:开始多路视频任务
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| ar_file | std::map<std::string, std::string> | 以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空 |
paramsStr示例如下:
json
{
"secret":string,//鉴权码
"pull_url":string, //高清拉流地址
"pull_sd_url":string, //标清拉流地址
"push_url":string, //高清推流地址
"push_sd_url":string, //标清推流地址
"func_mask":string, //功能掩码
}功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能
cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000ar_file示例如下:
| Key | Value |
|---|---|
| ar_vector | 矢量文件kml或kmz |
| ar_camera | 相机的config文件 |
smaStopProcess
描述:停止并删除任务
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string, //鉴权码
"id":string,//任务id,由新建任务接口返回
}smaUpdateFuncMask
描述:更新任务的功能,即功能开关
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| ar_file | std::map<std::string, std::string> | 以键值对形式存储的ar相关文件,在开启AR时才必须传,否则可以传空 |
paramsStr示例如下:
json
{
"secret":string,//鉴权码
"id":string,//任务id,由新建任务接口返回
"func_mask":string //功能掩码
}功能掩码func_mask示例如下,目前去雾、稳像未启用,使用方法:0表示不开启任何功能,1表示只开启AI,3表示开启AI和AR,功能掩码之和即为需要开启的功能
cpp
#define FUNCTION_MASK_AI 0b0000001
#define FUNCTION_MASK_AR 0b0000010
#define FUNCTION_MASK_DEFOG 0b0000100
#define FUNCTION_MASK_STABLE 0b0001000
#define FUNCTION_MASK_VIDEO_RECORD 0b0010000
#define FUNCTION_MASK_SNAP_SHOT 0b0100000
#define FUNCTION_MASK_AI_ASSIST_TRACK 0b1000000ar_file示例如下:
| Key | Value |
|---|---|
| ar_vector | 适量文件kml或kmz |
| ar_camera | 相机的config文件 |
smaGetMediaList
描述:获取流媒体任务列表
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string //鉴权码
}返回的流媒体列表信息
json
{
"code":int, //错误码
"data":
[
{
"pull_url":string, //高清拉流地址
"push_url":string, //高清推流地址
"pull_sd_url":string, //标清拉流地址(非必填,多路视频时有)
"push_sd_url":string, //标清推流地址(非必填,多路视频时有)
"ai_enable":bool, //是否开启AI
"ai_enable":bool, //是否开启AR
"aiassisttrack_enable":bool, //是否开启AI辅助跟踪
"func_mask": int, //功能掩码
"id":string, //任务ID
},
{
......
}
]
}smaGetMediaInfo
描述:获取指定任务的媒体信息
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string, //鉴权码
"id":string //任务id
}返回的媒体信息
json
{
"code":int, //错误码
"pull_url":string, //拉流地址
"push_url":string, //推流地址
"pull_sd_url":string, //标清拉流地址(非必填,多路视频时有)
"push_sd_url":string, //标清推流地址(非必填,多路视频时有)
"ai_enable":bool, //是否开启AI
"ai_enable":bool, //是否开启AR
"aiassisttrack_enable":bool, //是否开启AI辅助跟踪
"func_mask": int, //功能掩码
"id":string, //任务ID
}smaGetServerConfig
描述:获取服务配置信息
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string, //鉴权码
}返回的配置信息
json
{
"code":int, //错误码
"data":{
"api.secret": string, //api操作密钥
"general.TimeZoneNum": string, //时区
"general.UploadImageTimeDuration": string, //隐患回传间隔秒数
"general.guid": string, //微服务guid
"general.server_version": string, //微服务程序版本
"http.port": string, //http服务端口号
//wep hook api相关配置
"hook.enable": bool, //是否启用hook api
"hook.on_add_task": string, //开始创建任务
"hook.on_add_task_result": string, //创建任务结果
"hook.on_remove_task": string, //主动调用删除任务的结果
"hook.on_function_updated": string, //更新funcmask掩码结果
"hook.on_task_stoped": string, //拉不到原始视频流,开始删除任务
"hook.onnx_to_engine_result": string, //onnx转引擎结果
"hook.on_save_snapshot_result": string, //快照结果
"hook.on_create_ar_engine_result": string, //创建arengine的结果
"hook.ground_edge_response": string, //地面边应用给云端边应用的回复
//机载端相关配置
"media.enable_visual_and_infrared": string, //默认为1开启可见光,为2时,开启红外
"media.infrared_guid": string, //红外视频任务guid
"media.infrared_input_url": string, //红外视频吊舱输入视频流地址
"media.infrared_multicast_url": string, //红外视频输出组播视频流地址
"media.record_file_prefix": string, //录像文件前缀
"media.record_hd_file_prefix": string, //机载端高清录像文件前缀
"media.record_path": string, //录像文件夹地址
"media.record_sd_file_prefix": string, //机载端标清录像文件前缀
"media.snap_shot_numbers": int, //快照数量
"media.snap_shot_path": string, //快照保存路径
"media.visual_guid": string, //可见光视频任务guid
"media.visual_input_frame_rate": int, //可见光输入视频帧率
"media.visual_input_url": string, //可见光视频输入视频流地址
"media.visual_multicast_url": string, //可见光视频输出组播视频流地址
//rpc 相关配置,从开始端口到结束端口间找到一个可用端口
"sma_rpc.start_port": string, //rpc开始端口
"sma_rpc.end_port": string, //rpc结束端口
//原pilotControl 视频相关配置
"vehicle.hd_app": string, //高清视频流app
"vehicle.hd_stream": string, //高清视频流stream, 流媒体视频流为:协议//ip:port/app/stream
"vehicle.hd_url_pusher": string, //高清视频推流地址
"vehicle.hd_url_src": string, //高清视频拉流地址
"vehicle.http_port": string, //流媒体端口,默认为webrtc http端口
"vehicle.pilot_id": string, //飞控id
//ai 相关配置
"ai.YoloVersion": string, //yolo版本
"ai.aux_YoloVersion": string, //ai辅助ar yolo版本
"ai.aux_class_num": string, //ai辅助ar 类别数量
"ai.aux_conf_thresh": string, //ai辅助ar 目标类别置信度阈值
"ai.aux_engine_file_full_name": string, //ai辅助ar engine完整路径
"ai.aux_height": string, ///ai辅助ar 输入尺寸的高
"ai.aux_nms_thresh": string, ///ai辅助ar nms阈值
"ai.aux_onnx_file_full_name": string, //ai辅助ar onnx完整路径
"ai.aux_track_buff_len": string, //ai辅助ar 跟踪buf大小
"ai.aux_track_switch": string, //ai辅助ar 目标跟踪开关
"ai.aux_width": string, //ai辅助ar 输入尺寸的宽
"ai.class_num": string, //类别数量
"ai.conf_thresh": string, //目标类别置信度阈值
"ai.danger_photo_server_url": string, //隐患回传http地址
"ai.engine_file_full_name": string, //engine完整路径
"ai.height": string, //输入尺寸的高
"ai.nms_thresh": string, //nms阈值
"ai.onnx_file_full_name": string, //onnx完整路径
"ai.track_buff_len": string, //跟踪buf大小
"ai.track_switch": string, //目标跟踪开关
"ai.width": string, //输入尺寸的宽
.......
}
}smaGetAIRelated
描述:获取所有AI相关文件路径
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string, //鉴权码
"find_engine":string, //1表示要查找engine文件,0表示不查找
"find_onnx":string //1表示要查找onnx文件,0表示不查找
}返回的相关文件路径信息
json
{
"code":int, //错误码
"engine":[
"/usr/loacl/..."
.......
]
"onnx":[
"/usr/loacl/..."
.......
]
}smaSetServerConfig
描述:修改配置
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string, //鉴权码
"http.port": string,
"http.sslport":string,
"http.apiDebug":string,
"rpc.port":string
}smaUploadAIModelFile
描述:上传AImodel文件
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| aiStream | std::string | AI model文件,通过http form-data传递时key为ai_model_file |
paramsStr示例如下:
json
{
"secret":string,
"model_width": string, //模型宽
"model_height": string, //模型高
"class_number": string, //检测的类型数量
"conf_thresh": string, //检测框的置信度阈值
"nms_thresh": string, //nms(非极大值抑制)的置信度阈值
"yolo_version": string //yolo版本
}smaAddAnnotationElements
描述:增加标注要素
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| ar_file | std::map<std::string, std::string> | 以键值对形式存储的ar相关文件,这里时camera.config文件和标注要素json文件 |
paramsStr示例如下:
json
{
"secret":string,
"id": string, //任务id
}ar_file示例如下:
| Key | Value |
|---|---|
| video_mark_data | 标注要素json文件 |
| ar_camera | 相机的config文件 |
标注要素示例如下:
json
{
"Guid": 透传回云端的GUID,用于云端自己标识标注要素
"ArElementsArray":[
{
X: int //图像坐标X
Y: int //图像坐标Y
Type: uint8 //坐标类型,当前是点、线还是面
DotQuantity:uint8 //如果是线或面,表示线、面有几个点
Category:uint8 //当前点的类型,比如房屋等-暂时未用
CurIndex:uint8 //当前点序号
NextIndex: uint8 //下一点序号
lon: double //经度
lat: double //纬度
HMSL: //高度
},
{
....
}
]
}smaDeleteAnnotationElements
描述:删除标注要素
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string, //任务id
"elements_guid": string //添加标注要素时云端下发的guid
}smaUploadAIOnnxFile
描述:上传AIonnx文件
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
| onnxStream | std::string | AI onnx文件,通过http form-data传递时key为ai_onnx_file |
paramsStr示例如下:
json
{
"secret":string,
"onnx": ".onnx" //onnx文件后缀
}smaStartOnnxtoEngine
描述:将onnx转换为对应的engine文件
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
json
{
"secret":string,
"is_fp16": string, //是否按照fp_16转换,0表示否,1表示是
}smaGetOnnxtoEnginePercent
描述:获取onnx转换为engine文件的进度
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string
}返回的进度信息
json
{
"code":int, //错误码
"data": float //转换进度,范围 1~100
}smaRequestAiAssistTrack
描述:AI辅助跟踪
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"track_cmd": string,
"track_pixelpos_x": string, //跟踪点的图像坐标X
"track_pixelpos_y": string, //跟踪点的图像坐标Y
}smaSaveSnapShot
描述:AI辅助跟踪
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"path": string, //快照保存路径
"numbers": string //快照数
}smaUpdateArTowerHeight
描述:更新AR杆塔高度
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"is_tower": bool, //
"tower_height": double, //
"buffer_sync_height": bool //
}smaUpdateAIPosCor
描述:更改AI辅助吸附位置,默认为中心
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"ai_pos_cor": int //取值范围0-BOTTOM,1-CENTER,2-TOP
}smaSetSeekPercent
描述:视频跳转,只有http和文件作为视频源时才支持跳转
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"percent": float //进度,取值范围0-100
}smaSetVideoPause
描述:视频暂停,只有http和文件作为视频源时才支持跳转
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"pause": int //进度,1-暂停, 0-继续播放
}smaPlaybackMarkRecord
描述:开始回放标注的后处理
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"playback_address": string //回放文件路径
"video_out_url": string,//推流地址
"directory": string, //元数据文件地址,非必填
}smaSetArLevelDistance
描述:设置ar警戒区
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"id": string,
"level_one_distance": string //一级警戒区,要大于0,一级警戒区要大于等于二级警戒区
"level_two_distance": string,//二级警戒区,要大于0
}pushStreamUrl
描述:推流地址推送,原pilotControl功能
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"data": {
"streamUrl": string //推流地址:如果是本地使用时,传空;如果是云平台使用时,传具体的推流地址
},
"id": string, //飞控id
}distributeCfg
描述:流媒体分发相关配置,原pilotControl功能
参数
| 参数名 | 参数类型 | 备注 |
|---|---|---|
| paramsStr | std::string | json形式的参数列表 |
paramsStr示例如下:
json
{
"secret":string,
"data": {
"hdVideoUrl": string, //高清视频源
"httpPort": int, //流媒体服务器webrtc http端口
"hdApp": string, //高清视频流地址的app
"hdStream": string, //高清视频流地址的stream
"sdVideoUrl": string, //标清视频源 (非必填)
"rtcPort": int, //webrtc端口,默认8000 (非必填)
"sdApp": string, //标清视频流地址的app (非必填)
"sdStream": string //标清视频流地址的stream (非必填)
},
"id": string, //飞控id
}5 hook api详解
根据微服务配置里的hoop api地址,如果打开了hook.enable且api有地址,触发相应事件的时候会调用相关hook api接口
on_add_task_result
描述:创建任务结果hook api接口
参数
json
{
"id": string, //任务id
"code":string, //状态码
"result": string, //"true"、"false"
"duration": string, //时长,本地视频才有,暂时没用
"sd_duration": string,
"msg": string //信息描述
}on_add_task
描述:开始创建任务hook api接口
参数
json
创建任务的http 接口参数on_task_stoped
描述:拉不到原始视频流,开始删除任务hook api接口
参数
json
{
"code":string, //状态码
"id": string, //任务id
"reason":string, //原因描述
}on_remove_task
描述:主动调用删除任务的结果hook api接口
参数
json
{
"code":string, //状态码
"id": string, //任务id
"result": string, //"true"、"false"
}onnx_to_engine_result
描述:onnx转引擎结果hook api接口
参数
json
{
"code":string, //状态码
"msg": string //信息描述
"result": string, //"success" : "failed"
}on_save_snapshot_result
描述:快照结果hook api接口
参数
json
{
"code":string, //状态码
"id": string, //任务id
"msg": string //信息描述
}on_function_updated
描述:更新funcmask掩码结果hook api接口
参数
json
{
"code":string, //状态码
"id": string, //任务id
"result": string, //"success"、"failed"
"func_mask": string, //功能掩码
"msg": string //信息描述
}on_create_ar_engine_result
描述:创建AR引擎结果hook api接口
参数
json
{
"code":string, //状态码
"id": string, //任务id
"result": string, //"success"、"failed"
"msg": string //信息描述
}ground_edge_response
描述:地面边应用给云端边应用的回复
参数
json
{
"from":string, //源站点
"interface": string, //接口名
"pilot_id": string, //飞控ID
...其他的跟http结果一样
}
