top of page

Aqara ZigBee Sensors for SmartThings - Installing Custom Device Handlers


In the video which follows, I provide you with information about the fantastic benefits that gained via the Aqara sensors. The Aqara Zigbee Door and Window Sensor which I feature in this video is very small in size making it less conspicuous, it is priced less than $20 dollars and it has an extraordinary battery life of at least two years.












Each Aqara sensor requires the installation of Custom Device Handler. The code from these Device Handlers can be obtained from a repository of device code. This source for device code is known as the GitHub Repository.

When it comes to adding the custom device handler code to SmartThings devices, you can either add the code manually or you can create a GitHub account and link that account to SmartThings. Establishing a link between GitHub and your SmartThings account will provide you the ability to easily install new or updated code to your smart devices.


My recommendation is that you setup a GitHub Account and integrate GitHub with SmartThings, by executing the steps listed under Option 1. I provide the steps which you can follow link GitHub in the following paragraphs. However, if you do not plan to create more then a couple custom device handlers and you want an easier approach to install the device handler for the Aqara Door and Window Sensor, then skip down to Option 2.


PLEASE NOTE: If GitHub Integration is Already Enabled within you SmartThings Account then it is very easy to add the bspranger repository to your SmartThings account. Just skip down to the section, 'Add a Repository to the SmartThings IDE' and add the data provided for the 'Owner', 'Name' and 'Branch' fields as instructed.


OPTION 1 - Setting Up A GitHub Account and Integrating GitHub with SmartThings

If you do not have a GitHub Account, I highly recommend that that you get one. It is easy to set up and your account access it gives you free access to many repositories containing many and various SmartThings Device Handlers. To set up your account select 'Create a free organization' from the GitHub plan/pricing page. For more information for obtaining a GitHub account follow the steps provided on the page titled "Signing up for a new GitHub account" or by following the Steps provided by Smart Device Life.


Once you have you GitHub account set up then you need to Enable GitHub Integration with your SmartThings Account. You can follow the instructions in this link to enable this integration just log into you SmartThings Account IDE @ https://account.smartthings.com and then click the Enable GitHub Integration link on the My SmartApps or My Device Types page. This will launch a wizard that will guide you through the process. Then it is just a matter of following Steps 11 through 16 detailed in the content provided by Smart Device Life


This is a one time setup. Going forward you will be able to use the SmartThings Account IDE to easily connect various repositories in order to access the code for various custom device handlers.


How to add a GitHub Repository to your SmartThings IDE

It is very easy to link to a GitHub Repository once GitHub is linked your SmartThings account. You can add a repository by taking the following actions:

  • While in the 'My Device Handlers' tab click on the 'Settings' button

  • Add the following information in the appropriate fields. (Note: this information is specific to bspranger's Xiaomi Aqara repository:

- Owner: bspranger

- Name: Xiaomi

- Branch: master

  • Save the newly added repository by clicking on 'Save' at the bottom


Now you want to click on 'Update from Repo' and select the newly added repository from the dropdown list of repositories.

  • In the next page select the appropriate device handler(s) by placing a checkmark next to the device handler(s) you wish to install

  • Next, check the box next to 'Publish' at the bottom of the list of device handlers and then click on the blue 'Execute Update' button. Your new device handler is now published.

  • In the next page you will tick the box next to the handler ending with 'Xiaomi Aqara Door/Window Sensor'. Be sure to check the box next to 'Publish' and then click on the blue 'Execute Update' button. Your new device handler is now published.

To assign the newly added Device Handler to your SmartThings device, first add your new device to the SmartThings App. Next, log into your SmartThings account and click on the 'My Devices' tab. Now perform the following steps:

  • Find your Aqara device in the list of devices

  • Click on your Device Name

  • Click on the 'Edit' button

  • Expand the dropdown list under 'Type'

  • Select 'Xiaomi Aqara Door/Window Sensor' for your device type handler


Option 2 - Manual

(Manually install a Device Handler by Copying and Pasting the RAW Code )

If you prefer not to setup a GitHub Account you can easily install the Device Handler using the RAW GitHub Code. I will provide the links to the RAW code for the device handlers of each SmartThngs compatible Aqara sensor for your convenience.


To manually install the device handlers:

  • login to your SmartThings Account at https://account.smartthings.com (this is also referred to as the SmartThings IDE), and

  • go to “My Device Handler”.

  • Click on “Create a New Device Handler” button on the top right.

  • Select the “From Code” tab.

  • Click on the appropriate Aqara device link below to access the specific code that you want to copy.

  • Use your mouse to click on the code text and then hold down on the control 'Ctrl' key on you keyboard and while holding the Ctrl key tap the 'A' key. This will select all text for the RAW code.

  • Now copy the text and go back to your SmartThings account and paste the relevant code in the white space under the "From Code" tab.

  • Then click 'Save' and then “Publish” and “For Me”. Repeat these steps if you want to add other device handlers for different Aqara sensors.

Links to Aqara Sensor RAW Code

  • Xiaomi Aqara Motion Sensor – here

  • Xiaomi Aqara Contact Sensor – here

  • Xiaomi Aqara Temperature/Humidity Sensor – here

  • Xiaomi Zigbee Button – here

  • Xiaomi Aqara Leak Sensor - here

To assign your new device handler to your device, first add your device to the SmartThings App and then login to your SmartThings IDE Account and find click on the 'My Devices' Tab. Now perform the following steps:

  • Find your Aqara device in the list of devices

  • Click on your Device Name

  • Click on the 'Edit' button

  • Expand the dropdown list under 'Type'

  • Select 'Xiaomi Aqara Door/Window Sensor' for your device type handler

If this article helped you please remember to give it a like.




bottom of page