ReAIHDConnect ReAI硬件连接

概述

一个用于与设备通过 MQTT/WebSocket 进行通信的接口。它提供了一系列方法，允许开发者注册回调函数以处理设备状态更新和消息接收，同时支持与指定设备建立安全的连接，发送消息请求和响应。

安装

npn i @re-ai/hd-connect

接口方法说明

export interface IHDConnect {

    /**
     * 注册一个回调函数来处理设备状态更新
     * 
     * @param callback 当设备状态更新时会触发的回调函数，接收一个HDDevice参数
     *                 开发者可以在回调函数内处理设备状态的变化
     */
    onDeviceStatus(callback: (device: HDDevice) => void): void

    /**
     * 注册一个消息接收回调函数，当有消息接收到时将被调用
     * 
     * @param callback - 回调函数，包含设备ID和消息请求对象作为参数
     *        设备ID用于标识接收消息的设备，消息请求对象包含消息的具体内容和元数据
     */
    onMessageReceived(callback: (deviceId: string, message: MessageRequest) => void): void

    /**
     * 建立WebSocket安全连接到指定设备
     * 
     * @param deviceId - 目标设备的唯一标识符
     * @param ws - 已初始化的WebSocket实例，将被用于与设备通信
     */
    wssConnect(deviceId: string, ws: WebSocket): void

    /**
     * 服务器主动向指定设备发送消息指令
     * 
     * @param deviceId 设备的唯一标识符，用于定位目标设备
     * @param message 消息请求对象，包含要发送给设备的具体消息内容
     * @param callback 可选参数，用于处理消息请求后的响应或结果的回调函数
     */
    messageRequest(deviceId: string, message: MessageRequest, callback?: (data: any) => void): void

    /**
     * 服务端向指定设备发送消息响应
     * 
     * @param deviceId 设备ID，用于标识接收消息响应的设备
     * @param message 消息内容，是设备期望接收的信息对象
     */
    messageResponse(deviceId: string, message: MessageResponse): void

     /**
     * 发送配置到指定设备
     * 
     * 
     * @param deviceId 目标设备的唯一标识符
     * @param conf 要发送的配置信息，可选
     */
    messageSendConf(deviceId: string, conf?: Record<string, any>): void
}

使用示例

import { WebSocket } from 'ws'
import { HDDevice, MessageRequest, MessageResponse, ReAIHDConnect } from '@re-ai/hd-connect'
import { v4 } from 'uuid'
const hdConnect = ReAIHDConnect({
    appId: "testAppId",
    mqtt: {
        address: "",
        username: "",
        password: ""
    }
})

// 监听设备状态
hdConnect.onDeviceStatus((device: HDDevice) => {
    console.log(device)
    // 去处理设备的状态
    if (device.status === 'online') {
        // 处理设备上线

        // 给设备发送配置，默认会带上appId  
        hdConnect.messageSendConf(device.deviceId)

    } else if (device.status === 'offline') {
        // 处理设备下线
    }
    
})

// 监听硬件主动发起的消息请求
hdConnect.onMessageReceived((deviceId: string, message: MessageRequest) => {
    console.log(deviceId, message)
    const msgId = message.params._id // 消息id

    // 服务端回复消息
    hdConnect.messageResponse(deviceId, {
        id: v4(),
        result: {
            method: 'reply_once',
            content: {
                _id: msgId,
                type: "text",
                text: 'hello world'
            }
        }
    })
})

// 需要传入一个websocket实例
// const wss: WebSocket = ???
hdConnect.wssConnect('deviceId', wss)

// 服务端主动给硬件发送消息指令
hdConnect.messageRequest('deviceId', {
    id: v4(),
    method: 'send_once',
    params: {
        _id: v4(),
        type: "action",
        actionData: {
            name: "infoGet",
            arguments: JSON.stringify({
                "key": "base"
            })
        }
    }
}, (data: MessageResponse) => {
    const msgId = data.result.content._id // msgId = params._id
    console.log(msgId, data)
})

单条文本回复给硬件

hdConnect.messageResponse('deviceId', {
    id: v4(),
    result: {
        method: 'reply_once',
        params: {
            _id: v4(),
            type: 'text',
            text: 'hello world'
        }
    }
})

多段文本发送给硬件

// 发送多段文本消息
const msgId = "msgId" // 消息id
const hdID = "deviceId" // 设备id
let msgIndex = 0 // 消息index

// 开始消息
hdConnect.messageResponse(hdID, {
    id: v4(),
    result: {
        method: "reply_start",
        content: {
            _id: msgId,
            index: msgIndex,
            type: "text",
            text: 'hello world'
        }
    }
})
msgIndex++ // 消息index+1

for (let i = 0; i < 10; i++) {
    hdConnect.messageResponse(hdID, {
        id: v4(),
        result: {
            method: "reply_on",
            content: {
                _id: msgId,
                index: msgIndex,
                type: "text",
                text: `这是第${msgIndex}段话`
            }
        }
    })
    msgIndex++ // 消息index+1
}

// 结束消息
hdConnect.messageResponse(hdID, {
    id: v4(),
    result: {
        method: "reply_end",
        content: {
            _id: msgId,
            index: msgIndex,
            type: "text",
            text: 'hello end'
        }
    }
})

环境变量

|变量名|描述|默认值| |----|-----|-----| |REAI_MQTT_SERVER_URL|MQTT服务器地址|| |REAI_MQTT_USERNAME|MQTT用户名|| |REAI_MQTT_PASSWORD|MQTT密码||