Skip to content

adminkk/homeassistant-demo

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
src/main
src/main
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 
settings.xml
settings.xml
 
 

Repository files navigation

Home Assistant Spring Boot Demo

基于 Spring Boot 的 Home Assistant 智能家居控制中间件，提供 REST API 层用于控制灯光、开关、空调、音箱等智能设备。

技术栈

技术 版本 说明
Spring Boot 3.2.0 核心框架
Java 17 运行环境
Spring WebFlux - WebClient HTTP 客户端
SpringDoc OpenAPI 2.3.0 Swagger UI 接口文档
Lombok - 简化代码

快速开始

1. 克隆项目

git clone https://github.com/your-repo/homeassistant-demo.git
cd homeassistant-demo

2. 配置 Home Assistant 连接

编辑 src/main/resources/application.yml：

server:
  port: 8081

homeassistant:
  url: http://你的HomeAssistant地址:8123
  token: 你的长期访问令牌

获取长期访问令牌：

  1. 登录 Home Assistant
  2. 点击左下角用户头像 → 安全
  3. 滚动到底部 → 创建长期访问令牌

3. 启动项目

# 编译打包
mvn clean package

# 运行应用
mvn spring-boot:run

# 或者直接运行 jar
java -jar target/homeassistant-demo-1.0.0.jar

应用启动后访问 http://localhost:8081

API 文档

项目集成 Swagger/OpenAPI 3 文档：

Swagger UI 提供可视化接口文档，支持在线测试所有接口。

API 接口列表

查询设备

方法 路径 说明
GET /api/devices/states 获取所有实体状态
GET /api/devices/states/{entityId} 获取指定实体状态
GET /api/devices/lights 获取所有灯光
GET /api/devices/switches 获取所有开关
GET /api/devices/sensors 获取所有传感器
GET /api/devices/media-players 获取所有音箱/媒体播放器

设备控制

方法 路径 说明
POST /api/devices/{entityId}/on 打开设备
POST /api/devices/{entityId}/off 关闭设备
POST /api/devices/{entityId}/toggle 切换设备状态

灯光控制

方法 路径 参数 说明
POST /api/devices/{entityId}/brightness value=255 设置亮度 (0-255)
POST /api/devices/{entityId}/color Body: {"r":255,"g":0,"b":0} 设置 RGB 颜色
POST /api/devices/{entityId}/color-temp value=4000 设置色温 (开尔文)

色温参考值：

  • 2700K - 暖白光
  • 4000K - 自然白光
  • 6500K - 冷白光

空调控制

方法 路径 参数 说明
POST /api/devices/{entityId}/temperature value=26 设置温度
POST /api/devices/{entityId}/hvac-mode mode=cool 设置模式

HVAC 模式： off, heat, cool, auto, dry, fan_only

音箱控制

方法 路径 参数 说明
POST /api/devices/{entityId}/text message=你好 播报文本

场景控制

方法 路径 说明
POST /api/devices/scene/{sceneId} 激活场景

自定义服务调用

方法 路径 Body
POST /api/devices/service {"domain":"light","service":"turn_on","entityId":"light.living_room","data":{}}

支持调用任意 Home Assistant 服务，参数说明：

  • domain: 服务域 (light, switch, climate, tts, xiaomi_miio 等)
  • service: 服务名 (turn_on, turn_off, google_translate_say 等)
  • entityId: 实体 ID
  • data: 额外参数（可选）

使用示例

curl 示例

# 获取所有设备状态
curl http://localhost:8081/api/devices/states

# 打开灯光
curl -X POST http://localhost:8081/api/devices/light.living_room/on

# 关闭灯光
curl -X POST http://localhost:8081/api/devices/light.living_room/off

# 设置灯光亮度
curl -X POST "http://localhost:8081/api/devices/light.living_room/brightness?value=128"

# 设置灯光颜色为红色
curl -X POST http://localhost:8081/api/devices/light.living_room/color \
  -H "Content-Type: application/json" \
  -d '{"r":255,"g":0,"b":0}'

# 设置灯光色温 (自然白)
curl -X POST "http://localhost:8081/api/devices/light.living_room/color-temp?value=4000"

# 设置空调温度
curl -X POST "http://localhost:8081/api/devices/climate.living_room_ac/temperature?value=26"

# 设置空调制冷模式
curl -X POST "http://localhost:8081/api/devices/climate.living_room_ac/hvac-mode?mode=cool"

# 音箱播报文本
curl -X POST "http://localhost:8081/api/devices/media_player.living_room/text?message=欢迎回家"

