From c10cd0be723a002028a788fddaf80621ebb9a201 Mon Sep 17 00:00:00 2001 From: Aaron Bach Date: Sat, 14 Mar 2020 14:35:19 -0600 Subject: [PATCH 1/5] Add docs for AirVisual Node/Pro --- source/_integrations/airvisual.markdown | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown index ce182395af7d..77a5427b4b92 100644 --- a/source/_integrations/airvisual.markdown +++ b/source/_integrations/airvisual.markdown @@ -10,9 +10,11 @@ ha_codeowners: ha_domain: airvisual --- -The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) API for air quality data. Data can be collected via latitude/longitude or by city/state/country. The resulting information creates sensors for the Air Quality Index (AQI), the human-friendly air quality level, and the main pollutant of that area. Sensors that conform to either/both the [U.S. and Chinese air quality standards](https://www.clm.com/publication.cfm?ID=366) are created. +The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) cloud API for air quality data. Data can be collected via latitude/longitude, by city/state/country, or by the unique ID for an [AirVisual Node/Pro unit](https://www.airvisual.com/air-quality-monitor). -This platform requires an AirVisual API key, which can be obtained [here](https://airvisual.com/api). Note that the platform was designed using the "Community" package; the "Startup" and "Enterprise" package keys should continue to function, but actual results may vary (or not work at all). +## Using the AirVisual Cloud API + +AirVisual API keys can be obtained [here](https://airvisual.com/api). Note that the platform was designed using the "Community" package; the "Startup" and "Enterprise" package keys should continue to function, but actual results may vary (or not work at all). The Community API key is valid for 12 months after which it will expire. You must then go back to the AirVisual website, delete your old key, create a new one following the same steps and update your configuration with the new key. @@ -22,6 +24,10 @@ The "Community" API key is limited to 10,000 calls per month. In order to leave +## Using an AirVisual Node/Pro Unit + +The unique ID number for an AirVisual Node/Pro unit can be found by navigating to https://www.airvisual.com/dashboard/devices, clicking on the unit in question, and clicking on `API`, where the ID is visible at the end of the API URL (e.g., https://www.airvisual.com/api/v2/node/NODE_PRO_ID). + ## Configuration To enable the platform and gather data via latitude/longitude, add the following lines to your `configuration.yaml` file: From 8bb76a587ae7b2388216fa63344496f9c657223a Mon Sep 17 00:00:00 2001 From: Aaron Bach Date: Sat, 14 Mar 2020 14:39:57 -0600 Subject: [PATCH 2/5] Updates --- source/_integrations/airvisual.markdown | 35 +++++++++++++++++++++---- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown index 77a5427b4b92..e859c33f6392 100644 --- a/source/_integrations/airvisual.markdown +++ b/source/_integrations/airvisual.markdown @@ -35,12 +35,21 @@ To enable the platform and gather data via latitude/longitude, add the following ```yaml airvisual: api_key: YOUR_AIRVISUAL_API_KEY + # Or, to use an AirVisual Node/Pro: + node_pro_id: YOUR_NODE_PRO_ID ``` +Note that an API key-based entry can be mixed with one or more Node/Pro-baesd entries +(examples below). + {% configuration %} +node_pro_id: + description: Your Node/Pro ID. + required: false + type: string api_key: description: Your AirVisual API key. - required: true + required: false type: string geographies: description: A list of geographical locations to monitor @@ -71,14 +80,14 @@ geographies: ## Example Configurations -No explicit configuration (uses the `latitude` and `longitude` defined within `configuration.yaml`): +No explicit configuration (using the cloud API and the `latitude` and `longitude` defined within `configuration.yaml`): ```yaml airvisual: api_key: YOUR_AIRVISUAL_API_KEY ``` -Configuration using a single custom latitude and longitude: +Configuration using the cloud API and a single custom latitude and longitude: ```yaml airvisual: @@ -89,7 +98,7 @@ airvisual: scan_interval: 300 ``` -Configuration using multiple custom latitude and longitude pairs: +Configuration using the cloud API and multiple custom latitude and longitude pairs: ```yaml airvisual: @@ -101,7 +110,7 @@ airvisual: longitude: -117.22743 ``` -Configuration using a single city, state, and country: +Configuration using the cloud API and a single city, state, and country: ```yaml airvisual: @@ -112,6 +121,22 @@ airvisual: country: USA ``` +Configuration using a Node/Pro unit: + +```yaml +airvisual: + node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID +``` + +Configuration using the cloud API and multiple Node/Pro units: + +```yaml +airvisual: + - api_key: YOUR_AIRVISUAL_API_KEY + - node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID_1 + - node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID_2 +``` + ## Determining the City/State/Country To easily determine the proper values for a particular location, use the [AirVisual region directory](https://airvisual.com/world). Once you browse to the particular city you want, take note of the breadcrumb title, which is of the form `country > state/region > city`. Use this information to fill out `configuration.yaml`. From 4f5a2fd8270cf5a08fbc05212447e7f83dc00f47 Mon Sep 17 00:00:00 2001 From: Aaron Bach Date: Sun, 15 Mar 2020 13:41:10 -0600 Subject: [PATCH 3/5] Add local info --- source/_integrations/airvisual.markdown | 28 ++++++++++++++++--------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown index e859c33f6392..e700a81f9011 100644 --- a/source/_integrations/airvisual.markdown +++ b/source/_integrations/airvisual.markdown @@ -10,7 +10,7 @@ ha_codeowners: ha_domain: airvisual --- -The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) cloud API for air quality data. Data can be collected via latitude/longitude, by city/state/country, or by the unique ID for an [AirVisual Node/Pro unit](https://www.airvisual.com/air-quality-monitor). +The `airvisual` sensor platform queries the [AirVisual](https://airvisual.com/) cloud API for air quality data. Data can be collected via latitude/longitude, by city/state/country, or from an [AirVisual Node/Pro unit](https://www.airvisual.com/air-quality-monitor). ## Using the AirVisual Cloud API @@ -26,7 +26,7 @@ The "Community" API key is limited to 10,000 calls per month. In order to leave ## Using an AirVisual Node/Pro Unit -The unique ID number for an AirVisual Node/Pro unit can be found by navigating to https://www.airvisual.com/dashboard/devices, clicking on the unit in question, and clicking on `API`, where the ID is visible at the end of the API URL (e.g., https://www.airvisual.com/api/v2/node/NODE_PRO_ID). +The integration can communicate to Node/Pro units over the local network. You will need the IP address/hostname of the unit and its Samba password (which can be found on the unit; instructions here: https://support.airvisual.com/en/articles/3029331-download-the-airvisual-node-pro-s-data-using-samba). ## Configuration @@ -36,17 +36,14 @@ To enable the platform and gather data via latitude/longitude, add the following airvisual: api_key: YOUR_AIRVISUAL_API_KEY # Or, to use an AirVisual Node/Pro: - node_pro_id: YOUR_NODE_PRO_ID + ip_address: YOUR_NODE_PRO_IP_ADDRESS + password: YOUR_NODE_PRO_SAMBA_PASSWORD ``` Note that an API key-based entry can be mixed with one or more Node/Pro-baesd entries (examples below). {% configuration %} -node_pro_id: - description: Your Node/Pro ID. - required: false - type: string api_key: description: Your AirVisual API key. required: false @@ -76,6 +73,14 @@ geographies: description: The country the state belongs to. required: inclusive type: string +ip_address: + description: Your Node/Pro unit's IP address or hostname. + required: false + type: string +password: + description: Your Node/Pro unit's Samba password. + required: false + type: string {% endconfiguration %} ## Example Configurations @@ -125,7 +130,8 @@ Configuration using a Node/Pro unit: ```yaml airvisual: - node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID + ip_address: 192.168.1.100 + password: YOUR_NODE_PRO_SAMBA_PASSWORD ``` Configuration using the cloud API and multiple Node/Pro units: @@ -133,8 +139,10 @@ Configuration using the cloud API and multiple Node/Pro units: ```yaml airvisual: - api_key: YOUR_AIRVISUAL_API_KEY - - node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID_1 - - node_pro_id: YOUR_AIRVISUAL_NODE_PRO_ID_2 + - ip_address: 192.168.1.100 + password: YOUR_NODE_PRO_SAMBA_PASSWORD_1 + - ip_address: 192.168.1.148 + password: YOUR_NODE_PRO_SAMBA_PASSWORD_2 ``` ## Determining the City/State/Country From 0085b4fa674604e581ee17b1a7ab9a33424217c1 Mon Sep 17 00:00:00 2001 From: Aaron Bach Date: Mon, 16 Mar 2020 12:50:26 -0600 Subject: [PATCH 4/5] Code review --- source/_integrations/airvisual.markdown | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown index e700a81f9011..47d375360f0d 100644 --- a/source/_integrations/airvisual.markdown +++ b/source/_integrations/airvisual.markdown @@ -30,17 +30,22 @@ The integration can communicate to Node/Pro units over the local network. You wi ## Configuration -To enable the platform and gather data via latitude/longitude, add the following lines to your `configuration.yaml` file: +To enable the integration and gather data via latitude/longitude, add the following lines to your `configuration.yaml` file: ```yaml airvisual: api_key: YOUR_AIRVISUAL_API_KEY - # Or, to use an AirVisual Node/Pro: +``` + +To enable the integration and gather from a Node/Pro unit, add the following lines to your `configuration.yaml` file: + +```yaml +airvisual: ip_address: YOUR_NODE_PRO_IP_ADDRESS password: YOUR_NODE_PRO_SAMBA_PASSWORD ``` -Note that an API key-based entry can be mixed with one or more Node/Pro-baesd entries +Note that an API key-based entry can be mixed with one or more Node/Pro-based entries (examples below). {% configuration %} From 7a9b32773f8d1c15bd54f97e2eb0d74438f6f841 Mon Sep 17 00:00:00 2001 From: Aaron Bach Date: Sun, 19 Apr 2020 20:08:13 -0600 Subject: [PATCH 5/5] Remove config options --- source/_integrations/airvisual.markdown | 27 ------------------------- 1 file changed, 27 deletions(-) diff --git a/source/_integrations/airvisual.markdown b/source/_integrations/airvisual.markdown index 47d375360f0d..3dd845685a97 100644 --- a/source/_integrations/airvisual.markdown +++ b/source/_integrations/airvisual.markdown @@ -78,14 +78,6 @@ geographies: description: The country the state belongs to. required: inclusive type: string -ip_address: - description: Your Node/Pro unit's IP address or hostname. - required: false - type: string -password: - description: Your Node/Pro unit's Samba password. - required: false - type: string {% endconfiguration %} ## Example Configurations @@ -131,25 +123,6 @@ airvisual: country: USA ``` -Configuration using a Node/Pro unit: - -```yaml -airvisual: - ip_address: 192.168.1.100 - password: YOUR_NODE_PRO_SAMBA_PASSWORD -``` - -Configuration using the cloud API and multiple Node/Pro units: - -```yaml -airvisual: - - api_key: YOUR_AIRVISUAL_API_KEY - - ip_address: 192.168.1.100 - password: YOUR_NODE_PRO_SAMBA_PASSWORD_1 - - ip_address: 192.168.1.148 - password: YOUR_NODE_PRO_SAMBA_PASSWORD_2 -``` - ## Determining the City/State/Country To easily determine the proper values for a particular location, use the [AirVisual region directory](https://airvisual.com/world). Once you browse to the particular city you want, take note of the breadcrumb title, which is of the form `country > state/region > city`. Use this information to fill out `configuration.yaml`.