StarCloud Flutter SDK

Flutter 智能锁接入 SDK。SDK 封装了星云账户、蓝牙扫描和配对、锁管理、凭证管理、网关 WiFi 配网、锁状态/设置，以及视频对讲信令与媒体数据事件。

当前交付面向 Android 和 iOS；不提供 macOS、Windows、Linux 或 Web 的桌面端支持。

交付内容

实际交付根目录包含下列五个同级目录。flutter_sdk 通过相对路径依赖前三个底层包；video_decode_plugin 是示例工程的视频渲染可选组件：

vendor/
├── flutter_sdk/       # 本 SDK
├── starlock_ble/      # 蓝牙协议与设备连接层
├── starcloud/         # 云端、设备与领域模型
├── starchart/         # 视频对讲信令与传输层
└── video_decode_plugin/ # 可选：示例使用的 H264 FFmpeg 渲染插件

example/ 是可运行的集成示例，覆盖常用的接入路径。不要将示例中的测试账号、日志或 UI 直接用于生产环境。

环境与平台要求

项目	要求
Flutter	3.19.6 或更高版本
Dart	3.3.0 或更高版本
Android	minSdkVersion 23，真机蓝牙调试
iOS	iOS 12.0 或更高版本，真机调试
网络	可访问已获授权的星云服务和视频对讲服务

蓝牙扫描、配对、门锁控制、WiFi 配网、麦克风和相机相关能力均需要在真机验证。模拟器不具备完整的蓝牙能力。

安装

将 flutter_sdk、starlock_ble、starcloud、starchart 放入宿主 App 的 vendor/。需要使用示例同款 FFmpeg 视频渲染时，再一并放入 video_decode_plugin。

宿主 pubspec.yaml 的最小依赖只需要声明 flutter_sdk：

dependencies:
  flutter:
    sdk: flutter

  flutter_sdk:
    path: vendor/flutter_sdk

flutter_sdk 的 pubspec.yaml 已通过 path: ../starlock_ble、../starcloud、../starchart 引用同级底层包，因此宿主执行一次依赖安装即可递归解析全部核心包：

fvm flutter pub get

如需将示例的 H264 FFmpeg 解码渲染带入宿主 App，额外声明：

  video_decode_plugin:
    path: vendor/video_decode_plugin

然后仍只需要在宿主 App 根目录再执行一次 fvm flutter pub get。不需要为正常集成专门进入 video_decode_plugin、starlock_ble、starcloud 或 starchart 逐个执行 pub get；只有开发/测试这些包自身或运行它们的独立 example 时才需要。

如果项目不使用 FVM，请使用与本 SDK 兼容的 Flutter 版本执行 flutter pub get。

平台配置

Android

确认 android/app/build.gradle 的最小版本不低于 23，并在 android/app/src/main/AndroidManifest.xml 添加按业务实际需要的权限：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

• 仅使用锁管理时，麦克风、相机权限可不声明。
• Android 12 及以上需要在运行时申请 BLUETOOTH_SCAN、BLUETOOTH_CONNECT。
• 若视频对讲服务使用 http:// 地址，Android 需要允许明文流量；生产环境建议使用 HTTPS。

iOS

在 ios/Podfile 中设置：

platform :ios, '12.0'

在 ios/Runner/Info.plist 添加适合实际业务的用途说明：

<key>NSBluetoothAlwaysUsageDescription</key>
<string>用于扫描和连接智能锁。</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>用于连接智能锁设备。</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>用于发现附近的蓝牙智能锁。</string>
<key>NSMicrophoneUsageDescription</key>
<string>用于视频对讲。</string>
<key>NSCameraUsageDescription</key>
<string>用于视频对讲和扫码功能。</string>

完成后执行：

cd ios && pod install && cd ..

接入顺序

常规业务建议严格按以下顺序执行：

bootstrap
  → auth.init
  → createCloudUser / setCloudAccounts
  → 扫描、配对或获取锁列表
  → 构建 StarCloudLockContext
  → 锁控制、凭证、WiFi 配网或视频对讲

CloudUserInfo 是扫描、配对及云端锁管理的前提；lock.skychip.top 的 WiFi 授权登录令牌仅用于网关配网，不能替代 SDK 云账户。

快速接入

1. 创建客户端并初始化认证

应用启动时只调用一次 bootstrap()：

import 'package:flutter/widgets.dart';
import 'package:flutter_sdk/starcloud_flutter_sdk.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  StarCloudClient.bootstrap();
  runApp(const MyApp());
}

从星云后台注册应用并获取 clientId、clientSecret。不要把密钥提交到代码仓库；建议由业务后端下发或通过构建参数注入：

const clientId = String.fromEnvironment('STARCLOUD_CLIENT_ID');
const clientSecret = String.fromEnvironment('STARCLOUD_CLIENT_SECRET');
const environmentUrl = String.fromEnvironment('STARCLOUD_ENV_URL');

StarCloudClient.instance.auth.init(
  clientId: clientId,
  clientSecret: clientSecret,
  environmentUrl: environmentUrl,
);

例如：

fvm flutter run \
  --dart-define=STARCLOUD_CLIENT_ID=your_client_id \
  --dart-define=STARCLOUD_CLIENT_SECRET=your_client_secret \
  --dart-define=STARCLOUD_ENV_URL=https://your-authorized-host

2. 设置 SDK 云账户

生产环境应由业务后台保存、恢复并下发合法的 CloudUserInfo。仅在联调或示例中，可创建临时云账户：

final cloudUser = await StarCloudClient.instance.auth.createCloudUser();
StarCloudClient.instance.auth.setCloudAccounts([cloudUser]);

若有多个云账户，使用 setCloudAccounts 一次性设置，并在设备业务 API 中按需传入 cloudUid。

3. 扫描、配对与锁控制

final devices = await StarCloudClient.instance.device.scanDeviceList(
  timeout: 10,
  onScan: (list) {
    // 可持续刷新扫描列表
  },
);

if (devices.isEmpty) return;

final lock = await StarCloudClient.instance.device.pairDevice(
  scanResult: devices.first,
);

await StarCloudClient.instance.device.openLock(lockId: lock.lockId);
await StarCloudClient.instance.device.closeLock(lockId: lock.lockId);

扫描页应直接为每个扫描结果提供“配对”操作；若本地已配对锁的 mac 或蓝牙设备名与扫描结果一致，应展示“已配对”而非再次配对。离开页面或用户取消时调用：

await StarCloudClient.instance.device.stopScan();
await StarCloudClient.instance.device.disconnect();

已配对设备可从云端获取：

final list = await StarCloudClient.instance.device.getDeviceList(
  pageNo: 1,
  pageSize: 20,
);
final latestLock = await StarCloudClient.instance.device.getDevice(
  lockId: lock.lockId,
);

4. 使用 StarCloudLockContext

高级 BLE 接口（状态、功能位、网关配网）需要锁身份、蓝牙密钥和本地握手 token。请从已配对或已查询到的 StarCloudLock 构建上下文，不要自行拼装密钥：

final context = await StarCloudLockContext.fromLock(latestLock);

final state = await StarCloudClient.instance.lockState
    .readLockStateByContext(context);

await StarCloudClient.instance.lockSetting.setRemoteUnlockByContext(
  context,
  enabled: true,
);

上下文依赖已经完成的蓝牙认证握手；token 缺失或过期时，应重新连接/配对并获取最新锁信息后重试。

5. 网关 WiFi 配网

网关配网需要：已配对的网关锁、SDK 云账户、锁主账号或管理员账号的 WiFi 授权令牌，以及 App 视频对讲 PeerID。

先登录 WiFi 授权服务：

final accessToken = await StarCloudClient.instance.auth.loginLockService(
  username: username,
  password: password,
  deviceBrand: 'android',
  deviceModel: 'model-name',
  deviceVersion: 'os-version',
);

初始化视频对讲以取得 App PeerID（见下一节），随后执行：

final context = await StarCloudLockContext.fromLock(lock);
final reply = await StarCloudClient.instance.wifi.configureWifiByContext(
  context,
  ssid: ssid,
  password: password,
  lockServiceAccessToken: accessToken,
  deviceName: lock.bluetooth.bluetoothDeviceName,
  mac: lock.mac,
);

// 配网响应包含锁端 peerId；仍需轮询云端确认锁上线。
final status = await StarCloudClient.instance.wifi.getGatewayStatus(
  lockId: lock.bluetooth.bluetoothDeviceName,
  userId: context.userId,
  deviceName: lock.bluetooth.bluetoothDeviceName,
  mac: lock.mac,
);

configureWifiByContext 会获取网关配置、通过 BLE 下发，并向云端提交设备网络信息。BLE 返回成功只表示流程已接受，不代表锁已联网；请使用 getDevice(lockId: ...) 轮询 isOnline 与 peerId。

6. 视频对讲

视频对讲服务只负责注册、呼叫和事件分发；H264 解码渲染、G711 编解码、麦克风采集与权限处理由宿主 App 集成。示例工程使用本地 video_decode_plugin 的 FFmpeg 后端进行 H264 解码渲染。

