菊风已发布实时音视频2.0升级版（2.0版本说明），当前您正在访问1.0旧版本，点击此处可进入2.0升级版
快速开始

# 功能介绍

借助微信小程序音视频通话（for 硬件） (opens new window)能力，硬件开发者设备端集成菊风 IoT SDK，小程序端接入微信 VoIP 通话插件，可以实现当设备呼叫手机端微信用户时，手机端微信用户不需要打开微信，即可收到音视频通话弹窗提醒，通过提醒进入小程序进行通话。适用于智能门锁、智能手表、校园话机、门禁机、智慧中控屏、智能电视、智能摄像头、智能音箱、智慧养老等多种设备和场景。下图为手机端微信的示意图，授权弹窗、通话提醒、通话界面为微信提供的统一界面。

功能介绍

# 业务流程

业务流程

# 功能开通

# 申请小程序

  1. 开发者向微信官方 (opens new window)申请开通非个人主体的微信小程序，并做好微信官方认证，该小程序用于和设备通话，登录微信公众平台 (opens new window)获取小程序的 AppID

image.png

# 申请开通设备管理

开发者参考微信官方文档 (opens new window)的要求和步骤，添加 [工具-设备管理]为小程序服务类目，开通硬件设备能力，添加用于音视频通话的设备类型，获取微信平台分配的 model_id

image.png

# 集成开发

# 兼容性说明

如果实现双向音视频通话，确保微信版本高于 8.0.54 版本

# 开发准备

  1. 准备应用账号和导入 License

请注册 (opens new window) 或登录 (opens new window) 菊风开发者账号，在控制台创建 1.0 应用以获取 appKey 和 AES_KEY，并导入 License

TIP

如果已有 RTC1.0 应用的 appKey 和 AES_KEY 密钥，也可以直接使用，License 导号逻辑保持不变

  1. 在控制台【应用管理】-【应用详情】页面开通微信 VoIP 通话服务，开发者获取小程序授权链接，由小程序的管理员扫码授权小程序权限集硬件服务 ID：118 给菊风

image.png

image.png

  1. 开发者自行实现用户的通讯录功能，维护设备 sn（即设备唯一 ID：Device ID）和微信小程序 appid、微信小程序用户 openid 的关系

  2. 开发者自行实现呼叫信令，小程序呼叫设备需要信令

# 设备呼叫小程序

image.png

开发者在设备端集成菊风 RTOS SDK，设备呼叫小程序通过以下三个阶段实现：

  1. 全局配置：调用 jwxa1_config 完成全局配置
  2. 发起呼叫：设备呼叫客户服务器，由服务器调用 POST call 接口发起呼叫
  3. 接通媒体：用户触发呼叫后，构造会话参数并调用 jwxa1_open 打开媒体通道，返回 jrtc_t 对象（通话对象）

# 小程序拒接

前提：

  1. 小程序端在小程序管理后台完成「小程序音视频能力」申请并通过后，开发者参考菊风提供的微信小程序 VoIP 插件接入文档进行集成开发，直接使用 VoIP 插件，无需额外申请

  2. 小程序收到设备的呼叫后，小程序用户需要对设备进行授权，授权后才会弹出来电的通知进而实现通话，因此开发者还需要参考微信官方文档 (opens new window)实现授权逻辑

小程序端调用 VoIP 插件接口实现来电拒接，拒接通知由菊风服务端推送至 RTOS SDK。SDK 需持续主动调用 jrtc_state 轮询通话状态：

enum jrtc_state state = jrtc_state(jc);
if (state == JRTC_LEAVING || state == JRTC_CLOSED) {
    // 通话已结束，查询原因
    enum jrtc_error err = jrtc_error(jc);
    if (err == JRTC_EDECLINE) {
        // 对方拒接（值 129）
    }
}
状态常量值说明
JRTC_LEAVING1离开中的临时状态
JRTC_CLOSED0初始或已结束
JRTC_TALKING5通话中
错误常量值说明
JRTC_EDECLINE129对方拒接
JRTC_EBYE255对方挂断
JRTC_ECONNRESET104连接断开

# 小程序接听

小程序端调用 VoIP 插件接口实现来电接听，接听后菊风后台实现双端媒体流打通，实现双向音视频通话

# 小程序挂断

小程序端调用 VoIP 插件接口实现通话挂断，挂断通知由菊风服务推送至 RTOS SDK。SDK 同样通过 jrtc_state 轮询，当状态为 JRTC_LEAVING 或 JRTC_CLOSED 时，调用 jrtc_error 获取 JRTC_EBYE 确认对方挂断

# 设备挂断

设备端 SDK 主动挂断通话，调用 jrtc_leave 离开，再调用 jrtc_close 释放资源

jrtc_leave(jc, JRTC_EBYE);

jrtc_close(jc, JRTC_EBYE);

# 小程序呼叫设备

image.png

开发者在设备端集成菊风 RTOS SDK，SDK 中 jwxa1 接口用于实现 1.0 环境微信 VoIP 通话。小程序呼叫设备，由小程序端通过客户自建信令通道通知客户后台服务，后台服务通知设备，此时小程序端调用 VoIP 插件接口 (opens new window)发起呼叫，准备接通媒体

# 设备拒接

设备通知客户后台拒接来电，通过客户后台调用 POST reject 接口拒绝接听，此时小程序端会收到拒接通知

# 设备接听

设备端 SDK 调用 jwxa1_open 接听来电，接听后双端媒体流打通，实现双向音视频通话

# 画面角度旋转与分辨率

  1. 微信小程序端发出的视频流方向与物理方向并不一致，默认是逆时针旋转 90 度的，因此设备端看小程序端的画面如果需要调整为正向，需要保证微信版本高于 8.0.54

    • 在设备呼叫小程序时，restful API 的 subscribeVideoRotation 参数传 1，query 中的 encodeVideoRotation 参数传 1；
    • 小程序呼叫设备时，小程序端的callDevice (opens new window)接口 payload 中subscribeVideoRotation 参数传 1 。

  2. 小程序看设备端的画面调整，可参考微信官方文档配置：微信官方文档 (opens new window)

image.png

当采用上述方案时，注意事项如下：

  1. setUIConfig 需要在通话发起前/接通前设置

  2. 小程序看设备端 需要将设备设置旋转 270 度 根据小程序是主叫还是被叫 调用 setUIconfig 来旋转 listenerUI 还是 callerUI,

当小程序作为主叫时 小程序为 caller 设备端为 listener 则需要旋转 listener 的 UI

// 在callDevice发起前调用
wmpfVoip.setUIConfig({
    listenerUI:{
        cameraRotation: 270,
    },
    callerUI:{
        cameraRotation: 270,
    },
})

当小程序作为被叫时 设备端为 caller 小程序为 listener 接听者 则需要旋转 caller 的 UI

// 此时应写在app.js 在小程序拉起时加载
wmpfVoip.setUIConfig({
    listenerUI:{
        cameraRotation: 0,
    },
    callerUI:{
        cameraRotation: 270,
    },
})
  1. 小程序端发出的 VoIP 的视频流默认为 H264 编码流，原始分辨率最大为 640x480

# 主要函数

# jwxa1_config

配置环境。会修改内部的全局变量。

函数原型：

void jwxa1_config(const char appKey[24], const char uid[64], const char aesKey[16], const char sn[128], const char tokens[128]);

参数说明如下：

参数名类型是否必填说明
appKeystring是当前APP特有的标识, 固定长度24, 需向Juphoon申请获得
uidstring是自定义的设备许可标识, 要求在 appKey 内唯一, 长度不超 64, 且需要向 Juphoon 登记并激活
aesKeystring是通讯密钥, 必须与 appKey 匹配, 固定长度16, 需向Juphoon申请或注册
snstring否对应规范要求的唯一设备标识，使用服务间对接方式(RESTful)时务必传 NULL，长度不超 128
tokensstring是用于鉴权的凭证, 长度不超128。详见 Token 鉴权

# jwxa1_open

打开通话通道，分配通话资源，返回 jrtc_t 对象。

函数原型：

struct jrtc_t* jwxa1_open (const char openid[64], const char callid[64], struct jrtc_image_t* video, struct jrtc_image_t* camera, const struct jwxa_options_t* options);

参数详细说明如下：

参数名类型是否必填说明
openidstring否默认传 null，被呼叫的微信用户 ID（OpenID 需要在微信手机客户端小程序侧通过 wx.login 获取），最大 64 字节
callidstring是自定义的唯一会话标识, 要求每次通话都不同，最大64字节
video结构体是表示期望接收视频的媒体建议值，若传NULL, 则不接收视频
camera结构体是表示期望发送视频的媒体建议值，若传NULL, 则不发送视频
option结构体否指向 jwxa_options_t 结构，可传 NULL。包含如下参数：
  • role：初始的角色集合, 默认主叫
  • status：初始的状态集合
  • query：小程序页面自定义参数, 长度不超64, 可以传 NULL

# 验收

由于微信小程序工具类类目的开通没有门槛，出于安全要求，如果最终业务要上线，需要寄送一台完成集成的设备给微信官方进行认证备案（设备寄送后不返还），具体参考硬件 VoIP 审核验证要求 (opens new window)。

# 商务计费

当前菊风支持 License 计费，具体费用联系商务咨询

最后更新时间: 7/31/2026, 9:21:14 AM

← 服务器接口 →