Welcome to Firefly
Switch language
Switch language
Firefly Docsss
Last Updated: 2026-08-26 17:51:06

OEM 资源

OEM 资源提供 Firefly 扩展的 KVM/ADB、VNC、WebTTY 和告警通知能力。

认证与访问协议

本页普通 HTTP 请求支持 HTTP Basic Auth 和会话 Token。Token 通过请求头 X-Xsrf-Token 携带。WebSocket 连接同样使用 X-Xsrf-Token 请求头。示例中的 <protocol> 根据服务配置填写 http 或 https。

1 远程管理资源

1.1 查询 ADB 设备列表

查询当前通过 USB 或网络 ADB 连接的设备。

项目内容
方法GET
路径/redfish/v1/Oem/KvmServices
认证HTTP Basic Auth 或 X-Xsrf-Token
请求体无
查询 ADB 设备列表
curl --user '<username>:<password>' \
  --header 'Accept: application/json' \
  --max-time 20 \
  '<protocol>://<device-ip>:<port>/redfish/v1/Oem/KvmServices'

成功响应结构

后端成功取得 ADB 设备时返回以下结构：

200 OK · 后端响应结构
{
  "@odata.type": "#Oem.v1_0_2.FireflyKvmService.DeviceList",
  "Oem": {
    "Firefly": {
      "DeviceList": []
    }
  },
  "Name": "FireflyKvmService.DeviceList",
  "Id": "FireflyKvmService.DeviceList",
  "@odata.id": "/redfish/v1/Oem/KvmServices"
}

响应字段

字段类型说明
@odata.typestringADB 设备列表的 OEM 类型。
OemobjectOEM 扩展信息。
Oem.FireflyobjectFirefly KVM 扩展信息。
Oem.Firefly.DeviceListarrayADB 设备列表。具体设备字段由当前 ADB 实现返回。
Namestring资源名称。
Idstring资源标识。
@odata.idstring当前资源路径。

当前部署查询超时

实机请求在 20 秒内未返回任何响应，curl 状态为超时。该接口会同步等待 ADB 设备扫描；调用方应设置客户端超时，并将“未发现设备”和“ADB 服务未响应”区分处理。

1.2 远程管理 WebSocket

通过 WebSocket 建立 Android 设备投屏会话。连接成功后，服务端先发送设备显示和视频编码能力，客户端再提交投屏参数，随后通过二进制 WebSocket 消息持续接收视频数据。

项目内容
方法GET + WebSocket Upgrade
路径/redfish/v1/Oem/KvmServices/ws
认证X-Xsrf-Token
查询参数udid，Android 设备唯一标识
成功状态码101 Switching Protocols
传输内容JSON 协商消息、二进制视频帧和控制消息

协议对应关系

BMC 使用 HTTP 时连接 ws://；使用 HTTPS 时连接 wss://。该接口不返回普通的 200 OK JSON 响应。

连接示例

建立 Android 投屏连接
websocat \
  --header 'X-Xsrf-Token: <token>' \
  'ws://<device-ip>:<port>/redfish/v1/Oem/KvmServices/ws?udid=<device-udid>'

udid 应使用“1.1 查询 ADB 设备列表”返回的有效设备标识。未在 URL 中传入 udid 时，服务端兼容旧版客户端：WebSocket 连接建立后，将下列 JSON 作为第一条文本消息发送。

旧版客户端设备选择消息
{
  "udid": "<device-udid>"
}

连接流程

  1. 客户端使用有效 udid 发起 WebSocket Upgrade 请求。
  2. 服务端查找 Android 设备，并读取设备名称、分辨率、显示器和编码器信息。
  3. 服务端发送一条 JSON 文本消息，告知客户端可用的视频能力。
  4. 新版客户端发送 setting 消息，选择码率、帧率、分辨率、显示器和编码器。
  5. 服务端启动 scrcpy 会话，持续发送二进制视频数据；客户端可同时发送触摸等控制消息。

视频能力消息

以下为服务端首条文本消息的结构示例。设备名称、分辨率和编码器列表以实际 Android 设备为准。