await StarCloudClient.instance.talk.init(
  productName: 'YourApp',
  unique: deviceUniqueId,
  baseUrl: 'http://scd.skychip.top:8710',
);

final appPeerId = StarCloudClient.instance.talk.myPeerId;

先订阅事件，再响应来电、视频协商与状态：

final incomingSub = StarCloudClient.instance.talk.onIncomingCall.listen((call) {
  // 展示接听/拒绝 UI
});

final mediaSub = StarCloudClient.instance.talk.onTalkData.listen((event) {
  // event.isAudio：G711 音频；否则为视频数据，交给宿主解码器
});

final expectSub = StarCloudClient.instance.talk.onTalkExpectResp.listen((event) {
  // 根据 width、height、rotate 与 videoType 重建/调整渲染器
});

final statusSub = StarCloudClient.instance.talk.onTalkStatus.listen((event) {
  // 根据 TalkStatus 更新 UI 与资源生命周期
});

主动监控、接听和挂断：

StarCloudClient.instance.talk.requestCall(
  lockPeerId: lockPeerId,
  callerName: 'YourApp Monitor',
  options: const TalkOptions(
    preferredVideoTypes: [VideoTypeE.H264],
    preferredAudioTypes: [],
  ),
);

StarCloudClient.instance.talk.accept(lockPeerId: incomingCall.lockPeerId);
StarCloudClient.instance.talk.hangup(lockPeerId: lockPeerId);

停止使用时取消订阅并释放宿主侧解码器、录音和播放器；在应用彻底退出视频对讲模块时调用 StarCloudClient.instance.talk.dispose()。

服务一览

服务	入口	典型能力
认证	auth	初始化、SDK 云账户、WiFi 授权登录
设备	device	扫描、配对、锁列表、开关锁、重置
密码	password	查询、在线/离线密码、重置
卡片/生物识别	card、biometric	IC 卡、指纹、人脸管理
电子钥匙	electricKey	查询、新增、编辑、冻结、删除
记录	record	查询与上报锁记录
状态/设置	lockState、lockSetting	锁状态、功能位读取与设置
WiFi	wifi	WiFi 搜索、网关/锁板配网、网关状态
视频对讲	talk	注册、来电、呼叫、媒体事件、挂断

高级 BLE 同类请求应串行发送，避免多个相同 Reply 类型的命令同时在途导致响应匹配错误。

示例工程

示例位于 example，当前操作顺序为：

1. 登录页注册星云应用，填写 client_id 与 client_secret 并初始化 SDK；创建测试云账户或接入业务账户。
2. 在设备扫描页扫描、直接配对门锁。
3. 在 WiFi 配网页完成“第 1 步：初始化视频对讲”，然后输入 WiFi 名称/密码并执行“第 2 步：WiFi 配网”。
4. 在视频对讲页对已联网且有 peerId 的锁发起监控，或处理来电。

故障排查

现象	优先检查
auth.init 或 createCloudUser 失败	clientId、clientSecret、授权环境地址与网络连通性
扫描不到锁	真机蓝牙/定位已开启，运行时权限已授予，锁处于可发现状态
配对或高级 BLE 命令超时	设备距离、蓝牙连接、锁的认证握手及 StarCloudLockContext token
WiFi 配网成功但无法监控	配网后等待锁上线，轮询锁详情确认 isOnline == true 且 peerId 非空
视频无画面	确认对讲已初始化、锁端协商到 H264、宿主解码器已处理 SPS/PPS/关键帧与旋转比例
iOS 编译失败	Podfile 最低版本、权限声明和 pod install 是否完成

提交支持请求时，请提供 Flutter 版本、设备型号/系统版本、操作时间、脱敏后的完整日志、锁型号和最小复现步骤。请不要提交 clientSecret、访问令牌、私钥或完整用户信息。

安全与发布

• clientSecret、WiFi 授权令牌、蓝牙密钥和视频对讲凭据均为敏感数据，不得写入日志或提交版本库。
• 生产环境应由业务后端管理应用凭据与用户身份，不建议在客户端内置长期密钥。
• 上线前请使用正式包名、签名、隐私政策和实际权限用途说明；按应用商店要求审核蓝牙、定位、相机与麦克风权限。
• SDK 功能与门锁固件、账号权限和已开通服务相关；请在量产前完成真实锁、弱网和异常断连测试。

支持

联系技术支持时请附上项目名称、SDK 版本、目标平台、问题模块和上述脱敏诊断信息。