linknlink_device_hub_lib #

LinknLink 设备中心库 - 用于管理设备中心相关功能的 Flutter 库包。

📋 简介 #

linknlink_device_hub_lib 是一个 Flutter 库，提供了统一的设备中心管理功能，支持多种第三方智能家居平台的设备接入和管理。该库使用 Isar 数据库进行本地数据存储，提供了完整的设备信息、实体信息管理能力，以及第三方服务接入的抽象基类。

✨ 开发注意事项 #

服务启动流程中,需要调用updateStatus设置对应服务的运行状态
根据接入服务不同,需要注意是否需要主动来轮询状态
Entity状态发生变化需要调用updateEntityState更新
Entity 不可用,需要讲state更新为unavailable(如:设备离线了)
继承ThirdPartyServiceConfig的类,可以增加对应服务需要的一些配置信息,交给App来配置
生成的LlEntityInfo需要thridPartyType字段. LlDeviceInfo需要serviceId/thridPartyType字段
生成的LlEntityInfo LlDeviceInfo cookie信息中需要设置source_id字段(来源设备的id)

✨ 功能特性 #

🏠 设备信息管理：完整的设备信息存储和管理，支持设备 ID、名称、制造商、型号等属性
🔌 实体信息管理：支持实体（Entity）的状态、属性、能力等信息管理
🔗 第三方服务接入：提供统一的第三方服务接入基类，支持 Home Assistant、小米、涂鸦等平台
💾 本地数据存储：基于 Isar 数据库的高性能本地存储
🍪 设备 Cookie 管理：支持设备认证信息和配置的加密存储
📡 实时状态同步：支持设备状态实时更新和同步
🎮 设备控制：提供统一的设备控制接口
📊 历史记录：支持设备历史记录查询
🔄 流式数据：支持设备列表和实体状态的流式更新
📝 设备注册接口：提供设备注册到 App 的抽象接口

📦 系统要求 #

Dart SDK: >=3.0.0 <4.0.0
Flutter: >=3.0.0

🚀 安装 #

方式一：本地路径依赖 #

在 pubspec.yaml 中添加依赖：

dependencies:
  linknlink_device_hub_lib:
    path: ../linknlink_device_hub_lib

方式二：Git 依赖 #

dependencies:
  linknlink_device_hub_lib:
    git:
      url: https://github.com/yourusername/linknlink_device_hub_lib.git
      ref: main

方式三：Pub.dev（如果已发布） #

dependencies:
  linknlink_device_hub_lib: ^0.0.4

安装依赖：

flutter pub get

📖 快速开始 #

1. 初始化 Isar 数据库 #

import 'package:isar/isar.dart';
import 'package:linknlink_device_hub_lib/linknlink_device_hub_lib.dart';

// 初始化 Isar
final isar = await Isar.open([
  LlDeviceInfoSchema,
  LlEntityInfoSchema,
]);

2. 创建设备信息 #

final device = LlDeviceInfo(
  id: 'device_001',
  name: '客厅智能灯',
  manufacturer: 'Xiaomi',
  model: 'Yeelight',
  thridPartyType: DeviceServiceTypeConst.HA,
  icon: 'mdi:lightbulb',
  areaId: 'area_001',
  serviceId: 'service_001',
);

// 保存到数据库
await isar.writeTxn(() async {
  await isar.llDeviceInfos.put(device);
});

3. 创建实体信息 #

final entity = LlEntityInfo(
  entityId: 'light.living_room',
  name: '客厅灯',
  icon: 'mdi:lightbulb',
  deviceId: 'device_001',
  platform: 'mqtt',
  state: 'on',
  attributes: {
    'brightness': 180,
    'color_temp': 350,
  },
);

// 保存到数据库
await isar.writeTxn(() async {
  await isar.llEntityInfos.put(entity);
});

4. 实现第三方服务接入 #

class MyHomeAssistantService extends ThirdPartyServiceBase {
  MyHomeAssistantService({required super.config});

  @override
  Future<bool> onStart() async {
    // 实现启动逻辑
    // 例如：连接 WebSocket、初始化 API 客户端等
    return true;
  }

  @override
  Future<bool> onStop() async {
    // 实现停止逻辑
    // 例如：关闭连接、清理资源等
    return true;
  }

  @override
  Future<(List<LlDeviceInfo>, List<LlEntityInfo>)> onFetchDeviceEntityList() async {
    // 实现获取设备列表的逻辑
    // 返回 (设备列表, 实体列表)
    return ([], []);
  }

  @override
  Future<List<LlEntityInfo>> onGetEntityStates() async {
    // 实现获取实体状态的逻辑
    return [];
  }

  @override
  Future<bool> onControlDevice(
    String entityId,
    String action, {
    Map<String, dynamic>? data,
  }) async {
    // 实现设备控制逻辑
    return true;
  }