# 激活场景
curl -X POST http://localhost:8081/api/devices/scene/scene.movie_mode

# 自定义服务调用 (小米音箱播报)
curl -X POST http://localhost:8081/api/devices/service \
  -H "Content-Type: application/json" \
  -d '{"domain":"xiaomi_miio","service":"play_text","entityId":"media_player.xiaomi_speaker","data":{"text":"你好，欢迎回家"}}'

Java 代码示例

@RestController
@RequiredArgsConstructor
public class MyController {

    private final HomeAssistantService haService;

    @GetMapping("/demo")
    public void demo() {
        // 设备控制
        haService.turnOn("light.living_room");
        haService.turnOff("switch.bedroom");
        haService.toggle("light.kitchen");

        // 灯光设置
        haService.setLightBrightness("light.living_room", 200);
        haService.setLightColor("light.living_room", 255, 100, 50);
        haService.setLightColorTemp("light.living_room", 4000);

        // 空调控制
        haService.setClimateTemperature("climate.living_room_ac", 26);
        haService.setClimateMode("climate.living_room_ac", "cool");

        // 音箱播报
        haService.playText("media_player.living_room", "欢迎回家");

        // 场景激活
        haService.activateScene("scene.movie_mode");

        // 状态查询
        EntityState state = haService.getState("light.living_room");
        List<EntityState> lights = haService.getAllLights();
    }
}

项目结构

homeassistant-demo/
├── pom.xml                                    # Maven 配置
├── src/main/
│   ├── java/com/example/homeassistant/
│   │   ├── HomeAssistantDemoApplication.java # Spring Boot 启动类
│   │   ├── config/
│   │   │   ├── HomeAssistantProperties.java  # 配置属性绑定
│   │   │   ├── OpenApiConfig.java            # Swagger/OpenAPI 配置
│   │   │   └── WebClientConfig.java          # WebClient HTTP 客户端配置
│   │   ├── controller/
│   │   │   ├── DeviceController.java         # 设备控制 REST 接口
│   │   │   └── GlobalExceptionHandler.java   # 全局异常处理
│   │   ├── dto/
│   │   │   ├── ApiResponse.java              # 统一 API 响应封装
│   │   │   ├── ColorRequest.java             # RGB 颜色请求 DTO
│   │   │   ├── EntityState.java              # Home Assistant 实体状态
│   │   │   └── ServiceCallRequest.java       # 服务调用请求 DTO
│   │   └── service/
│   │       └── HomeAssistantService.java     # Home Assistant 服务层
│   └── resources/
│       └── application.yml                   # 应用配置文件
└── src/test/                                  # 测试目录

架构设计

┌─────────────────┐
│   REST Client   │
└────────┬────────┘
         │ HTTP
┌────────▼────────┐
│ DeviceController│  ← OpenAPI 注解文档
└────────┬────────┘
         │ 调用
┌────────▼────────┐
│HomeAssistantService│  ← callService() 核心调度
└────────┬────────┘
         │ WebClient
┌────────▼────────┐
│  Home Assistant │  ← REST API (Bearer Token)
│   (端口 8123)   │
└─────────────────┘

核心设计：

  • HomeAssistantService.callService() - 统一服务调用入口，支持任意 HA 服务
  • 实体 ID 格式：{domain}.{name}（如 light.living_room）
  • API 响应封装：ApiResponse<T> 统一返回格式

支持的设备类型

域 实体前缀 示例服务
light light. turn_on, turn_off, toggle
switch switch. turn_on, turn_off, toggle
climate climate. set_temperature, set_hvac_mode
media_player media_player. turn_on, turn_off, toggle
text text. set_value (文本显示/播报)
scene scene. turn_on (激活场景)
sensor sensor. 仅查询状态

运行测试

# 运行所有测试
mvn test

# 运行单个测试类
mvn test -Dtest=ClassName

# 运行单个测试方法
mvn test -Dtest=ClassName#methodName

常见问题

连接超时

检查 Home Assistant 地址是否正确，确保网络可达：

curl http://你的HA地址:8123/api/

认证失败

确认 Token 有效，检查 application.yml 配置。

跨域问题 (CORS)

如需前端调用，添加 CORS 配置：

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("*")
                .allowedMethods("*");
    }
}

参考文档

https://developers.home-assistant.io/docs/api/rest/?utm_source=chatgpt.com

许可证

MIT License

About

这是一个 Spring Boot 项目，用于调用 Home Assistant API 控制智能家居设备。

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages