airgradienthq/arduino
1
0
Fork 1
mirror of https://github.com/airgradienthq/arduino.git synced 2025-07-30 00:47:17 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #201 from McJoppy/feature/root-api

Browse Source 
Reintroduce 'ROOTAPI' so domain and protocol can be configured
This commit is contained in:
AirGradient
2024-08-20 09:25:48 +07:00
committed by GitHub
parent be150e105a ab69b686ec
commit fb57a112c9
7 changed files with 107 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
docs/local-server.md
View File

@ -17,62 +17,77 @@ With the path "/measures/current" you can get the current air quality data.
http://airgradient_ecda3b1eaaaf.local/measures/current 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: You get the following response:
~~~ ```json
{"wifi":-46, {
"serialno":"ecda3b1eaaaf", "wifi": -46,
"rco2":447, "serialno": "ecda3b1eaaaf",
"pm01":3, "rco2": 447,
"pm02":7, "pm01": 3,
"pm10":8, "pm02": 7,
"pm003Count":442, "pm10": 8,
"atmp":25.87, "pm003Count": 442,
"rhum":43, "atmp": 25.87,
"tvocIndex":100, "atmpCompensated": 24.47,
"tvoc_raw":33051, "rhum": 43,
"noxIndex":1, "rhumCompensated": 49,
"nox_raw":16307, "tvocIndex": 100,
"boot":6, "tvocRaw": 33051,
"ledMode":"pm", "noxIndex": 1,
"firmwareVersion":"3.0.10beta", "noxRaw": 16307,
"fwMode":"I-9PSL"} "boot": 6,
~~~ "bootCount": 6,
"ledMode": "pm",
"firmware": "3.1.3",
"model": "I-9PSL"
}
```
|Properties|Type|Explanation| | Properties | Type | Explanation |
|-|-|-| |------------------|--------|--------------------------------------------------------------------|
|serialno|String| Serial Number of the monitor| | serialno | String | Serial Number of the monitor |
|wifi|Number| WiFi signal strength| | wifi | Number | WiFi signal strength |
|pm01, pm02, pm10|Number| PM1, PM2.5 and PM10 in ug/m3| | pm01 | Number | PM1 in ug/m3 |
|rco2|Number| CO2 in ppm| | pm02 | Number | PM2.5 in ug/m3 |
|pm003Count|Number| Particle count per dL| | pm10 | Number | PM10 in ug/m3 |
|atmp|Number| Temperature in Degrees Celcius| | pm02Compensated | Number | PM2.5 in ug/m3 with correction applied (from fw version 3.1.4 onwards) |
|rhum|Number| Relative Humidity| | rco2 | Number | CO2 in ppm |
|tvocIndex|Number| Senisiron VOC Index| | pm003Count | Number | Particle count per dL |
|tvoc_raw|Number| VOC raw value| | atmp | Number | Temperature in Degrees Celsius |
|noxIndex|Number| Senisirion NOx Index| | atmpCompensated | Number | Temperature in Degrees Celsius with correction applied |
|nox_raw|Number| NOx raw value| | rhum | Number | Relative Humidity |
|boot|Number| Counts every measurement cycle. Low boot counts indicate restarts.| | rhumCompensated | Number | Relative Humidity with correction applied |
|ledMode|String| Current configuration of the LED mode| | tvocIndex | Number | Senisiron VOC Index |
|firmwareVersion|String| Current firmware version| | tvocRaw | Number | VOC raw value |
|fwMode|String| Current model name| | noxIndex | Number | Senisirion NOx Index |
| 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 |
| 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) #### Get Configuration Parameters (GET)
With the path "/config" you can get the current configuration. With the path "/config" you can get the current configuration.
~~~ ```json
{"country":"US", {
"pmStandard":"ugm3", "country": "US",
"ledBarMode":"pm", "pmStandard": "ugm3",
"displayMode":"on", "ledBarMode": "pm",
"abcDays":30, "displayMode": "on",
"tvocLearningOffset":12, "abcDays": 30,
"noxLearningOffset":12, "tvocLearningOffset": 12,
"mqttBrokerUrl":"", "noxLearningOffset": 12,
"temperatureUnit":"f", "mqttBrokerUrl": "",
"configurationControl":"both", "temperatureUnit": "f",
"postDataToAirGradient":true} "configurationControl": "both",
~~~ "postDataToAirGradient": true
}
```
#### Set Configuration Parameters (PUT) #### Set Configuration Parameters (PUT)
@ -82,24 +97,30 @@ Example to force CO2 calibration
```curl -X PUT -H "Content-Type: application/json" -d '{"co2CalibrationRequested":true}' http://airgradient_84fce612eff4.local/config ``` ```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 ``` ```curl -X PUT -H "Content-Type: application/json" -d '{"temperatureUnit":"c"}' http://airgradient_84fce612eff4.local/config ```
#### Avoiding Conflicts with Configuration on AirGradient Server #### 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) #### Configuration Parameters (GET/PUT)
|Properties|Type|Accepted Values|Example| | Properties | Description | Type | Accepted Values | Example |
|-|-|-|-| |-------------------------|:-------------------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
|country|String| Country code as [ALPHA-2 notation](https://www.iban.com/country-codes) | {"country": "TH"}| | country | Country where the device is. | String | Country code as [ALPHA-2 notation](https://www.iban.com/country-codes) | {"country": "TH"} |
|pmStandard|String|ugm3 : ug/m3 <br> usaqi: USAQI | {"pmStandard": "ugm3"}| | model | Hardware identifier (only GET). | String | I-9PSL-DE | {"model": "I-9PSL-DE"} |
|ledBarMode|String|co2: LED bar displays CO2 <br> pm: LED bar displays PM <br> off: Turn off LED bar | {"ledBarMode": "off"}| | pmStandard | Particle matter standard used on the display. | String | `ugm3`: ug/m3 <br> `us-aqi`: USAQI | {"pmStandard": "ugm3"} |
|abcDays|Number|Number of days for CO2 automatic baseline balibration. Maximum 200 days. Default 8 days. | {"abcDays": 8}| | ledBarMode | Mode in which the led bar can be set. | String | `co2`: LED bar displays CO2 <br>`pm`: LED bar displays PM <br>`off`: Turn off LED bar | {"ledBarMode": "off"} |
|mqttBrokerUrl|String|MQTT broker URL. | {"mqttBrokerUrl":"mqtt://192.168.0.18:1883"} | | displayBrightness | Brightness of the Display. | Number | 0-100 | {"displayBrightness": 50} |
|temperatureUnit|String|c or C: Degree Celsius °C <br>f or F: Degree Fahrenheit °F | {"temperatureUnit": "c"}| | ledBarBrightness | Brightness of the LEDBar. | Number | 0-100 | {"ledBarBrightness": 40} |
|configurationControl|String|both : Accept local and cloud configuration <br>local : Accept only local configuration <br>cloud : Accept only cloud configuration | {"configurationControl": "both"}| | abcDays | Number of days for CO2 automatic baseline calibration. | Number | Maximum 200 days. Default 8 days. | {"abcDays": 8} |
|postDataToAirGradient|Boolean|Send data to AirGradient cloud: <br>true : Enabled <br>false: Disabled | {"postDataToAirGradient": true}| | mqttBrokerUrl | MQTT broker URL. | String | | {"mqttBrokerUrl": "mqtt://192.168.0.18:1883"} |
|co2CalibrationRequested|Boolean|Trigger CO2 calibration (400ppm) on monitor:<br>true : Calibration will be triggered | {"co2CalibrationRequested": true}| | temperatureUnit | Temperature unit shown on the display. | String | `c` or `C`: Degree Celsius °C <br>`f` or `F`: Degree Fahrenheit °F | {"temperatureUnit": "c"} |
|ledBarTestRequested|Boolean|Test LED bar:<br> true : LEDs will run test sequence | {"ledBarTestRequested": true}| | configurationControl | The configuration source of the device. | String | `both`: Accept local and cloud configuration <br>`local`: Accept only local configuration <br>`cloud`: Accept only cloud configuration | {"configurationControl": "both"} |
| postDataToAirGradient | Send data to AirGradient cloud. | Boolean | `true`: Enabled <br>`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) <br> `true`: Enabled | {"offlineMode": true} |

3
examples/BASIC/BASIC.ino
View File

@ -126,6 +126,9 @@ void setup() {
openMetrics.setAirGradient(&ag); openMetrics.setAirGradient(&ag);
localServer.setAirGraident(&ag); localServer.setAirGraident(&ag);
/** Example set custom API root URL */
// apiClient.setApiRoot("https://example.custom.api");
/** Init sensor */ /** Init sensor */
boardInit(); boardInit();

3
examples/DiyProIndoorV3_3/DiyProIndoorV3_3.ino
View File

@ -126,6 +126,9 @@ void setup() {
openMetrics.setAirGradient(&ag); openMetrics.setAirGradient(&ag);
localServer.setAirGraident(&ag); localServer.setAirGraident(&ag);
/** Example set custom API root URL */
// apiClient.setApiRoot("https://example.custom.api");
/** Init sensor */ /** Init sensor */
boardInit(); boardInit();

3
examples/DiyProIndoorV4_2/DiyProIndoorV4_2.ino
View File

@ -127,6 +127,9 @@ void setup() {
openMetrics.setAirGradient(&ag); openMetrics.setAirGradient(&ag);
localServer.setAirGraident(&ag); localServer.setAirGraident(&ag);
/** Example set custom API root URL */
// apiClient.setApiRoot("https://example.custom.api");
/** Init sensor */ /** Init sensor */
boardInit(); boardInit();

3
examples/OneOpenAir/OneOpenAir.ino
View File

@ -163,6 +163,9 @@ void setup() {
openMetrics.setAirGradient(ag); openMetrics.setAirGradient(ag);
localServer.setAirGraident(ag); localServer.setAirGraident(ag);
/** Example set custom API root URL */
// apiClient.setApiRoot("https://example.custom.api");
/** Init sensor */ /** Init sensor */
boardInit(); boardInit();

10
src/AgApiClient.cpp
View File

@ -22,6 +22,7 @@ AgApiClient::~AgApiClient() {}
void AgApiClient::begin(void) { void AgApiClient::begin(void) {
getConfigFailed = false; getConfigFailed = false;
postToServerFailed = false; postToServerFailed = false;
logInfo("Init apiRoot: " + apiRoot);
logInfo("begin"); logInfo("begin");
} }
@ -44,9 +45,8 @@ bool AgApiClient::fetchServerConfiguration(void) {
return false; return false;
} }
String uri = String uri = apiRoot + "/sensors/airgradient:" +
"http://hw.airgradient.com/sensors/airgradient:" + ag->deviceId() + ag->deviceId() + "/one/config";
"/one/config";
/** Init http client */ /** Init http client */
#ifdef ESP8266 #ifdef ESP8266
@ -185,3 +185,7 @@ bool AgApiClient::sendPing(int rssi, int bootCount) {
root["boot"] = bootCount; root["boot"] = bootCount;
return postToServer(JSON.stringify(root)); return postToServer(JSON.stringify(root));
} }
String AgApiClient::getApiRoot() const { return apiRoot; }
void AgApiClient::setApiRoot(const String &apiRoot) { this->apiRoot = apiRoot; }

3
src/AgApiClient.h
View File

@ -20,6 +20,7 @@ class AgApiClient : public PrintLog {
private: private:
Configuration &config; Configuration &config;
AirGradient *ag; AirGradient *ag;
String apiRoot = "http://hw.airgradient.com";
bool getConfigFailed; bool getConfigFailed;
bool postToServerFailed; bool postToServerFailed;
@ -37,6 +38,8 @@ public:
bool isNotAvailableOnDashboard(void); bool isNotAvailableOnDashboard(void);
void setAirGradient(AirGradient *ag); void setAirGradient(AirGradient *ag);
bool sendPing(int rssi, int bootCount); bool sendPing(int rssi, int bootCount);
String getApiRoot() const;
void setApiRoot(const String &apiRoot);
}; };
#endif /** _AG_API_CLIENT_H_ */ #endif /** _AG_API_CLIENT_H_ */