{"id":19260967,"url":"https://github.com/lukaszlapaj/airpurifierdriver","last_synced_at":"2025-04-21T17:30:34.173Z","repository":{"id":42034626,"uuid":"174682413","full_name":"LukaszLapaj/AirPurifierDriver","owner":"LukaszLapaj","description":"An improved driver for Xiaomi Air Purifier 2/2S automation.","archived":false,"fork":false,"pushed_at":"2023-04-30T15:10:24.000Z","size":370,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-01T14:45:56.547Z","etag":null,"topics":["air-purifier","airly","airly-api","airpurifier","database","hysteresis","javascript","nodejs-script","purifier","smog","xiaomi","xiaomi-smart-home"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukaszLapaj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-03-09T10:55:39.000Z","updated_at":"2022-04-16T17:54:31.000Z","dependencies_parsed_at":"2024-11-09T19:24:55.826Z","dependency_job_id":"f4df5005-1fa4-493c-859f-ea3ed583818d","html_url":"https://github.com/LukaszLapaj/AirPurifierDriver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukaszLapaj%2FAirPurifierDriver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukaszLapaj%2FAirPurifierDriver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukaszLapaj%2FAirPurifierDriver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukaszLapaj%2FAirPurifierDriver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukaszLapaj","download_url":"https://codeload.github.com/LukaszLapaj/AirPurifierDriver/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250100158,"owners_count":21374881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["air-purifier","airly","airly-api","airpurifier","database","hysteresis","javascript","nodejs-script","purifier","smog","xiaomi","xiaomi-smart-home"],"created_at":"2024-11-09T19:23:54.837Z","updated_at":"2025-04-21T17:30:34.160Z","avatar_url":"https://github.com/LukaszLapaj.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Xiaomi Air Purifier 2/2S Driver\nAn improved driver for Xiaomi Air Purifier 2/2S automation.\n\n# Features:\n- Multi-device support\n- Hysteresis\n- Force turn on / favourite mode\n- Display settings\n- Day/Night mode\n- Day/Night cooling\n- Unconditional speed boost\n- Low/Critical humidity warning\n- High temperature warning\n- Low temperature protection\n- Highly customisable speed\n- Database logger\n- Airly logger\n\n## Hysteresis\nOne of the best features of this script is the built-in implementation of [hysteresis](https://en.wikipedia.org/wiki/Hysteresis). This allows for preventing unwanted frequent speed changes. \nThe standard version only helps with +/- 1 level differences. This one is highly recommended for everybody to reduce speed and possible Air Purifier wear due to constant jumping between speed levels.\nThere is also a more advanced/conservative version, which is turned on by default as well. This one prevents big speed jumps, when there is a possibility, that they are unwanted.\n\n#### Examples\n- When going from level 1 to 14, there will be created an additional step at level 8, to check if the pollution around purifier is still rising, to make sure it’s not a false alarm.\n- When the device was running at a high level for a while, and this will be followed by a sudden drop in pollution. The speed of the purifier will at first drop in half, to make sure it’s not a false alarm.\n\n## Multi-device support\nGo to `devices.json` and add devices duplicating first entry, like this:\n```\n  {\n    \"name\": \"\",\n    \"ip\": \"192.168.0.222\",\n    \"token\": \"123\",\n    \"minSpeed\": 0,\n    \"maxSpeed\": 14,\n    \"hysteresisStack\": [],\n    \"debug\": {}\n  },\n  {\n    \"name\": \"\",\n    \"ip\": \"192.168.0.223\",\n    \"token\": \"456\",\n    \"minSpeed\": 0,\n    \"maxSpeed\": 14,\n    \"hysteresisStack\": [],\n    \"debug\": {}\n  }\n```\n#### Remember: \n- Separate devices on a list with a comma, like in the example\n- Only first device on the list will be logging to database\n\n## Unconditional speed boost\nIf you feel that the device is temporary running too slow at all pm2.5 levels, you can enable this feature at any time, and set the preferred boost level.\n```\nunconditionalBoost: false\nunconditionalBoostLevel: 0\n```\n\n## Low-temperature protection\nWhen the temperature in the room drops below a certain value, you may want to set it on the slowest possible speed.\nThis might be helpful when the device is standing very close to you, and the sensed room temperature in combination with a breeze from the purifier fan is becoming unpleasant.\n```\npreventLowTemperature: false\npreventLowTemperatureThreshold: 24.8\npreventLowTemperatureSpeed: 0\n```\n\n## Cooling down and high-temperature warning\nWhen the sensed temperature in the room is too high, you can use your device to improve air circulation and create some pleasant breeze. \n`dayCoolingDownThreshold` is the temperature at which the purifier will start ramping up the speed. At every `dayTempBetweenLevels` speed will be increased by 1 level.\nWhen the speed will rise by `preventHighTemperatureMultiplier` levels, the purifier will start beeping reminding you to take other possible steps.\n\nThis can be set separately for day and night with different settings.\n```\n\"dayEnableCoolingDown\": true\n\"dayCoolingDownThreshold\": 26.5\n\"dayTempBetweenLevels\": 0.6\n\"preventHighTemperature\": true\n\"preventHighTemperatureMultiplier\": 5\n```\n\n```\n\"nightEnableCoolingDown\": true\n\"nightCoolingDownThreshold\": 27.0\n\"nightTempBetweenLevels\": 0.4\n```\n\n## Low/Critical humidity warning\nCarbon purifier filters tend to accumulate some moisture and decrease room humidity. \nThis setting will allow sacrificing air quality to save some moisture at extremely low levels.\nAt `lowHumidityThreshold` purifier will slow down by 1 level, and below criticalHumidityThreshold, the device will stay on level 0.\n```\n\"preventLowHumidity\": true\n\"lowHumidityThreshold\": 30\n\"criticalHumidityThreshold\": 28\n```\n## Day / night mode\nAirPurifierDriver allows you to set different speeds at certain pollution level separately for day and night.\nWith night mode is turned on, purifier display will be turned off, until pollution level is below `criticalPM25Display`.\nRelevant variables:\n```\n\"enableNightMode\": true\n\"disableLedAtNight\": true\n\"criticalPM25Display\": 25\n```\n\n# Requirements\n- Postgres SQL Server\n- Node.js 18+\n\n# Install\n```\ngit clone -b master https://github.com/LukaszLapaj/AirPurifierDriver.git\nnpm install\n```\n\n# Configuration\nGo to `devices.json` and set necessary information:\n```\n\"ip\": \"AIR PURIFIER IP ADDRESS\";\n\"token\" \"AIR PURIFIER ACCESS TOKEN\"\n```\nGo to `config.json` and set necessary information:\nIf You want to use Airly measurements:\n```\n\"airlyApiKey\": \"AIRLY API KEY\";\n\"latitude\": \"LATITUDE\";\n\"longitude\": \"LONGITUDE\";\n```\nOr disable it by setting:\n```\n\"enableAirly\": false;\n```\nGo to `db.mjs` and set up database connection. All the necessary fields in database will be created automatically.\n```\nconst host = \"localhost\";\nconst port = \"5432\";\nconst databaseName = \"home\";\nconst login = \"postgres\";\nconst password = \"\";\n```\nIf You won't be using database, remove this import in `app.mjs` and set logging flag to false:\n```\nimport * as db from './db.mjs';\n```\n```\n\"databaseLogging\": false\n```\n\n# Running the driver\nStart your database server, then application:\n```\nnpm run start\n```\n\n# Example output\n\u003cimg src=\"screenshots/console.PNG\" width=\"850\"\u003e\n\n# Example logged data presentation\nI highly recommend using grafana to create graphs.\n\u003cimg src=\"screenshots/grafana.PNG\" width=\"850\"\u003e\n\n## Credits\n* [bartekn](https://github.com/bartekn) for initial idea.\n* [aholstenson](https://github.com/aholstenson) for miio library.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszlapaj%2Fairpurifierdriver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukaszlapaj%2Fairpurifierdriver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukaszlapaj%2Fairpurifierdriver/lists"}