From 5534a2cf7e5735b5d7154f8de3e0be0526d9b22b Mon Sep 17 00:00:00 2001 From: Achim Date: Fri, 19 Apr 2024 14:09:48 +0700 Subject: [PATCH] Added documentation --- README.md | 4 ++ docs/local-server.md | 105 +++++++++++++++++++++++++++++++++++++++++++ library.properties | 2 +- src/AirGradient.cpp | 2 +- 4 files changed, 111 insertions(+), 2 deletions(-) create mode 100644 docs/local-server.md diff --git a/README.md b/README.md index a52c9441..a991bafb 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,10 @@ If you have an older version of the AirGradient PCB not mentioned in the example If you have any questions or problems, check out [our forum](https://forum.airgradient.com/). +## Documentation + +Local server API documentation is available in [/docs/local-server.md](/docs/local-server.md) and AirGradient server API on [https://api.airgradient.com/public/docs/api/v1/](https://api.airgradient.com/public/docs/api/v1/). + ## The following libraries have been integrated into this library for ease of use - [Adafruit BusIO](https://github.com/adafruit/Adafruit_BusIO) diff --git a/docs/local-server.md b/docs/local-server.md new file mode 100644 index 00000000..1bd0f655 --- /dev/null +++ b/docs/local-server.md @@ -0,0 +1,105 @@ +## Local Server API + +From [firmware version 3.0.10](firmwares) onwards, the AirGradient ONE and Open Air monitors have below API available. + +#### Discovery + +The monitors run a mDNS discovery. So within the same network, the monitor can be accessed through: + +http://airgradient_{{serialnumber}}.local + + +The following requests are possible: + +#### Get Current Air Quality (GET) + +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 + +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"} +~~~ + +|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. +~~~ +{"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) + +Configuration parameters can be changed with a put request to the monitor, e.g. + +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 + + ```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. + +#### 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}| diff --git a/library.properties b/library.properties index d2706c70..42e4fca1 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=AirGradient Air Quality Sensor -version=3.0.9 +version=3.0.10beta2 author=AirGradient maintainer=AirGradient sentence=ESP32-C3 / ESP8266 library for air quality monitor measuring PM, CO2, Temperature, TVOC and Humidity with OLED display. diff --git a/src/AirGradient.cpp b/src/AirGradient.cpp index 783e0a06..9be7f722 100644 --- a/src/AirGradient.cpp +++ b/src/AirGradient.cpp @@ -5,7 +5,7 @@ #include "WiFi.h" #endif -#define AG_LIB_VER "3.0.9" +#define AG_LIB_VER "3.0.10beta2" AirGradient::AirGradient(BoardType type) : pms5003(type), pms5003t_1(type), pms5003t_2(type), s8(type), sgp41(type),