From 59d189e1d3a32943b9117478cc4c19784ab77583 Mon Sep 17 00:00:00 2001 From: Joostlek Date: Tue, 4 Jun 2024 09:14:30 +0200 Subject: [PATCH 1/8] Update configuration parameters --- docs/local-server.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/local-server.md b/docs/local-server.md index 1bd0f65..96ca11c 100644 --- a/docs/local-server.md +++ b/docs/local-server.md @@ -91,15 +91,15 @@ If the monitor is setup on the AirGradient dashboard, it will also receive confi #### Configuration Parameters (GET/PUT) -|Properties|Type|Accepted Values|Example| -|-|-|-|-| -|country|String| Country code as [ALPHA-2 notation](https://www.iban.com/country-codes) | {"country": "TH"}| -|pmStandard|String|ugm3 : ug/m3
usaqi: USAQI | {"pmStandard": "ugm3"}| -|ledBarMode|String|co2: LED bar displays CO2
pm: LED bar displays PM
off: Turn off LED bar | {"ledBarMode": "off"}| -|abcDays|Number|Number of days for CO2 automatic baseline balibration. Maximum 200 days. Default 8 days. | {"abcDays": 8}| -|mqttBrokerUrl|String|MQTT broker URL. | {"mqttBrokerUrl":"mqtt://192.168.0.18:1883"} | -|temperatureUnit|String|c or C: Degree Celsius °C
f or F: Degree Fahrenheit °F | {"temperatureUnit": "c"}| -|configurationControl|String|both : Accept local and cloud configuration
local : Accept only local configuration
cloud : Accept only cloud configuration | {"configurationControl": "both"}| -|postDataToAirGradient|Boolean|Send data to AirGradient cloud:
true : Enabled
false: Disabled | {"postDataToAirGradient": true}| -|co2CalibrationRequested|Boolean|Trigger CO2 calibration (400ppm) on monitor:
true : Calibration will be triggered | {"co2CalibrationRequested": true}| -|ledBarTestRequested|Boolean|Test LED bar:
true : LEDs will run test sequence | {"ledBarTestRequested": true}| +| Properties | Description | Type | Accepted Values | Example | +|-------------------------|:-------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| +| country | Country where the device is. | String | Country code as [ALPHA-2 notation](https://www.iban.com/country-codes) | {"country": "TH"} | +| pmStandard | Particle matter standard used on the display. | String | `ugm3`: ug/m3
`us-aqi`: USAQI | {"pmStandard": "ugm3"} | +| ledBarMode | Mode in which the led bar can be set. | String | `co2`: LED bar displays CO2
`pm`: LED bar displays PM
`off`: Turn off LED bar | {"ledBarMode": "off"} | +| abcDays | Number of days for CO2 automatic baseline calibration. | Number | Maximum 200 days. Default 8 days. | {"abcDays": 8} | +| mqttBrokerUrl | MQTT broker URL. | String | | {"mqttBrokerUrl": "mqtt://192.168.0.18:1883"} | +| temperatureUnit | Temperature unit shown on the display. | String | `c` or `C`: Degree Celsius °C
`f` or `F`: Degree Fahrenheit °F | {"temperatureUnit": "c"} | +| configurationControl | The configuration source of the device. | String | `both`: Accept local and cloud configuration
`local`: Accept only local configuration
`cloud`: Accept only cloud configuration | {"configurationControl": "both"} | +| postDataToAirGradient | Send data to AirGradient cloud. | Boolean | `true`: Enabled
`false`: Disabled | {"postDataToAirGradient": true} | +| co2CalibrationRequested | Can be set to trigger a calibration. | Boolean | `true`: CO2 calibration (400ppm) will be triggered | {"co2CalibrationRequested": true} | +| ledBarTestRequested | Can be set to trigger a test. | Boolean | `true` : LEDs will run test sequence | {"ledBarTestRequested": true} | From 5f93329e968e7776bb527817a3a2a7667f4febcf Mon Sep 17 00:00:00 2001 From: Joostlek Date: Tue, 4 Jun 2024 09:17:33 +0200 Subject: [PATCH 2/8] Fix typos in docs --- docs/local-server.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/local-server.md b/docs/local-server.md index 1bd0f65..47bc1c3 100644 --- a/docs/local-server.md +++ b/docs/local-server.md @@ -17,7 +17,7 @@ With the path "/measures/current" you can get the current air quality data. http://airgradient_ecda3b1eaaaf.local/measures/current -“ecda3b1eaaaf” being the serial number of your monitor +“ecda3b1eaaaf” being the serial number of your monitor. You get the following response: ~~~ @@ -82,12 +82,12 @@ Example to force CO2 calibration ```curl -X PUT -H "Content-Type: application/json" -d '{"co2CalibrationRequested":true}' http://airgradient_84fce612eff4.local/config ``` -Example to set monitor to Celcius +Example to set monitor to Celsius ```curl -X PUT -H "Content-Type: application/json" -d '{"temperatureUnit":"c"}' http://airgradient_84fce612eff4.local/config ``` #### Avoiding Conflicts with Configuration on AirGradient Server -If the monitor is setup on the AirGradient dashboard, it will also receive configurations from there. In case you do not want this, please set "configurationControl" to local. In case you set it to cloud and want to change it to local, you need to make a factory reset. +If the monitor is set up on the AirGradient dashboard, it will also receive configurations from there. In case you do not want this, please set `configurationControl` to `local`. In case you set it to `cloud` and want to change it to `local`, you need to make a factory reset. #### Configuration Parameters (GET/PUT) From 4a58b0b1c7ba326077c9c08c88a32bb585e14c6c Mon Sep 17 00:00:00 2001 From: Joostlek Date: Tue, 4 Jun 2024 09:20:18 +0200 Subject: [PATCH 3/8] Reformat JSON in docs --- docs/local-server.md | 68 +++++++++++++++++++++++--------------------- 1 file changed, 36 insertions(+), 32 deletions(-) diff --git a/docs/local-server.md b/docs/local-server.md index 1bd0f65..09379f4 100644 --- a/docs/local-server.md +++ b/docs/local-server.md @@ -20,25 +20,27 @@ http://airgradient_ecda3b1eaaaf.local/measures/current “ecda3b1eaaaf” being the serial number of your monitor You get the following response: -~~~ -{"wifi":-46, -"serialno":"ecda3b1eaaaf", -"rco2":447, -"pm01":3, -"pm02":7, -"pm10":8, -"pm003Count":442, -"atmp":25.87, -"rhum":43, -"tvocIndex":100, -"tvoc_raw":33051, -"noxIndex":1, -"nox_raw":16307, -"boot":6, -"ledMode":"pm", -"firmwareVersion":"3.0.10beta", -"fwMode":"I-9PSL"} -~~~ +```json +{ + "wifi": -46, + "serialno": "ecda3b1eaaaf", + "rco2": 447, + "pm01": 3, + "pm02": 7, + "pm10": 8, + "pm003Count": 442, + "atmp": 25.87, + "rhum": 43, + "tvocIndex": 100, + "tvoc_raw": 33051, + "noxIndex": 1, + "nox_raw": 16307, + "boot": 6, + "ledMode": "pm", + "firmwareVersion": "3.0.10beta", + "fwMode": "I-9PSL" +} +``` |Properties|Type|Explanation| |-|-|-| @@ -60,19 +62,21 @@ You get the following response: #### Get Configuration Parameters (GET) With the path "/config" you can get the current configuration. -~~~ -{"country":"US", -"pmStandard":"ugm3", -"ledBarMode":"pm", -"displayMode":"on", -"abcDays":30, -"tvocLearningOffset":12, -"noxLearningOffset":12, -"mqttBrokerUrl":"", -"temperatureUnit":"f", -"configurationControl":"both", -"postDataToAirGradient":true} -~~~ +```json +{ + "country": "US", + "pmStandard": "ugm3", + "ledBarMode": "pm", + "displayMode": "on", + "abcDays": 30, + "tvocLearningOffset": 12, + "noxLearningOffset": 12, + "mqttBrokerUrl": "", + "temperatureUnit": "f", + "configurationControl": "both", + "postDataToAirGradient": true +} +``` #### Set Configuration Parameters (PUT) From 4249a86fd55a211060c2ce56676b777985af3a43 Mon Sep 17 00:00:00 2001 From: Joostlek Date: Tue, 4 Jun 2024 09:21:29 +0200 Subject: [PATCH 4/8] Reformat table --- docs/local-server.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/local-server.md b/docs/local-server.md index 1bd0f65..9440a0d 100644 --- a/docs/local-server.md +++ b/docs/local-server.md @@ -40,23 +40,23 @@ You get the following response: "fwMode":"I-9PSL"} ~~~ -|Properties|Type|Explanation| -|-|-|-| -|serialno|String| Serial Number of the monitor| -|wifi|Number| WiFi signal strength| -|pm01, pm02, pm10|Number| PM1, PM2.5 and PM10 in ug/m3| -|rco2|Number| CO2 in ppm| -|pm003Count|Number| Particle count per dL| -|atmp|Number| Temperature in Degrees Celcius| -|rhum|Number| Relative Humidity| -|tvocIndex|Number| Senisiron VOC Index| -|tvoc_raw|Number| VOC raw value| -|noxIndex|Number| Senisirion NOx Index| -|nox_raw|Number| NOx raw value| -|boot|Number| Counts every measurement cycle. Low boot counts indicate restarts.| -|ledMode|String| Current configuration of the LED mode| -|firmwareVersion|String| Current firmware version| -|fwMode|String| Current model name| +| Properties | Type | Explanation | +|------------------|--------|--------------------------------------------------------------------| +| serialno | String | Serial Number of the monitor | +| wifi | Number | WiFi signal strength | +| pm01, pm02, pm10 | Number | PM1, PM2.5 and PM10 in ug/m3 | +| rco2 | Number | CO2 in ppm | +| pm003Count | Number | Particle count per dL | +| atmp | Number | Temperature in Degrees Celcius | +| rhum | Number | Relative Humidity | +| tvocIndex | Number | Senisiron VOC Index | +| tvoc_raw | Number | VOC raw value | +| noxIndex | Number | Senisirion NOx Index | +| nox_raw | Number | NOx raw value | +| boot | Number | Counts every measurement cycle. Low boot counts indicate restarts. | +| ledMode | String | Current configuration of the LED mode | +| firmwareVersion | String | Current firmware version | +| fwMode | String | Current model name | #### Get Configuration Parameters (GET) With the path "/config" you can get the current configuration. From adabb9baa483ccd109c5a35506f620b17362b493 Mon Sep 17 00:00:00 2001 From: Phat Nguyen Date: Wed, 12 Jun 2024 06:04:13 +0700 Subject: [PATCH 5/8] OpenAir set WiFi connect to `airgradient` on factory reset --- examples/OneOpenAir/OneOpenAir.ino | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/examples/OneOpenAir/OneOpenAir.ino b/examples/OneOpenAir/OneOpenAir.ino index d3ec231..ecda5c9 100644 --- a/examples/OneOpenAir/OneOpenAir.ino +++ b/examples/OneOpenAir/OneOpenAir.ino @@ -418,8 +418,12 @@ static void factoryConfigReset(void) { } /** Reset WIFI */ - WiFi.enableSTA(true); // Incase offline mode + WiFi.enableSTA(true); // Incase offline mode WiFi.disconnect(true, true); + if (ag->isOne() == false) { + WiFi.begin("airgradient", "cleanair"); + Serial.println("Set WiFi connect to \"airgradient\""); + } /** Reset local config */ configuration.reset(); From 3b6859f483f494d0556d36acdb95bfc3d7957f08 Mon Sep 17 00:00:00 2001 From: Achim Date: Mon, 17 Jun 2024 08:46:56 +0700 Subject: [PATCH 6/8] Updated documentation for local server --- docs/local-server.md | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/docs/local-server.md b/docs/local-server.md index f719632..925117f 100644 --- a/docs/local-server.md +++ b/docs/local-server.md @@ -30,15 +30,18 @@ You get the following response: "pm10": 8, "pm003Count": 442, "atmp": 25.87, + "atmpCompensated": 24.47, "rhum": 43, + "rhumCompensated": 49, "tvocIndex": 100, - "tvoc_raw": 33051, + "tvocRaw": 33051, "noxIndex": 1, - "nox_raw": 16307, + "noxRaw": 16307, "boot": 6, + "bootCount": 6, "ledMode": "pm", - "firmwareVersion": "3.0.10beta", - "fwMode": "I-9PSL" + "firmware": "3.1.3", + "model": "I-9PSL" } ``` @@ -46,19 +49,27 @@ You get the following response: |------------------|--------|--------------------------------------------------------------------| | serialno | String | Serial Number of the monitor | | wifi | Number | WiFi signal strength | -| pm01, pm02, pm10 | Number | PM1, PM2.5 and PM10 in ug/m3 | +| pm01 | Number | PM1 in ug/m3 | +| pm02 | Number | PM2.5 in ug/m3 | +| pm10 | Number | PM10 in ug/m3 | +| pm02Compensated | Number | PM2.5 in ug/m3 with correction applied (from fw version 3.1.4 onwards) | | rco2 | Number | CO2 in ppm | | pm003Count | Number | Particle count per dL | -| atmp | Number | Temperature in Degrees Celcius | +| atmp | Number | Temperature in Degrees Celsius | +| atmpCompensated | Number | Temperature in Degrees Celsius with correction applied | | rhum | Number | Relative Humidity | +| rhumCompensated | Number | Relative Humidity with correction applied | | tvocIndex | Number | Senisiron VOC Index | -| tvoc_raw | Number | VOC raw value | +| tvocRaw | Number | VOC raw value | | noxIndex | Number | Senisirion NOx Index | -| nox_raw | Number | NOx raw value | +| noxRaw | Number | NOx raw value | | boot | Number | Counts every measurement cycle. Low boot counts indicate restarts. | +| bootCount | Number | Same as boot property. Required for Home Assistant compatability. Will be depreciated. | | ledMode | String | Current configuration of the LED mode | -| firmwareVersion | String | Current firmware version | -| fwMode | String | Current model name | +| firmware | String | Current firmware version | +| model | String | Current model name | + +Compensated values apply correction algorithms to make the sensor values more accurate. Temperature and relative humidity correction is only applied on the outdoor monitor Open Air but the properties _compensated will still be send also for the indoor monitor AirGradient ONE. #### Get Configuration Parameters (GET) With the path "/config" you can get the current configuration. @@ -98,8 +109,11 @@ If the monitor is set up on the AirGradient dashboard, it will also receive conf | Properties | Description | Type | Accepted Values | Example | |-------------------------|:-------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| | country | Country where the device is. | String | Country code as [ALPHA-2 notation](https://www.iban.com/country-codes) | {"country": "TH"} | +| model | Hardware identifier (only GET). | String | I-9PSL-DE | {"model": "I-9PSL-DE"} | | pmStandard | Particle matter standard used on the display. | String | `ugm3`: ug/m3
`us-aqi`: USAQI | {"pmStandard": "ugm3"} | | ledBarMode | Mode in which the led bar can be set. | String | `co2`: LED bar displays CO2
`pm`: LED bar displays PM
`off`: Turn off LED bar | {"ledBarMode": "off"} | +| displayBrightness | Brightness of the Display. | Number | 0-100 | {"displayBrightness": 50} | +| ledBarBrightness | Brightness of the LEDBar. | Number | 0-100 | {"ledBarBrightness": 40} | | abcDays | Number of days for CO2 automatic baseline calibration. | Number | Maximum 200 days. Default 8 days. | {"abcDays": 8} | | mqttBrokerUrl | MQTT broker URL. | String | | {"mqttBrokerUrl": "mqtt://192.168.0.18:1883"} | | temperatureUnit | Temperature unit shown on the display. | String | `c` or `C`: Degree Celsius °C
`f` or `F`: Degree Fahrenheit °F | {"temperatureUnit": "c"} | @@ -107,3 +121,6 @@ If the monitor is set up on the AirGradient dashboard, it will also receive conf | postDataToAirGradient | Send data to AirGradient cloud. | Boolean | `true`: Enabled
`false`: Disabled | {"postDataToAirGradient": true} | | co2CalibrationRequested | Can be set to trigger a calibration. | Boolean | `true`: CO2 calibration (400ppm) will be triggered | {"co2CalibrationRequested": true} | | ledBarTestRequested | Can be set to trigger a test. | Boolean | `true` : LEDs will run test sequence | {"ledBarTestRequested": true} | +| noxLearningOffset | Set NOx learning gain offset. | Number | 0-720 (default 12) | {"noxLearningOffset": 12} | +| tvocLearningOffset | Set VOC learning gain offset. | Number | 0-720 (default 12) | {"tvocLearningOffset": 12} | +| offlineMode | Set monitor to run without WiFi. | Boolean | `false`: Disabled (default)
`true`: Enabled | {"offlineMode": true} | From 7b9dac756bd8fdf362926fd87fe3cffff9b12a54 Mon Sep 17 00:00:00 2001 From: John Date: Sun, 21 Jul 2024 19:38:50 +1200 Subject: [PATCH 7/8] Reintroduce 'ROOTAPI' so domain and protocol can be configured eg. setter for api root added as comment in examples/BASIC/BASIC.ino --- examples/BASIC/BASIC.ino | 3 +++ src/AgApiClient.cpp | 15 +++++++++------ src/AgApiClient.h | 3 +++ 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/examples/BASIC/BASIC.ino b/examples/BASIC/BASIC.ino index 8928c68..7a6e200 100644 --- a/examples/BASIC/BASIC.ino +++ b/examples/BASIC/BASIC.ino @@ -126,6 +126,9 @@ void setup() { openMetrics.setAirGradient(&ag); localServer.setAirGraident(&ag); + /** Example set custom API root URL */ + // apiClient.setApiRoot("https://example.custom.api"); + /** Init sensor */ boardInit(); diff --git a/src/AgApiClient.cpp b/src/AgApiClient.cpp index 1f7c83b..bff6789 100644 --- a/src/AgApiClient.cpp +++ b/src/AgApiClient.cpp @@ -22,6 +22,7 @@ AgApiClient::~AgApiClient() {} void AgApiClient::begin(void) { getConfigFailed = false; postToServerFailed = false; + logInfo("Init apiRoot: " + apiRoot); logInfo("begin"); } @@ -44,9 +45,8 @@ bool AgApiClient::fetchServerConfiguration(void) { return false; } - String uri = - "http://hw.airgradient.com/sensors/airgradient:" + ag->deviceId() + - "/one/config"; + String uri = apiRoot + "/sensors/airgradient:" + + ag->deviceId() + "/one/config"; /** Init http client */ #ifdef ESP8266 @@ -109,9 +109,8 @@ bool AgApiClient::postToServer(String data) { return false; } - String uri = - "http://hw.airgradient.com/sensors/airgradient:" + ag->deviceId() + - "/measures"; + String uri = apiRoot + "/sensors/airgradient:" + + ag->deviceId() + "/measures"; logInfo("Post uri: " + uri); logInfo("Post data: " + data); @@ -177,3 +176,7 @@ bool AgApiClient::sendPing(int rssi, int bootCount) { root["boot"] = bootCount; return postToServer(JSON.stringify(root)); } + +String AgApiClient::getApiRoot() const { return apiRoot; } + +void AgApiClient::setApiRoot(const String &apiRoot) { this->apiRoot = apiRoot; } diff --git a/src/AgApiClient.h b/src/AgApiClient.h index 4b37bf3..7e6037d 100644 --- a/src/AgApiClient.h +++ b/src/AgApiClient.h @@ -20,6 +20,7 @@ class AgApiClient : public PrintLog { private: Configuration &config; AirGradient *ag; + String apiRoot = "http://hw.airgradient.com"; bool getConfigFailed; bool postToServerFailed; @@ -37,6 +38,8 @@ public: bool isNotAvailableOnDashboard(void); void setAirGradient(AirGradient *ag); bool sendPing(int rssi, int bootCount); + String getApiRoot() const; + void setApiRoot(const String &apiRoot); }; #endif /** _AG_API_CLIENT_H_ */ From 6746d25dc2fd5565b157401837a90e565f95f961 Mon Sep 17 00:00:00 2001 From: John Date: Sun, 18 Aug 2024 16:46:56 +1200 Subject: [PATCH 8/8] Add comment to all example scripts showing how to change APIROOT --- examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino | 3 +++ examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino | 3 +++ examples/OneOpenAir/OneOpenAir.ino | 3 +++ 3 files changed, 9 insertions(+) diff --git a/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino b/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino index d1eaa76..295a2ca 100644 --- a/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino +++ b/examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino @@ -126,6 +126,9 @@ void setup() { openMetrics.setAirGradient(&ag); localServer.setAirGraident(&ag); + /** Example set custom API root URL */ + // apiClient.setApiRoot("https://example.custom.api"); + /** Init sensor */ boardInit(); diff --git a/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino b/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino index 3b16795..c158856 100644 --- a/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino +++ b/examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino @@ -127,6 +127,9 @@ void setup() { openMetrics.setAirGradient(&ag); localServer.setAirGraident(&ag); + /** Example set custom API root URL */ + // apiClient.setApiRoot("https://example.custom.api"); + /** Init sensor */ boardInit(); diff --git a/examples/OneOpenAir/OneOpenAir.ino b/examples/OneOpenAir/OneOpenAir.ino index 96633a6..81afb84 100644 --- a/examples/OneOpenAir/OneOpenAir.ino +++ b/examples/OneOpenAir/OneOpenAir.ino @@ -163,6 +163,9 @@ void setup() { openMetrics.setAirGradient(ag); localServer.setAirGraident(ag); + /** Example set custom API root URL */ + // apiClient.setApiRoot("https://example.custom.api"); + /** Init sensor */ boardInit();