{"id":24941404,"url":"https://github.com/marcelm/radonwave","last_synced_at":"2025-04-10T03:04:11.135Z","repository":{"id":46714789,"uuid":"118829272","full_name":"marcelm/radonwave","owner":"marcelm","description":"Read radon levels from Airthings Wave","archived":false,"fork":false,"pushed_at":"2022-03-25T09:37:41.000Z","size":16,"stargazers_count":26,"open_issues_count":7,"forks_count":8,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-24T04:35:14.848Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/marcelm.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}},"created_at":"2018-01-24T22:17:51.000Z","updated_at":"2023-04-07T03:08:32.000Z","dependencies_parsed_at":"2022-09-14T05:01:13.614Z","dependency_job_id":null,"html_url":"https://github.com/marcelm/radonwave","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/marcelm%2Fradonwave","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelm%2Fradonwave/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelm%2Fradonwave/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcelm%2Fradonwave/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcelm","download_url":"https://codeload.github.com/marcelm/radonwave/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248148224,"owners_count":21055547,"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":[],"created_at":"2025-02-02T18:22:48.796Z","updated_at":"2025-04-10T03:04:11.099Z","avatar_url":"https://github.com/marcelm.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Radonwave\n\nThis tool reads the current radon level from the “Airthings Wave”\nradon detector *without* using the official smartphone app.\n\nThe official app cannot export radon levels to an external file. This tool\nallows you to create such a file.\n\n**Note:** Don’t expect a finished product here. The tool and the README serve\nmainly as a way to document how to interface with the Wave.\n\nA couple of days after publishing this, Airthings themselves made instructions\nand a script available at \u003chttps://airthings.com/raspberry-pi/\u003e. Their script\nis written in Python 2 and does not report the “Other characteristics”\n(described below), but appears to have equivalent functionality otherwise.\n\n# Limitations\n\nIt may be possible that the Wave must be connected to the official app at least\nonce before you can use this program, so you will probably not get around\nregistering an account with Airthings.\n\nThe radon level history stored on the Wave itself cannot be accessed\nwith this program. To get around this, I run it continuously on a Raspberry Pi\nthat connects regularly to the radon detector.\n\nMake sure you install the latest firmware. The Wave and also this script were\nvery unstable until I installed firmware from Feb. 21, 2018.\n\n# Hardware requirements\n\n* An Airthings Wave\n* A Bluetooth adapter that supports Bluetooth Low Energy (BLE).\n\n\n# Installing software requirements\n\nYou need:\n\n* The bluez software\n* Python 3\n* The `bluepy` Python library\n\nThe following will install the above on Debian/Ubuntu/Raspbian (it will install\nthe `bluepy` Python library into a virtualenv):\n\n    sudo apt install build-essential python3-venv python3-pip libglib2.0-dev bluez\n    python3 -m venv env\n    env/bin/pip install bluepy\n\n# Running\n\nAfter the above, scan for your Wave device with\n\n    sudo hcitool lescan\n\nThis should list the device addresses of all Bluetooth devices that are nearby.\nThe Wave probably has a device address that starts with 98:07:2D.\n\nIt may be more comfortabe to use an app on your smartphone that can scan for\nBluetooth Low Energy devices. It doesn’t matter as long as you find out\nwhat the device address is.\n\nFinally, you can run the program:\n\n    env/bin/python radonwave.py ADDRESS\n\nReplace ADDRESS with the device address that you found out above.\n\n\n# MQTT\n\nFor MQTT support, please install the `paho.mqtt` package in the virtual environment:\n```\nenv/bin/pip install paho.mqtt\n```\n\nTo regularly post measurements to an MQTT server, I use a script named `radonlog.sh`:\n```\nenv/bin/python radonwave.py --wait 0 --mqtt MQTT-SERVER-HOSTNAME --topic sensor/wave ADDRESS \u003e\u003e radonlog.txt\n```\nMake the script executable with `chmod +x radonlog.sh`.\n\nAdjust `MQTT-SERVER-HOSTNAME`, `sensor/wave` and `ADDRESS` as necessary. If authentication is required,\nadd `--username myusername` and, if a password is required, also `--password mypassword`. To change the default port (1883), use `--port PORT`, where PORT is the port number.\n\nDue to the `--wait 0`, this will only run once and exit. For regular measurements, I then use a cron job that runs twice an hour. I used to `crontab -e` to edit the crontab and added this line:\n```\n*/30 * * * * $HOME/radonlog.sh\n```\nThis should be more reliable than running the script with `--wait 1800`, and the measurements will be at well-defined times.\n\n\n# Notes\n\n* The [nRF Connect app](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp\u0026hl=en)\n  was very helpful. It allows to connect to the device via Bluetooth Low Energy (BLE)\n  and browse the services that are available.\n* GATT (part of Bluetooth) specifies some standard “characteristics”.\n  The Wave offers the standard *temperature* and *humidity* characteristics.\n  This is very easy to see in nRF Connect.\n* Radon levels are reported in two different characteristics. Characteristics\n  even come with proper descriptions, so this is also easy to spot from nRF\n  Connect.\n\n# Reading temperature and humidity with gatttool\n\n```\n$ sudo gatttool -I -b YOUR-DEVICE-ADDRESS\n[98:07:2D:xx:yy:zz][LE]\u003e connect\nAttempting to connect to 98:07:2D:xx:yy:zz\nConnection successful\n[98:07:2D:xx:yy:zz][LE]\u003e char-read-uuid 00002a6e-0000-1000-8000-00805f9b34fb\nhandle: 0x0022   value: 1c 07\n```\n\nThe two bytes 1c and 07 were returned. To convert to temperature,\nswap them (0x071c), convert to decimal (1820) and divide by 100:\nThe temperature is 18.2°C.\n\nIt is similar for humidity:\n```\nchar-read-uuid 00002a6f-0000-1000-8000-00805f9b34fb\nhandle: 0x0026   value: 68 10\n```\nThe value 0x1068 was returned, which is 4200 in decimal. Divide by 100\nto get 42% relative humidity.\n\n# Radon level characteristics\n\nThere are two characteristics:\n\n* “Radon conc. average” is available by reading the characteristic b42e0a4c-ade7-11e4-89d3-123b93f75cba.\n* “Radon conc. 1 day” is available by reading the characteristic b42e01aa-ade7-11e4-89d3-123b93f75cba.\n\nThat is, you can read the values with `char-read-uuid` and using the above number.\nAgain, two bytes are returned that need to be swapped, but they must not be\ndivided by 100. The unit is Bq/m³.\n\n“Radon conc. average” is identical to the value that the app reports as current\nradon level. This value is updated every 60 minutes. If you reset the Wave, a\nzero is reported during the first 60 minutes. It seems that measurements are\nactually even slower: When I moved the device from the basement to a place\noutside the house, it took 24 hours until the value reported here had dropped\nfrom over 500 to 17.\n\nThe meaning of the “Radon conc. 1 day” value is described by [Airthings on\ntheir Raspberry Pi website](https://airthings.com/raspberry-pi/) as follows:\n\n\u003e The radon long term measurements are averaged from the batteries are\n\u003e inserted up to one year.\n\nIt appears that after a reset, the value is identical to “Radon conc. average”\nfor the first 24 hours and then starts to differ.\n\n# Other characteristics\n\n## Status info\n\nThere is a characteristic called “Status info” available by reading from\nb42e1348-ade7-11e4-89d3-123b93f75cba. It is identical to the humidity\ncharacteristic *except* for once every 24 hours, when this one is 0, but the\ntrue “Humidity” characteristic still shows a sensible value.\n\n## Accel. Light 5m\n\nA characteristic called “Accel. Light 5m” is available from\nb42e1096-ade7-11e4-89d3-123b93f75cba.\n\nThe second byte of this 16-bit value appears to be brightness, as\n@christianchristensen found out. See also the discussion in\n[issue #1](https://github.com/marcelm/radonwave/issues/1).\n\n# Other notes\n\n* The Wave also reports the current time as a Bluetooth characteristic. This is\n  quite likely synchronized by the app.\n\n* If your Bluetooth adapter seems not to work, you may need to unblock it:\n\n      sudo apt install rfkill\n      sudo rfkill unblock bluetooth\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelm%2Fradonwave","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcelm%2Fradonwave","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcelm%2Fradonwave/lists"}