ecg-at-sdk v1.1.4

英语答题器上层 sdk

封装了操作答题器的常用步骤

安装

npm i ecg-at-sdk

用法

import { IpcTool, answers } from 'ecg-at-sdk'

const ipcTool = new IpcTool()

// 开启调试模式，开发模式会打印log
ipcTool.enableDebug()

// 事件回调
ipcTool.on('device-inited', msg => {
  console.log(msg)
})

ipcTool.on('pong', (cmd, msg) => {
  console.log(cmd, msg)
})

// 方法调用
ipcTool.init() // 可选参数 type: any/audio/no-audio

API

实例方法

vm.enableDebug(mode)

• 参数

  • {number} mode - 0 关闭 1 打印到console 2 通过debug事件传出

• 用法

  • 开启debug模式
  • 只在 process.env.NODE_ENV 为 development 时有效

vm.init(type)

• 参数

  • {string} type - any|audio|no-audio

• 用法

  • 初始化答题器实例

• 备注

  • 另有别名方法 vm.answerInit()

vm.startLesson(lessonId, students)

• 参数

  • {string} lessonId - 班级id，一般由业务后台提供
  • {Array} students - 学生列表，超过30个只去前30个

• 用法

  • 开始上课，一般在登录后调用

• 备注

  • 学生对象中必须有 stuid, stuname, stupoint 字段

vm.stopLesson()

• 用法
  • 结束上课

vm.startAnswer(type, options)

• 参数

  • {string} type - 答题类型，具体类型见可用常量
  • {Object} options - 答题参数，具体见示例

• 示例

  // 可用答题类型： 
  vm.startAnswer('audio', {
    row1: "哈哈哈哈",
    row2: "请按选项键",
    row3: "总积分：0",  // 空格清空 " ", 保留上次内容 ""
    context: {
      stems:["stem1", "stem2"],  // stems:字符串数组，音频评测原型，可以单个，也可以是多个，根据题目类型不同，数量不同
      'audio-file-name-prefix': "",  // 拼接音频文件名前缀
    },
    custom: ""  // 在按键事件上报时会原样返回, 用于数据跟踪
  })

vm.stopAnswer(options)

• 参数

  • {Object} options - 答题器回显参数

• 示例

  vm.stopAnswer({
    row1: "哈哈哈哈",
    row2: "请按选项键",
    row3: "总积分：0",  // 空格清空 " ", 保留上次内容 ""
  })

vm.stopAnswerAndClear()

• 示例

  vm.stopAnswerAndClear() // 停止答题并且清空 row2

vm.addStudent(student)

• 参数

  • {Object} student - 添加的学生

• 用法

  • 一般在缺勤或同步班上学生时使用，添加的学生会去重取最新的

• 示例

  vm.addStudent({
    stuid: '0101',
    stuname: '张三丰',
    stupoint: 20
  })

vm.removeStudent(studentOrId)

• 参数

  • {string | Object} studentOrId - 学生id 或者 学生对象

• 用法

  • 用来同步学生列表，删除的学生在实例中会消失

• 示例

  vm.removeStudent('0101')
  vm.removeStudent({
    stuid: '0101'
  })

vm.unbindStudent(stuid)

• 参数

  • {string} - 学生id

• 用法

  • 解绑学生，业务解绑+答题器drop

vm.setStudentContext(student)

• 参数

  • {Object} student - 学生对象

• 用法

  • 用来设置已绑定学生的答题器的回显

• 示例

  vm.setStudentContext({
    stuid: '0101',
    stuname: '张三', // 姓名会截取8个字符
    stupoint: 20
  })

vm.setStudentScore(stuid, stupoint)

• 参数

  • {string|number} stuid - 学生id
  • {string|number} stupoint - 学生分数

• 用法

  • 用来直接更新答题器分数
  • 不会更新学生姓名

• 示例

  vm.setStudentScore('0101', 20)

