0x100 / mi-home-api

REST and Java API for interacting with Xiaomi Smart Home devices

REST and Java API for interacting with Xiaomi Smart Home devices

Capabilities

Devices supported by the API which connect to a gateway through Zigbee:

• Xiaomi Door and Window Sensor
• Xiaomi Button
• Xiaomi Plug (Socket)
• Xiaomi Magic Cube
• Xiaomi Motion Sensor

Built-in into the gateway:

• Xiaomi Gateway Light
• Xiaomi Gateway Illumination Sensor

Build and run

cd api
mvnw spring-boot:run

Requirements

• JDK 11. Check the compiler version with javac -version or mvnw -version.
• Maven 3.2+ (or use the Maven wrapper mvnw supplied with the project).

Docker

Docker file location:

/api/Dockerfile

Build image

cd api
mvnw dockerfile:build

Run

docker run com/mihome-api:latest

Examples

See examples of using the Java API in the samples module.

Rest API

After run the application you can find the Rest API at http://localhost:8080/v1/. Now it contains methods:

• GET /devices - list known devices.
• GET /devices/type/{type} - list known devices of the specified type. The type variable can take values:

XIAOMI_CUBE
XIAOMI_DOOR_WINDOW_SENSOR
XIAOMI_SOCKET
XIAOMI_MOTION_SENSOR
XIAOMI_SWITCH_BUTTON

• POST /devices/subscribe - subscribe on events from a specified device. Request params example:

{
  "deviceSid" : "a22b4b5b6c7cc0d",
  "webHookUrl" : "http://localhost:8081/callback"
}

deviceSid param takes a unique SID of the device to subscribe (you can get it from the methods above).

webHookUrl param takes the URI which will called on firing any event at the subscribed device. That URI must take following parameters:

{
  "deviceSid" : "Device SID",
  "action": "Name of the fired event (action)"
}

How to contribute

Fork the repository, make changes, write a test for your code, send me a pull request. I will review your changes and apply them to the master branch shortly, provided they don't violate quality standards. To avoid frustration, before sending a pull request please run the Maven build:

$ mvnw clean package

Good luck and have fun!

mi-home-api's Issues

Add examples

Java client (in the form of Spring Boot starter) for interacting with REST API

Update the Overview

Develop a telegram bot

Add /devices controller

Add Spring / Maven support

Divide app into modules

core
rest-api
telegram-bot
web
samples

Migrate to JDK 11

Failed to execute goal on project rest-api: Could not resolve dependencies for project com.mihome:rest-api:jar:0.1-SNAPSHOT: Could not find artifact com.mihome:core:jar:0.1-SNAPSHOT

I run command mvn spring-boot:run

But this error appear: Failed to execute goal on project rest-api: Could not resolve dependencies for project com.mihome:rest-api:jar:0.1-SNAPSHOT: Could not find artifact com.mihome:core:jar:0.1-SNAPSHOT

I tried to find this library, to see actual version, but could't get any library like this one:

<groupId>com.mihome</groupId>
        <artifactId>mi-home-api</artifactId>
        <version>0.1-SNAPSHOT</version>

Do I do something wrong ?

Add Rest API documentation

Add Maven wrapper

Add Docker distribution