SDK 类

SDK 类是 StreamInd Node.js SDK 的核心入口，用于管理终端连接、发送信号和处理指令。

导入


const { SDK } = require('@streamind/sdk');
// 或 TypeScript/ES6
import { SDK } from '@streamind/sdk';

构造函数


const sdk = new SDK();


const sdk: SDK = new SDK();

创建一个新的 SDK 实例。不需要传入任何参数。

方法

registerTerminal


sdk.registerTerminal(terminalId, config)


registerTerminal(terminalId: string, config: Config): void

注册一个新的终端。

参数：

terminalId (string) - 终端的唯一标识符
config (Config) - 终端的配置对象

示例：


const config = new Config(...);
sdk.registerTerminal('terminal-1', config);

connect


await sdk.connect(terminalId)


async connect(terminalId: string): Promise<void>

异步连接指定的终端到 StreamInd 平台。

参数：

terminalId (string) - 要连接的终端ID

Promise<void> - 连接成功时resolve，失败时reject

异常：

Error - 连接失败时抛出

示例：


try {
  await sdk.connect('terminal-1');
  console.log('连接成功');
} catch (error) {
  console.error('连接失败:', error);
}

connectAll


await sdk.connectAll()


async connectAll(): Promise<Map<string, boolean>>

异步连接所有已注册的终端。

Promise<Map<string, boolean>> - Map 对象，键为终端ID，值为连接是否成功

示例：


const results = await sdk.connectAll();
results.forEach((success, terminalId) => {
  console.log(`${terminalId}: ${success ? '成功' : '失败'}`);
});

disconnect


await sdk.disconnect(terminalId)


async disconnect(terminalId: string): Promise<void>

异步断开指定终端的连接。

参数：

terminalId (string) - 要断开的终端ID

示例：


await sdk.disconnect('terminal-1');

disconnectAll


await sdk.disconnectAll()


async disconnectAll(): Promise<void>

异步断开所有终端的连接。

示例：


await sdk.disconnectAll();

sendSignal


await sdk.sendSignal(terminalId, signal)


async sendSignal(terminalId: string, signal: Signal): Promise<void>

向指定终端发送信号。

参数：

terminalId (string) - 目标终端ID
signal (Signal) - 要发送的信号对象

异常：

Error - 发送失败时抛出

示例：


const signal = new Signal('sensor.data');
signal.getPayload().setNumber('temperature', 25.5);
await sdk.sendSignal('terminal-1', signal);

sendAudioData


await sdk.sendAudioData(terminalId, audioData)


async sendAudioData(terminalId: string, audioData: Buffer): Promise<void>

向指定终端发送 OPUS 格式的音频数据。

参数：

terminalId (string) - 目标终端ID
audioData (Buffer) - OPUS 格式的音频二进制数据

异常：

Error - 发送失败时抛出

示例：


const fs = require('fs');
const audioData = fs.readFileSync('audio.opus');
await sdk.sendAudioData('terminal-1', audioData);

setDirectiveCallback


sdk.setDirectiveCallback(terminalId, callback)


setDirectiveCallback(terminalId: string, callback: (directive: Directive) => void): void

设置接收指令的回调函数。

参数：

terminalId (string) - 终端ID
callback (Function) - 回调函数，接收一个 Directive 参数

回调函数签名：


(directive: Directive) => void

示例：


sdk.setDirectiveCallback('terminal-1', (directive) => {
  console.log('收到指令:', directive.name);
  const payload = directive.getPayload();
  // 处理指令...
});

TypeScript 示例：


sdk.setDirectiveCallback('terminal-1', (directive: Directive) => {
  console.log('收到指令:', directive.name);
  const payload = directive.getPayload();
  const action = payload.getString('action');
  // 处理指令...
});

setConnectionCallback


sdk.setConnectionCallback(terminalId, callback)


setConnectionCallback(
  terminalId: string,
  callback: (status: string, message: string) => void
): void

设置连接状态变化的回调函数。

参数：

terminalId (string) - 终端ID
callback (Function) - 回调函数，接收状态和消息两个参数

回调函数签名：


(status: string, message: string) => void

状态值：

"connected" - 已连接
"disconnected" - 已断开
"reconnecting" - 重连中
"error" - 错误

示例：


sdk.setConnectionCallback('terminal-1', (status, message) => {
  if (status === 'connected') {
    console.log('连接成功');
  } else if (status === 'disconnected') {
    console.log('连接断开:', message);
  } else if (status === 'reconnecting') {
    console.log('正在重连:', message);
  } else if (status === 'error') {
    console.error('连接错误:', message);
  }
});

完整示例

JavaScript


const { SDK, Config, Signal } = require('@streamind/sdk');
 
async function main() {
  // 创建SDK
  const sdk = new SDK();
 
  // 创建配置
  const config = new Config(
    'device-001',
    'sensor',
    'wss://your-platform.com/signals',
    'your-tenant-id',
    'your-product-id',
    'your-secret-key'
  );
 
  // 注册终端
  sdk.registerTerminal('terminal-1', config);
 
  // 设置回调
  sdk.setDirectiveCallback('terminal-1', (directive) => {
    console.log('指令:', directive.name);
  });
 
  sdk.setConnectionCallback('terminal-1', (status, message) => {
    console.log(`状态: ${status}, ${message}`);
  });
 
  // 连接
  await sdk.connect('terminal-1');
 
  // 发送信号
  const signal = new Signal('sensor.data');
  signal.getPayload().setNumber('value', 25.5);
  await sdk.sendSignal('terminal-1', signal);
 
  // 发送音频
  const fs = require('fs');
  const audioData = fs.readFileSync('audio.opus');
  await sdk.sendAudioData('terminal-1', audioData);
 
  // 保持连接
  await new Promise(resolve => setTimeout(resolve, 60000));
 
  // 断开连接
  await sdk.disconnect('terminal-1');
}
 
main().catch(console.error);

TypeScript


import { SDK, Config, Signal, Directive } from '@streamind/sdk';
import * as fs from 'fs';
 
async function main(): Promise<void> {
  const sdk: SDK = new SDK();
 
  const config: Config = new Config(
    'device-001',
    'sensor',
    'wss://your-platform.com/signals',
    'your-tenant-id',
    'your-product-id',
    'your-secret-key'
  );
 
  sdk.registerTerminal('terminal-1', config);
 
  sdk.setDirectiveCallback('terminal-1', (directive: Directive) => {
    console.log('指令:', directive.name);
  });
 
  sdk.setConnectionCallback('terminal-1', (status: string, message: string) => {
    console.log(`状态: ${status}, ${message}`);
  });
 
  await sdk.connect('terminal-1');
 
  const signal: Signal = new Signal('sensor.data');
  signal.getPayload().setNumber('value', 25.5);
  await sdk.sendSignal('terminal-1', signal);
 
  const audioData: Buffer = fs.readFileSync('audio.opus');
  await sdk.sendAudioData('terminal-1', audioData);
 
  await new Promise((resolve) => setTimeout(resolve, 60000));
 
  await sdk.disconnect('terminal-1');
}
 
main().catch(console.error);

线程安全

SDK 类是单线程安全的，适用于 Node.js 的事件循环模型。不要在 Worker Threads 之间共享 SDK 实例。

最佳实践

单一 SDK 实例 - 在应用中使用单个 SDK 实例管理所有终端
错误处理 - 始终使用 try-catch 包裹连接和发送操作
优雅关闭 - 应用退出前调用 disconnectAll()
Promise 链 - 合理使用 async/await 或 Promise 链
回调轻量 - 回调函数中避免阻塞操作