• 别名 `vm.updateScore(student, stupoint)

vm.addScore(stuid, point)

• 参数

  • {string|number} stuid - 学生id
  • {string|number} point - 学生加的分数

• 用法

  • 增加学生分数

• 示例

  vm.addScore(1000, 3)

ipc事件

device-inited

• 说明

  • 设备初始化

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    event: "device-inited",
    avaliable-device-type: "audio",  // non-audio/audio
    ready: true,  // false
    info: ""  // no-power, not-connected, ip-not-set
  }

arrived

• 说明

  • 答题器接收器插入
  • arrived 事件发生后，会紧接着发送 device-inited 事件

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    event: "arrived",
  }

removed

• 说明

  • 答题器接收器拔出

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    event: "removed",
    info: "",  // no-power, not-connected, ip-not-set
  }

activated

• 说明

  • 答题器激活

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    event: "activated",
    device: "device_id"
  }

inactivated

• 说明

  • 答题器反激活

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    event: "inactivated",
    device: "device_id"
  }

key-pressed | audio-recognized | voice-evaluated

• 说明

  • 答题器按键上报|语音已识别|语音已评测

• 参数

  {
    id: "",  // GUID IPC 指令唯一标识，用于统计收发两端是否配对；原则指令是从哪边发哪边负责生成 id
    stuid: "0x01", // sdk 附加的学生id
    event: "key-pressed",  // audio-recognized/voice-evaluated
    device: "device-id",
    key: "T",  // T/F/A/B/C/D/G 多选题时是："ABC"
    data: { start_time:Number, end_time:Number, result:string, score:int },
    extra: "|device-id|-|tickcount|.wav",
    custom: ""  // 发题时传入的原值
  }

底层事件

command

• 说明

  • 原始 command 事件，由 @ecg/at-ipc 中触发
  • 业务中一般只需要处理ipc事件即可

• 参数

  • {number} cmd 命令标识符 固定为 2018
  • {string} msg 消息JSON串

pong

• 说明

  • 心跳事件
  • 由中科答题器定义的，任意一方在发送 ping，另外一方需发送 pong

• 参数

  • {number} cmd 命令标识符 固定为 202 （ping 201, pong 202)
  • {string} msg 目前为 空字符串

自定义事件

active-device-exists

• 说明

  • 激活设备已绑定时触发

• 参数

  • {string} device 设备id
  • {Object} student 学生对象

active-device-success

• 说明

  • 激活设备成功时触发

• 参数

  • {string} device 设备id
  • {Object} student 学生对象

active-device-error

• 说明

  • 激活设备不存在时触发

• 参数

  • {string} device 设备id

inactive-device-success

• 说明

  • 反激活设备成功时触发

• 参数

  • {string} device 设备id
  • {Object} student 学生对象

inactive-device-error

• 说明

  • 反激活设备不存在时触发

• 参数

  • {string} device 设备id

unbind-student-success

• 说明

  • 解绑学生成功时触发

• 参数

  • {string} device 设备id
  • {Object} student 学生对象

unbind-student-error

• 说明

  • 解绑学生不存在时触发

• 参数

  • {string} stuid 学生id

可用常量

可用常量可以直接导出使用，如下：

import { answers, events, cmds } from '@ecg/at-sdk'

answers - 答题类型

const answers = {
  SINGLE_CHOICE: 'single-choice', // 单选
  MULTIPLE_CHOICE: 'multiple-choice', // 多选
  RED_ENVELOPE: 'red-envelope', // 红包
  CONTINUOUS_RED_ENVELOPE: 'continous-red-envelope', // 连续红包
  TRUE_FALSE: 'true-false', // 对错
  AUDIO: 'audio', // 语音
  GENERAL: 'general', // 通用
  MULTIPLE_QUESTION_SINGLE_CHOICE: 'multiple-question-single-choice', // 多题单选
  AUDIO_SINGLE: 'audio-single', // 单标准答案语音题
  AUDIO_MUTIPLE: 'audio-multiple', // 多标准答案语音题
  SIGN_UP: 'sign-up',
  AUDIO_MULTIPLE_CHN: 'audio-multiple-chn', // 多标准答案语音题(语文)
  EVALUATION: 'evaluation', // 通用语音评测
  VOICE_RECORD: 'voice-record' // 录音测试
}

events - 事件

const events = {
  DEVICE_INITED: 'device-inited', // 检测结果
  ARRIVED: 'arrived', // 答题器插入
  REMOVED: 'removed', // 答题器拔出
  ACTIVATED: 'activated', // 答题器激活
  INACTIVATED: 'inactivated', // 答题器反激活
  KEY_PRESSED: 'key-pressed', // 答题器按键
  VOICE_EVALUATED: 'voice-evaluated', // 语言评测结果(先声))
  AUDIO_RECOGNIZED: 'audio-recognized' // 语音识别结果(百度)
}

cmds - 命令

const cmds = {
  INIT: 'init', // 启用答题器
  ASK: 'ask', // 发题
  TEXT: 'text', // 设置回显
  HI: 'hi', // 控制指令
  STOP: 'stop', // 停止
  DROP: 'drop', // 清理多刷的答题器
  QUIT: 'quit' // 退出 （可能没用）
}

更多信息请参考 ts 定义文件

• index.d.ts

文档

• 答题器IPC协议
• 英语答题器docs