tdabasinskas / powershell-xiaomi

PowerShell module to interact with developer-unlocked Xiaomi Mi Smart Home devices

Xiaomi Smart Home PowerShell Module

Description

This is a PowerShell module, which allows programmatic interaction with Xiaomi Mi Smart Home devices. The module contains a group of functions, that you can easily integrate with other scripts and tools in order to work with the information provivided by the Xiaomi Smart Home sensors. One of such cases can be using this module to regularly query the temperature data from the temperature sensor and then passing that data to some other script / tool which can draw temperature graphs.

Currently, the number of supported devices is limited, as well as only read-only actions are supported. However, there are plans to provide support for additional sensors in the near future.

Prerequisites

1. For starters, you need to have a Xiaomi Mi Smart Home Gateway.
2. You'll likely want to have at least one sensor, e.g. temperature/humidity one, as well.
3. To be able to access the gateway over network, you must have the developer mode unlocked. This can be done by following these steps:
4. Download the latest version of MiHome application to your Android device (yes, at the moment, developer mode can be enabled only via Android).
5. Follow the in-app instructions to connect the application to your Xiaomi Mi Smart Home Gateway.
6. Once the Gateway is added, open the Gateway settings and navigate to the About section.
7. At the bottom of the About section, there should be the version number listed. Click it multiple times until you see to additional options (both in Chinese) appearing above.
8. Click the first new option (the one with the longer Chinese name).
9. Take a note of the 16 symbol key you see on the second line. You might need this key for the write operations.
10. Activate the first option and click the right Chinese button (probably meaning OK) at the bottom. The developer mode should be active now.
11. You also need Windows Management Framework 5.0 (or above) to use the module.

Installation

The module is published in PowerShell Gallery repository, so the easiest way to install it is from there. Simply run the following command in you PowerShell prompt:

Install-Module -Name Xiaomi;

In case the above installation using the package manager fails, you can install the module manually. Simply download the latest version of the module and extract the Xiaomi-master folder into the folder, which is included in your $ENV:PSModulePath, e.g. %USERPROFILE%\Documents\WindowsPowerShell\Modules. Make sure to rename Xiaomi-master to Xiaomi afterwards.

To confirm the module is successfully installed and see all the available functions, use the following command:

Get-Command -Module Xiaomi;

Functions

Currently, the module contains the following functions:

• Connect-XiaomiSession
• Disconnect-XiaomiSession
• Get-XiaomiGateway
• Get-XiaomiSensor
• Get-XiaomiTemperature

Examples

Getting the key information about the gateway(s)

The following example can be used as the simplest test to see if all (any) gateway devices on the network are reachable.

# Initate the connection:
$Connection = Connect-XiaomiSession;
# Get the gateway(s) information:
$Connection | Get-XiaomiGateway;
# Close the connection:
$Connection | Disconnect-XiaomiSession;

Getting the list of sensors attached to the gateway(s)

This example shows how to get the list of all the sensors attached to the gateway(s). It might be a good idea to run it to make sure that all the sensors are discovered, before performing any actions on them.

# Initate the connection:
$Connection = Connect-XiaomiSession;
# Get the gateway(s) and all the sensors attached the each of them:
$Connection | Get-XiaomiGateway | Get-XiaomiSensor;
# Close the connection:
$Connection | Disconnect-XiaomiSession;

Keep querying temperature and humidity information every 10 seconds:

This is a more detailed example, which keeps querying data from the temperature sensors every few seconds. Also, this time we are passing the parameters to the functions directly, instead providing them via a pipeline as in the previous examples.

# Initate the connection:
$Connection = Connect-XiaomiSession;
# Get the gateway(s):
$Gateway = Get-XiaomiGateway -Connection $Connection;
# Get all the sensors:
$Sensor = Get-XiaomiSensor -Gateway $Gateway;
# Keep querying and printing temperature/humidity every 10 seconds:
While ($TRUE) {
    Get-XiaomiTemperature -Sensor $Sensor | FT;
    Start-Sleep -Seconds 10;
}
# Close the connection:
$Connection | Disconnect-XiaomiSession;

References

The following resources were invaluable in writing this PowerShell module:

• https://github.com/jon1012/mihome
• https://notes.jmsinfor.com/blog/post/admin/Xiaomi-Hub
• https://louiszl.gitbooks.io/lumi-gateway-local-api/content/
• http://bbs.xiaomi.cn/t-13198850
• https://github.com/rockmanqh/blynk-aquara

Thank you!

powershell-xiaomi's Issues

Images for README

WriteErrorException

First of all, absolutely great work.

Now the issue: Get-XiaomiGateway throws with this:

+ CategoryInfo : ProtocolError: (:) [Write-Error], WriteErrorException
+ FullyQualifiedErrorId : Microsoft.PowerShell.Commands.WriteErrorException,Get-XiaomiGateway

Is it maybe related to the 16 symbol key you mention in the prerequisites, the one shown after activating developer mode? Where do I use that?