WebSocket 文本消息·结构示例
{
  "deviceName": "<android-device-name>",
  "displayInfo": {
    "displayId": 0,
    "width": 1080,
    "height": 1920,
    "rotation": 0,
    "layerStack": 0
  },
  "connectionCount": 0,
  "screenInfo": {
    "left": 0,
    "top": 0,
    "right": 0,
    "bottom": 0,
    "width": 1080,
    "height": 1920,
    "deviceRotation": 0
  },
  "videoSettings": {
    "video": true,
    "bitrate": 0,
    "maxFps": 0,
    "width": 0,
    "height": 0,
    "left": 0,
    "top": 0,
    "right": 0,
    "bottom": 0,
    "displayId": 0,
    "encoderName": "",
    "codecOptions": "",
    "iFrameInterval": 0,
    "sendFrameMeta": false,
    "lockedVideoOrientation": 0,
    "videoBuffer": 0,
    "control": true,
    "audio": false
  },
  "encoders": [
    "<encoder-name>"
  ],
  "clientId": 1
}
字段类型说明
deviceNamestringAndroid 设备产品名称。
displayInfoobject当前显示器信息。
displayInfo.displayIdintegerAndroid 显示器编号。
displayInfo.widthinteger显示器宽度，单位为像素。
displayInfo.heightinteger显示器高度，单位为像素。
displayInfo.rotationinteger显示器旋转角度。
displayInfo.layerStackintegerAndroid 显示层栈标识。
connectionCountinteger当前连接数。
screenInfoobject当前屏幕区域和旋转信息。
screenInfo.leftinteger屏幕区域左边界。
screenInfo.topinteger屏幕区域上边界。
screenInfo.rightinteger屏幕区域右边界。
screenInfo.bottominteger屏幕区域下边界。
screenInfo.widthinteger屏幕宽度，单位为像素。
screenInfo.heightinteger屏幕高度，单位为像素。
screenInfo.deviceRotationinteger设备屏幕旋转角度。
videoSettingsobject服务端建议的初始视频配置。
videoSettings.videoboolean是否启用视频传输。
videoSettings.bitrateinteger视频码率，单位为 bit/s；初始能力消息中可为 0。
videoSettings.maxFpsinteger最大视频帧率；初始能力消息中可为 0。
videoSettings.widthinteger目标视频宽度，单位为像素。
videoSettings.heightinteger目标视频高度，单位为像素。
videoSettings.leftinteger视频裁剪区域左边界。
videoSettings.topinteger视频裁剪区域上边界。
videoSettings.rightinteger视频裁剪区域右边界。
videoSettings.bottominteger视频裁剪区域下边界。
videoSettings.displayIdintegerAndroid 显示器编号。
videoSettings.encoderNamestring选用的视频编码器名称。
videoSettings.codecOptionsstring传递给视频编码器的附加选项。
videoSettings.iFrameIntervalinteger关键帧间隔。
videoSettings.sendFrameMetaboolean是否传输视频帧元数据。
videoSettings.lockedVideoOrientationinteger锁定的视频方向。
videoSettings.videoBufferinteger视频缓冲配置。
videoSettings.controlboolean是否启用远程控制。
videoSettings.audioboolean是否启用音频传输。
encodersarray当前设备支持的视频编码器名称列表。
clientIdinteger当前 WebSocket 客户端标识。

客户端设置消息

收到视频能力消息后，新版客户端应发送一条 setting JSON 文本消息。

WebSocket 文本消息
{
  "type": "setting",
  "data": {
    "bitrate": 4000000,
    "maxFps": 24,
    "bounds": {
      "width": 720,
      "height": 1280
    },
    "displayId": 0,
    "control": true,
    "audio": false,
    "video": true,
    "encoderName": "<encoder-name>",
    "codecOptions": ""
  }
}
字段类型说明
typestring消息类型，固定为 setting。
data.bitrateinteger视频码率，单位为 bit/s。
data.maxFpsinteger最大视频帧率。
data.bounds.widthinteger输出视频宽度，单位为像素。
data.bounds.heightinteger输出视频高度，单位为像素。
data.displayIdinteger要投屏的 Android 显示器编号。
data.controlboolean是否启用远程控制。
data.audioboolean是否启用音频传输。
data.videoboolean是否启用视频传输。
data.encoderNamestring视频编码器名称，应从服务端返回的 encoders 中选择。
data.codecOptionsstring传递给 scrcpy 视频编码器的附加选项；无额外选项时传空字符串。

视频与控制消息

  • 服务端以二进制 WebSocket 消息持续发送视频数据，客户端需按 scrcpy 视频流处理，不能将其当作 JSON 解析。
  • 客户端可以发送 scrcpy 二进制控制包，也可发送兼容的 JSON 文本触摸消息。
  • pong 文本消息用于客户端保活，服务端接收后不转发给 Android 设备。
触摸控制消息
{
  "messageType": "touch",
  "data": {
    "actionType": 0,
    "x": 416,
    "y": 243,
    "width": 1080,
    "height": 1920
  }
}
字段类型说明
messageTypestring消息类型。触摸事件为 touch，保活消息为 pong。
data.actionTypeinteger触摸动作：0 表示按下，1 表示抬起，2 表示移动。
data.xinteger触摸点 X 坐标。
data.yinteger触摸点 Y 坐标。
data.widthinteger坐标系宽度，必须大于 0 且不超过 65535。
data.heightinteger坐标系高度，必须大于 0 且不超过 65535。

错误消息

WebSocket Upgrade 已成功但后续初始化失败时，服务端会发送 JSON 字符串后结束连接。

消息说明
"udid is empty"旧版握手消息未提供有效 udid。
"device not found"未找到 udid 对应的 Android 设备。
"scrcpy option list failed"无法读取设备的 scrcpy 编码器或显示信息。
"scrcpy client create failed"创建 scrcpy 会话失败。
"scrcpy client start failed"启动 scrcpy 会话失败。

2 告警管理资源

2.1 查询 SMTP 配置

项目内容
方法GET
路径/redfish/v1/Oem/Alert/GetSMTPServer
认证HTTP Basic Auth 或 X-Xsrf-Token
所需权限OemDebug
成功状态码200 OK
查询 SMTP 配置
curl --user '<username>:<password>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/Oem/Alert/GetSMTPServer'

响应示例

200 OK
{
  "@odata.id": "/redfish/v1/Oem/Alert/GetSMTPServer",
  "enable": false,
  "mail_addr": "",
  "smtp_addr": "",
  "smtp_port": 0
}

响应字段

字段类型说明
@odata.idstringSMTP 配置资源路径。
enableboolean是否启用邮件发送。
mail_addrstring发件人邮箱账号。
smtp_addrstringSMTP 服务器地址。
smtp_portintegerSMTP 服务器端口。

授权码不会返回

查询接口不会返回 mail_auth，因此无法仅依靠 GET 响应完整还原当前 SMTP 配置。原值回写前必须另行确认授权码。

2.2 设置 SMTP 配置

项目内容
方法POST
路径/redfish/v1/Oem/Alert/SetSMTPServer
所需权限OemDebug
成功状态码200 OK
请求字段类型必填说明
mail_addrstring是发件人邮箱账号。
mail_authstring是SMTP 授权码或应用密码。
smtp_addrstring是SMTP 服务器域名或地址。
smtp_portinteger是SMTP 服务器端口。
enableboolean是是否启用邮件告警。
使用 Token 设置 SMTP 配置
curl --request POST \
  --header 'X-Xsrf-Token: <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "mail_addr": "sender@example.com",
    "mail_auth": "<smtp-authorization-code>",
    "smtp_addr": "smtp.example.com",
    "smtp_port": 465,
    "enable": true
  }' \
  '<protocol>://<device-ip>:<port>/redfish/v1/Oem/Alert/SetSMTPServer'

该接口整体替换发件人配置并写入数据库，本次未执行。

响应示例

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish 消息资源的 OData 类型。
Timestampstring服务端响应时间戳。
MessageIdstring成功消息标识。
Messagestring请求处理结果。
MessageArgsarray消息格式化参数。
MessageSeveritystring消息严重级别。
Severitystring兼容保留的严重级别字段。
Oemobject | nullOEM 扩展消息。
RelatedPropertiesarray | null相关属性路径。
Resolutionstring建议的处理方式。

2.3 发送测试邮件

项目内容
方法POST
路径/redfish/v1/Oem/Alert/SendMsg
所需权限OemDebug
前置条件SMTP 配置有效且网络可访问 SMTP 服务器
请求字段类型必填说明
tostring[]是收件人列表。
ccstring[]否抄送列表。
bccstring[]否密送列表。
subjectstring是邮件主题。
msgstring是邮件正文。
msg_formatstring是正文 MIME 类型，例如 text/plain 或 text/html。
请求体示例
{
  "to": ["receiver@example.com"],
  "subject": "BMC alert test",
  "msg": "This is a test message.",
  "msg_format": "text/plain"
}

该操作会向外部邮箱真实发送邮件，本次未执行。

响应示例

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish 消息资源的 OData 类型。
Timestampstring服务端响应时间戳。
MessageIdstring成功消息标识。
Messagestring请求处理结果。
MessageArgsarray消息格式化参数。
MessageSeveritystring消息严重级别。
Severitystring兼容保留的严重级别字段。
Oemobject | nullOEM 扩展消息。
RelatedPropertiesarray | null相关属性路径。
Resolutionstring建议的处理方式。

2.4 查询告警接收者

项目内容
方法GET
路径/redfish/v1/Oem/Alert/GetReceivers
认证HTTP Basic Auth 或 X-Xsrf-Token
所需权限OemDebug
成功状态码200 OK
查询告警接收者
curl --user '<username>:<password>' \
  --header 'Accept: application/json' \
  '<protocol>://<device-ip>:<port>/redfish/v1/Oem/Alert/GetReceivers'

响应示例

200 OK
{
  "@odata.id": "/redfish/v1/Oem/Alert/GetReceivers",
  "Receivers": {}
}

响应字段

字段类型说明
@odata.idstring告警接收者资源路径。
Receiversobject以接收者名称为键的接收者映射。
Receivers.{name}.Namestring接收者名称。
Receivers.{name}.Wayinteger通知渠道组合编码，取值为 1 至 8。
Receivers.{name}.Severitystring接收的告警严重级别。
Receivers.{name}.Mailstring邮件地址。
Receivers.{name}.EnterpriseWechatstring企业微信机器人 Webhook。
Receivers.{name}.DingTalkstring钉钉机器人 Webhook。

2.5 新增或修改告警接收者

操作方法路径
新增接收者POST/redfish/v1/Oem/Alert/AddReceivers
修改接收者POST/redfish/v1/Oem/Alert/SetReceivers

两个接口使用相同请求结构。

请求字段类型必填说明
Namestring是接收者唯一名称。修改接口以该字段定位或创建记录。
Wayinteger是渠道组合：1 不通知、2 邮件、3 企业微信、4 钉钉、5 邮件+企业微信、6 邮件+钉钉、7 企业微信+钉钉、8 全部。
Severitystring是接收的告警严重级别。
Mailstring条件必填使用邮件渠道时填写。
EnterpriseWechatstring条件必填使用企业微信渠道时填写 Webhook。
DingTalkstring条件必填使用钉钉渠道时填写 Webhook。
请求体示例
{
  "Name": "operations-team",
  "Way": 2,
  "Severity": "Critical",
  "Mail": "operations@example.com",
  "EnterpriseWechat": "",
  "DingTalk": ""
}

后端会拒绝重复名称，以及与其他接收者重复的邮箱或机器人 Webhook。本次未修改接收者。

响应示例

新增和修改成功时均返回：

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish 消息资源的 OData 类型。
Timestampstring服务端响应时间戳。
MessageIdstring成功消息标识。
Messagestring请求处理结果。
MessageArgsarray消息格式化参数。
MessageSeveritystring消息严重级别。
Severitystring兼容保留的严重级别字段。
Oemobject | nullOEM 扩展消息。
RelatedPropertiesarray | null相关属性路径。
Resolutionstring建议的处理方式。

2.6 删除告警接收者

项目内容
方法POST
路径/redfish/v1/Oem/Alert/DelReceivers
请求字段Name，string，必填
成功状态码200 OK
请求体示例
{
  "Name": "operations-team"
}

接收者不存在时返回 Redfish 通用错误。该操作会永久删除接收者配置，本次未执行。

响应示例

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish 消息资源的 OData 类型。
Timestampstring服务端响应时间戳。
MessageIdstring成功消息标识。
Messagestring请求处理结果。
MessageArgsarray消息格式化参数。
MessageSeveritystring消息严重级别。
Severitystring兼容保留的严重级别字段。
Oemobject | nullOEM 扩展消息。
RelatedPropertiesarray | null相关属性路径。
Resolutionstring建议的处理方式。

2.7 测试告警接收者

对一个或多个已存在的接收者触发测试通知。

项目内容
方法POST
路径/redfish/v1/Oem/Alert/Test
请求体接收者名称对象数组
成功状态码200 OK
请求体示例
[
  { "Name": "operations-team" }
]

接口会异步调用接收者配置的邮件、企业微信或钉钉渠道，可能产生真实外部通知，本次未执行。

响应示例

200 OK
{
  "@odata.type": "#Message.v1_1_1.Message",
  "Timestamp": "1785836138",
  "MessageId": "Base.1.11.0.Success",
  "Message": "The request completed successfully.",
  "MessageArgs": [],
  "MessageSeverity": "OK",
  "Severity": "",
  "Oem": null,
  "RelatedProperties": null,
  "Resolution": "None"
}

响应字段

字段类型说明
@odata.typestringRedfish 消息资源的 OData 类型。
Timestampstring服务端响应时间戳。
MessageIdstring成功消息标识。
Messagestring请求处理结果。
MessageArgsarray消息格式化参数。
MessageSeveritystring消息严重级别。
Severitystring兼容保留的严重级别字段。
Oemobject | nullOEM 扩展消息。
RelatedPropertiesarray | null相关属性路径。
Resolutionstring建议的处理方式。

Managers资源

Previous Page

Users资源

Next Page

On this page

OEM 资源
1 远程管理资源
1.1 查询 ADB 设备列表
成功响应结构
响应字段
1.2 远程管理 WebSocket
连接示例
连接流程
视频能力消息
客户端设置消息
视频与控制消息
错误消息
2 告警管理资源
2.1 查询 SMTP 配置
响应示例
响应字段
2.2 设置 SMTP 配置
响应示例
响应字段
2.3 发送测试邮件
响应示例
响应字段
2.4 查询告警接收者
响应示例
响应字段
2.5 新增或修改告警接收者
响应示例
响应字段
2.6 删除告警接收者
响应示例
响应字段
2.7 测试告警接收者
响应示例
响应字段