  @override
  Future<List<Map<String, dynamic>>> onGetEntityHistory(
    String entityId, {
    DateTime? startTime,
    DateTime? endTime,
    bool significantChangesOnly = true,
  }) async {
    // 实现获取历史记录的逻辑
    return [];
  }
}

6. 使用第三方服务 #

// 创建服务配置
final config = MyServiceConfig(
  id: 'ha_service_001',
  name: 'Home Assistant',
  serviceType: DeviceServiceTypeConst.HA,
  enabled: true,
);

// 创建服务实例
final service = MyHomeAssistantService(config: config);

// 设置设备注册接口
final deviceRegistry = MyDeviceRegistry(isar: isar);
service.setAppDeviceEntityListRegistryInterface(deviceRegistry);

// 启动服务
await service.start();

// 刷新设备列表
await service.refreshDeviceEntityList();

// 注册设备到 App
final devices = [device1, device2];
final deviceEntities = {
  'device_001': [entity1, entity2],
  'device_002': [entity3],
};
await service.registerDeviceRegistryToApp(devices, deviceEntities);

// 监听设备列表变化
service.deviceListStream?.listen((deviceEntity) {
  final (devices, entities) = deviceEntity;
  print('设备列表更新: ${devices.length} 个设备, ${entities.length} 个实体');
});

// 监听实体状态变化
service.entityStateStream?.listen((entities) {
  for (var entity in entities) {
    print('实体状态更新: ${entity.entityId} - ${entity.state}');
  }
});

// 控制设备
await service.controlDevice('light.living_room', 'turn_on', data: {
  'brightness': 255,
});

📚 核心类说明 #

LlDeviceInfo #

设备信息类，用于存储和管理设备的基本信息。

主要属性：

id: 设备唯一标识
name: 设备名称
manufacturer: 制造商
model: 型号
thridPartyType: 第三方服务类型
icon: 图标
areaId: 区域 ID
serviceId: 服务 ID
connections: 连接信息
identifiers: 标识符列表
cookie: 设备 Cookie（加密存储）

LlEntityInfo #

实体信息类，用于存储和管理实体的状态和属性。

主要属性：

entityId: 实体唯一标识
name: 实体名称
icon: 图标
deviceId: 所属设备 ID
platform: 平台类型
state: 当前状态
attributes: 属性字典
capabilities: 能力信息

ThirdPartyServiceBase #

第三方服务接入抽象基类，提供统一的服务管理接口。

主要方法：

start(): 启动服务
stop(): 停止服务
refreshDeviceEntityList(): 刷新设备列表
syncDeviceEntityStates(): 同步设备状态
controlDevice(): 控制设备
getEntityHistory(): 获取历史记录
setAppDeviceEntityListRegistryInterface(): 设置设备注册接口
registerDeviceRegistryToApp(): 注册设备到 App

状态流：

deviceListStream: 设备列表变化流
entityStateStream: 实体状态变化流

AppDeviceEntityListRegistryInterface #

设备注册抽象接口，定义设备注册到 App 的规范。

主要方法：

registerDevicesAndEntities(): 注册设备和实体到 App

方法签名：

Future<bool> registerDevicesAndEntities({
  required List<LlDeviceInfo> devices,
  required Map<String, List<LlEntityInfo>> deviceEntities,
});

DeviceServiceTypeConst #

服务类型常量定义，支持的服务类型：

HA: Home Assistant
linknlink: LinknLink
xiaomi: 小米
tuya: 涂鸦
ALEXA: Amazon Alexa
GOOGLE: Google Home

🔧 开发说明 #

生成代码 #

如果修改了 Isar 相关的类，需要运行代码生成：

flutter pub run build_runner build --delete-conflicting-outputs

运行测试 #

flutter test

📝 依赖说明 #

主要依赖 #

isar: ^3.1.0 - 高性能本地数据库
isar_flutter_libs: ^3.1.0+1 - Isar Flutter 支持库
logger: ^2.6.1 - 日志工具

开发依赖 #

flutter_test: Flutter 测试框架
flutter_lints: ^6.0.0 - Dart 代码规范检查
build_runner: ^2.4.10 - 代码生成工具
isar_generator: ^3.1.0 - Isar 代码生成器

🤝 贡献 #

欢迎提交 Issue 和 Pull Request！

📄 许可证 #

查看 LICENSE 文件了解详情。

🔗 相关链接 #

项目主页
问题反馈
变更日志

📞 联系方式 #

如有问题或建议，请通过以下方式联系：

提交 Issue
发送邮件

版本: 0.0.4

linknlink_device_hub_lib 1.0.2 linknlink_device_hub_lib: ^1.0.2 copied to clipboard

Metadata