{"id":13507179,"url":"https://github.com/roe-dl/weewx-airQ","last_synced_at":"2025-03-30T07:32:28.078Z","repository":{"id":136490549,"uuid":"384990206","full_name":"roe-dl/weewx-airQ","owner":"roe-dl","description":"Service for WeeWX to retrieve air quality data from the airQ device of Corant GmbH","archived":false,"fork":false,"pushed_at":"2023-05-08T17:46:36.000Z","size":1110,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-02T02:11:10.735Z","etag":null,"topics":["air-q","air-quality","air-quality-measurements","database","noise","ozone","particulate-matter","tvoc","weewx"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/roe-dl.png","metadata":{"files":{"readme":"README.md","changelog":"changelog","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}},"created_at":"2021-07-11T15:54:51.000Z","updated_at":"2022-11-22T04:50:02.000Z","dependencies_parsed_at":"2023-09-22T03:26:11.771Z","dependency_job_id":null,"html_url":"https://github.com/roe-dl/weewx-airQ","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":"0.16666666666666663","last_synced_commit":"32d9e4e79991462edfecb2869cab28ed9dc4fc8d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fweewx-airQ","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fweewx-airQ/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fweewx-airQ/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/roe-dl%2Fweewx-airQ/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/roe-dl","download_url":"https://codeload.github.com/roe-dl/weewx-airQ/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222535161,"owners_count":16999232,"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-q","air-quality","air-quality-measurements","database","noise","ozone","particulate-matter","tvoc","weewx"],"created_at":"2024-08-01T02:00:26.118Z","updated_at":"2024-11-01T06:31:34.176Z","avatar_url":"https://github.com/roe-dl.png","language":"Python","funding_links":[],"categories":["smart home integrations"],"sub_categories":["[WeeWX](https://weewx.com/)"],"readme":"# weewx-airQ\nService for WeeWX to retrieve air quality data from the airQ device of Corant GmbH\n\nPM\u003csub\u003e1.0\u003c/sub\u003e, PM\u003csub\u003e2.5\u003c/sub\u003e, PM\u003csub\u003e10.0\u003c/sub\u003e, TVOC, \nCO, CO\u003csub\u003e2\u003c/sub\u003e, O\u003csub\u003e2\u003c/sub\u003e, O\u003csub\u003e3\u003c/sub\u003e, NO\u003csub\u003e2\u003c/sub\u003e, \nH\u003csub\u003e2\u003c/sub\u003eS, SO\u003csub\u003e2\u003c/sub\u003e, noise, health index, performance index,\ntemperature, humidity, dewpoint, air pressure\n\n## Prerequisites\n\nThe following Python modules are necessary to use this extension:\n* base64\n* Cryptodome.Cipher\n* http.client\n* json\n* threading\n\nIt depends on the distribution you use whether those modules are installed\nby default. For Debian this installation should do it:\n```\nsudo apt-get install python3-cryptodome\n```\n\nUser Hartmut was successful with that:\n```\nsudo apt-get install build-essential python3-dev \npip3 install pycryptodomex \npython3 -m Cryptodome.SelfTest \n```\n\n\n## Installation instructions:\n\n1) download\n\n   wget -O weewx-airQ.zip https://github.com/roe-dl/weewx-airQ/archive/master.zip\n\n2) run the installer\n\n   sudo wee_extension --install weewx-airQ.zip\n\n3) edit configuration in weewx.conf\n\n   ```\n   [airQ]\n\n       query_interval = 5.0 # this is the default, if option is missing\n       volume_mass_method = 1 # 0 - temp/pressure independent factor\n\n       [[first_device]]\n           host = replace_me_by_host_address_or_IP\n           password = replace_me\n           #prefix = replace_me # optional\n           #altitude = value, unit # optional, default station altitude\n           #query_interval = value # optional, if different from general setting\n\n       [[second_device]]\n           ...\n   ...\n   [Engine]\n       [[Services]]\n           prep_services = ... ,user.airQ_corant.AirqUnits\n           data_services = ... ,user.airQ_corant.AirqService\n           ...\n   ```\n   \n   The section names can be any name. It need not be something like `[[first_device]]`. We recommend \n   to use some reference to the location of the device like `[[bedroom]]`, `[[livingroom]]`, or the like.\n   \n5) restart weewx\n\n   ```\n   sudo /etc/init.d/weewx stop\n   sudo /etc/init.d/weewx start\n   ```\n\n## Usage:\n\nUsing this extension you get the readings out of the airQ measuring\ndevice and can\n\n* save them to the database\n* display them using tags in skins\n* display them in graphs\n\n### Prefix\n\nMost of the the observation types provided by the airQ device are\npredefined within WeeWX. If no special configuration besides host\naddress and password is provided the readings are stored to\nthose observation types. \n\nIf you have more than one airQ device, you need different names of the \nobservation types for each of them. That's the prefix for. \nImagine there are 3 airQ devices, one outside, one in the bedroom and \none in the living room. Your could configure the outside device without \nprefix to put `co`, `co2`, `no2`, `noise`, `o3`, `pm1_0`, `pm2_5`, \n`pm10_0`, and `so2` into the predefined columns of the WeeWX database. \nFor the bedroom device you could set `prefix = bedroom`. So you get \n`bedroom_co`, `bedroom_co2` etc. for that device. And for the living \nroom device you could set `prefix = livingroom`. So you get \n`livingroom_co`, `livingroom_co2`, etc. for that. \n\n### Adding additional columns to the database\n\nThis extension comes with a special configuration tool called `airq_conf`.\nThe tool is based on the WeeWX `wee_database` tool and provides means\nto add the necessary columns according to the prefix setting to the\ndatabase or drop them from it. See below for details.\n\n### Special cases\n\nIf you run several instances of WeeWX and transfer readings from one\nto the other by MQTT, parallel database access, or something, then \nyou also need to install\nweewx-airQ at the target system and include `user.airQ_corant.AirqUnits`\nin line `prep_services`, but omit `user.airQ_corant.AirqService`\nin line `data_services`. \nThat is because in initialization of the weewx-airQ\nextension several additional units and conversations are\nadded to the lists in `units.py` They are neccassary to convert\nbetween ppm and ppb as well as µg/m\u003csup\u003e3\u003c/sup\u003e, mg/m\u003csup\u003e3\u003c/sup\u003e,\nand g/m\u003csup\u003e3\u003c/sup\u003e, respectively. \n\n### Display values (CheetahGenerator)\n\nThe observation types described below can be used for tags as described\nin the [WeeWX Customization\nguide](http://weewx.com/docs/customizing.htm#Tags).\n\nExample: `$current.TVOC`\n\n### Diagrams (ImageGenerator)\n\nTo create diagrams you need to include additional sections into the \n[ImageGenerator] section of skin.conf. This is an example:\n\n```\n        [[[dayPM]]]\n            [[[[pm1_0]]]]\n            [[[[pm2_5]]]]\n            [[[[pm10_0]]]]\n```\n\nThe result is as follows:\n\n\u003cimg src=\"dayPM.png\" /\u003e\n\n\n## Observation types:\n\nDependent on hardware configuration the following observation types\nare provided. The names are given as if no prefix is specified:\n\n* **airqDeviceID**: (provided if included in `[StdWXCalculate]` only) \n  device ID of the device\n* **airqStatus**: (provided if included in `[StdWXCalculate]` only)\n  sensor error messages or \"OK\" if none\n* **airqBattery**: battery status (actually not used)\n* **co**: CO concentration\n* **co2**: CO\u003csub\u003e2\u003c/sub\u003e concentration\n* **dCO2dt**: CO\u003csub\u003e2\u003c/sub\u003e changing rate\n* **dHdt**: absolute humidity changing rate\n* **airqDewpoint**: dewpoint\n* **airqDoorEvent**: (experimental) door opened or closed\n* **h2s**: H\u003csub\u003e2\u003c/sub\u003eS concentration\n* **airqHealthIdx**: health index (special index according to a newly\n  developed algorithm from the manufacturer)\n* **airqHumidity**: relative humidity\n* **airqHumAbs**: absolute humidity\n* **airqMeasuretime**: duration of the last measuring cycle\n* **no2**: NO\u003csub\u003e2\u003c/sub\u003e concentration\n* **o3**: O\u003csub\u003e3\u003c/sub\u003e concentration\n* **o2**: O\u003csub\u003e2\u003c/sub\u003e concentration\n* **airqPerfIdx**: performance index (special index according to a newly\n  developed algorithm from the manufacturer)\n* **pm1_0**, **pm2_5**, **pm10_0**: particulate matter \n* **cnt0_3**, **cnt0_5**, **cnt1_0**, **cnt2_5**, **cnt5_0**, **cnt10_0**: \n  amount of particles\n  of the appropriate size\n* **TypPS**: typical particle size\n* **airqPressure**: air pressure\n* **airqAltimeter** altimeter value (air pressure corrected by altitude, \n  software calculated, not received from the device)\n* **airqBarometer**: barometer value (air pressure corrected by altitude\n  and outside temperature, software calculated, not received from the\n  device)\n* **so2**: SO\u003csub\u003e2\u003c/sub\u003e concentration\n* **airqNoise**: sound level\n* **airqTemp**: temperature\n* **TVOC**: volatile organic compounds concentration (including Corona\n  viruses)\n* **airqUptime**: uptime of the device\n\nIf a prefix is provided \"airq\" is replaced by the prefix. If the\nname does not start by \"airq\" the prefix is prepended to the name.\n\n## Configuration tool `airq_conf`\n\n### General options\n\n* `--device=DEVICE`: airQ device to set/get configuration for\n* `--config=CONFIG_FILE`: use configuration file CONFIG_FILE. Default\n  according to the way of WeeWX installation\n* `--binding=BINDING_NAME`: Use binding BINDING_NAME. Default is `wx_binding`.\n\n### General commands\n\n* `airq_conf --help`:\n  display usage instructions\n* `airq_conf --device=DEVICE --print-config`:\n  read the device configuration and display\n\n### Add or drop columns to/from the database\n\nThe `wee_database` utility allows adding columns to the database one by one\nonly. As the airQ device provides a lot of additional observation types,\nthis is quite uncomfortable. The `airq_conf` tool provides the possibility\nto add all the additional columns in one step. It regards the `prefix`\nconfiguration option. By using the original WeeWX\nfunctions for that, it should be safe. Nevertheless, backups are alsways a\ngood idea. And stop WeeWX for that.\n\n**CAUTION:** Stop WeeWX and make a backup of the database before using these\ncommands.\n\n* `airq_conf --device=DEVICE --add-columns`:\n  add the necessary columns to the database\n* `airq_conf --device=DEVICE --drop-columns`:\n  drop the columns from the database\n\n### Create a skin\n\nThe configuration utility comes with an option to create a simple skin\nbased on the Seasons skin and the settings in `weewx.conf`. It creates\na separate page for each device configured showing the current readings\nand diagram images. Diagram are only possible for observation types\nthat are saved to the database.\n\n* `airq_conf --create-skin`\n\nThe command does **not** change `weewx.conf`. If you want to use this\nskin you need to add the following section into the `StdReport` section\nof `weewx.conf`.\n\n```\n    [[airqReport]]\n        enable = true\n        skin = airQ\n        lang = de\n        unit_system = METRIC\n        HTML_ROOT = /var/www/html/weewx/airQ\n```\n\nThe `lang` option must have the same value as it has for the Seasons\nskin.\n\nFor observation types that are not saved to the database, no diagram\ncan be created. In these cases the diagram is empty.\n\n**Note**: The language and unit system options are available from\nWeeWX version 4.6 alpha on, only. Starting with WeeWX version\n4.6 beta, the localization changed vom bracket to function style.\nThat is automatically honored.\n\nExample:\n\n\u003cimg src=\"weewx-airQ-Screenshot.png\" /\u003e\n\n### Set configuration parameters in the airQ device\n\nThose commands change configuration settings within the airQ device.\n\n* `airq_conf --device=DEVICE --set-location=station`:\n  set the location of the airQ device to the station location\n* `airq_conf --device=DEVICE --set-location=LATITUDE,LOGITUDE`:\n  set the location of the airQ device to latitude and longitude provided\n* `airq_conf --device=DEVICE --set-roomsize=HEIGHT,AREA`:\n  set the room size data\n* `airq_conf [--device=DEVICE] --set-ntp=NTP_SERVER`:\n  set the NTP server\n* `airq_conf [--device=DEVICE] --set-ntp=de`:\n  set the NTP server to the official german server of PTB.\n\n## Links:\n\n* [airQ homepage](https://www.air-q.com) - [airQ forum](https://forum.air-q.com)\n* [airQ data sheet (german)](https://uploads-ssl.webflow.com/5bd9feee2fb42232fe1d0196/5f898b110a9e9fea8049fa29_air-Q_Specs_de_aktuell_2020-06-25.pdf)\n* [WeeWX homepage](http://weewx.com) - [WeeWX Wiki](https://github.com/weewx/weewx/wiki)\n* [Wöllsdorf weather conditions](https://www.woellsdorf-wetter.de)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froe-dl%2Fweewx-airQ","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Froe-dl%2Fweewx-airQ","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Froe-dl%2Fweewx-airQ/lists"}