Skip to content

Commit 99a5d7f

Browse files
sebromerosebromero
committed
Improve API clarity
1 parent a833e95 commit 99a5d7f

File tree

3 files changed

+97
-50
lines changed

3 files changed

+97
-50
lines changed

‎examples/UARTRead/UARTRead.ino‎

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -56,81 +56,81 @@ void loop() {
5656

5757
float temperature = niclaSerial.temperature();
5858
if (!isnan(temperature)) {
59-
Serial.print("🌡 HS4001 temperature (°C): ");
59+
Serial.print("🌡 Temperature (°C): ");
6060
Serial.println(temperature);
6161
}
6262

6363
float humidity = niclaSerial.humidity();
6464
if (!isnan(humidity)) {
65-
Serial.print("💧 HS4001 humidity (%RH): ");
65+
Serial.print("💧 Humidity (%RH): ");
6666
Serial.println(humidity);
6767
}
6868

69-
int epaAqi = niclaSerial.airQualityIndex();
69+
int epaAqi = niclaSerial.outdoorAirQualityIndex();
7070
if (epaAqi >= 0) {
71-
Serial.print("🏭 ZMOD4510 EPA AQI: ");
71+
Serial.print("🏭 Outdoor EPA AQI: ");
7272
Serial.println(epaAqi);
73-
Serial.print("🏭 ZMOD4510 EPA AQI interpreted: ");
74-
Serial.println(niclaSerial.airQualityIndexInterpreted());
73+
Serial.print("🏭 Outdoor EPA AQI interpreted: ");
74+
Serial.println(niclaSerial.outdoorAirQualityIndexInterpreted());
7575
}
7676

77-
int fastAqi = niclaSerial.fastAirQualityIndex();
77+
int fastAqi = niclaSerial.outdoorFastAirQualityIndex();
7878
if (fastAqi >= 0) {
79-
Serial.print("🏭 ZMOD4510 Fast AQI: ");
79+
Serial.print("🏭 Outdoor Fast AQI: ");
8080
Serial.println(fastAqi);
8181
}
8282

8383
float o3 = niclaSerial.O3();
8484
if (!isnan(o3)) {
85-
Serial.print("🌬 ZMOD4510 O3 (ppb): ");
85+
Serial.print("🌬 Outdoor O3 (ppb): ");
8686
Serial.println(o3);
8787
}
8888

8989
float no2 = niclaSerial.NO2();
9090
if (!isnan(no2)) {
91-
Serial.print("🌬 ZMOD4510 NO2 (ppb): ");
91+
Serial.print("🌬 Outdoor NO2 (ppb): ");
9292
Serial.println(no2);
9393
}
9494

95-
float iaq = niclaSerial.airQuality();
95+
float iaq = niclaSerial.indoorAirQuality();
9696
if (!isnan(iaq)) {
97-
Serial.print("🏠 ZMOD4410 IAQ: ");
97+
Serial.print("🏠 Indoor IAQ: ");
9898
Serial.println(iaq);
99-
Serial.print("🏠 ZMOD4410 IAQ interpreted: ");
100-
Serial.println(niclaSerial.airQualityInterpreted());
99+
Serial.print("🏠 Indoor IAQ interpreted: ");
100+
Serial.println(niclaSerial.indoorAirQualityInterpreted());
101101
}
102102

103-
float relIaq = niclaSerial.relativeAirQuality();
103+
float relIaq = niclaSerial.indoorRelativeAirQuality();
104104
if (!isnan(relIaq)) {
105-
Serial.print("🏠 ZMOD4410 Rel IAQ: ");
105+
Serial.print("🏠 Indoor relative IAQ: ");
106106
Serial.println(relIaq);
107107
}
108108

109109
float co2 = niclaSerial.CO2();
110110
if (!isnan(co2)) {
111-
Serial.print("🌬 ZMOD4410 eCO2 (ppm): ");
111+
Serial.print("🌬 Indoor eCO2 (ppm): ");
112112
Serial.println(co2);
113113
}
114114

115115
float tvoc = niclaSerial.TVOC();
116116
if (!isnan(tvoc)) {
117-
Serial.print("🌬 ZMOD4410 TVOC (mg/m^3): ");
117+
Serial.print("🌬 Indoor TVOC (mg/m^3): ");
118118
Serial.println(tvoc);
119119
}
120120

121121
float ethanol = niclaSerial.ethanol();
122122
if (!isnan(ethanol)) {
123-
Serial.print("🍺 ZMOD4410 EtOH (ppm): ");
123+
Serial.print("🍺 Ethanol (ppm): ");
124124
Serial.println(ethanol);
125125
}
126126

127127
float odorIntensity = niclaSerial.odorIntensity();
128128
if (!isnan(odorIntensity)) {
129-
Serial.print("👃 ZMOD4410 intensity: ");
129+
Serial.print("👃 Odor intensity: ");
130130
Serial.println(odorIntensity);
131131
}
132132

133-
Serial.print("👃 ZMOD4410 odor: ");
133+
Serial.print("👃 Sulfur odor: ");
134134
Serial.println(niclaSerial.sulfurOdor() ? "detected" : "not detected");
135135

136136
Serial.println();

‎src/NiclaSenseEnvSerial.cpp‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -97,13 +97,13 @@ bool NiclaSenseEnvSerial::update() {
9797
float NiclaSenseEnvSerial::temperature() const { return _temperature; }
9898
float NiclaSenseEnvSerial::humidity() const { return _humidity; }
9999

100-
int NiclaSenseEnvSerial::airQualityIndex() const { return _epaAqi; }
101-
int NiclaSenseEnvSerial::fastAirQualityIndex() const { return _fastAqi; }
100+
int NiclaSenseEnvSerial::outdoorAirQualityIndex() const { return _epaAqi; }
101+
int NiclaSenseEnvSerial::outdoorFastAirQualityIndex() const { return _fastAqi; }
102102
float NiclaSenseEnvSerial::NO2() const { return _no2; }
103103
float NiclaSenseEnvSerial::O3() const { return _o3; }
104104

105-
String NiclaSenseEnvSerial::airQualityIndexInterpreted() const {
106-
int airQualityValue = airQualityIndex();
105+
String NiclaSenseEnvSerial::outdoorAirQualityIndexInterpreted() const {
106+
int airQualityValue = outdoorAirQualityIndex();
107107
if (airQualityValue < 0) {
108108
return String("unknown");
109109
}
@@ -122,10 +122,10 @@ String NiclaSenseEnvSerial::airQualityIndexInterpreted() const {
122122
}
123123
}
124124

125-
float NiclaSenseEnvSerial::airQuality() const { return _iaq; }
125+
float NiclaSenseEnvSerial::indoorAirQuality() const { return _iaq; }
126126

127-
String NiclaSenseEnvSerial::airQualityInterpreted() const {
128-
float iaqValue = airQuality();
127+
String NiclaSenseEnvSerial::indoorAirQualityInterpreted() const {
128+
float iaqValue = indoorAirQuality();
129129
if (isnan(iaqValue)) {
130130
return String("unknown");
131131
}
@@ -142,7 +142,7 @@ String NiclaSenseEnvSerial::airQualityInterpreted() const {
142142
}
143143
}
144144

145-
float NiclaSenseEnvSerial::relativeAirQuality() const { return _relativeIaq; }
145+
float NiclaSenseEnvSerial::indoorRelativeAirQuality() const { return _relativeIaq; }
146146
float NiclaSenseEnvSerial::CO2() const { return _co2; }
147147
float NiclaSenseEnvSerial::TVOC() const { return _tvoc; }
148148
float NiclaSenseEnvSerial::ethanol() const { return _ethanol; }

‎src/NiclaSenseEnvSerial.h‎

Lines changed: 68 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -30,43 +30,90 @@ class NiclaSenseEnvSerial {
3030
bool update();
3131

3232
// TemperatureHumiditySensor compatible API
33-
/** @brief Get the temperature value from the sensor in degrees Celsius. */
33+
/**
34+
* @brief Get the temperature value from the sensor in degrees Celsius.
35+
* @return Temperature in degrees Celsius, or NAN when unavailable.
36+
*/
3437
float temperature() const;
35-
/** @brief Get the relative humidity value (Range 0-100%). */
38+
/**
39+
* @brief Get the relative humidity value.
40+
* @return Relative humidity percentage in the range 0-100, or NAN when unavailable.
41+
*/
3642
float humidity() const;
3743

3844
// OutdoorAirQualitySensor compatible API
39-
/** @brief Retrieves the EPA air quality index. Range is 0 to 500. */
40-
int airQualityIndex() const;
41-
/** @brief Get the fast air quality index (1-minute averaging). */
42-
int fastAirQualityIndex() const;
43-
/** @brief Get the NO2 value from the outdoor air quality sensor (ppb). */
45+
/**
46+
* @brief Retrieves the outdoor EPA air quality index.
47+
* @return AQI value in the range 0-500, or -1 when unavailable.
48+
*/
49+
int outdoorAirQualityIndex() const;
50+
/**
51+
* @brief Get the outdoor fast air quality index (1-minute averaging).
52+
* @return Fast AQI value in the range 0-500, or -1 when unavailable.
53+
*/
54+
int outdoorFastAirQualityIndex() const;
55+
/**
56+
* @brief Get the NO2 value from the outdoor air quality sensor.
57+
* @return Nitrogen dioxide concentration in ppb, or NAN when unavailable.
58+
*/
4459
float NO2() const;
45-
/** @brief Get the O3 value from the outdoor air quality sensor (ppb). */
60+
/**
61+
* @brief Get the O3 value from the outdoor air quality sensor.
62+
* @return Ozone concentration in ppb, or NAN when unavailable.
63+
*/
4664
float O3() const;
47-
/** @brief Interprets the EPA AQI into a textual description. */
48-
String airQualityIndexInterpreted() const;
65+
/**
66+
* @brief Interprets the outdoor EPA AQI into a textual description.
67+
* @return Human-readable AQI category (e.g., Good, Moderate) or "unknown" when unavailable.
68+
*/
69+
String outdoorAirQualityIndexInterpreted() const;
4970

5071
// IndoorAirQualitySensor compatible API
51-
/** @brief Get the air quality value. Common range 0 to ~5. */
52-
float airQuality() const;
53-
/** @brief Get the interpreted air quality value (Very Good, Good, Medium, Poor, Bad). */
54-
String airQualityInterpreted() const;
55-
/** @brief Get the relative air quality value in percent (0 - 100%). */
56-
float relativeAirQuality() const;
57-
/** @brief Get the CO2 value in ppm. */
72+
/**
73+
* @brief Get the indoor air quality value.
74+
* @return IAQ value (common range 0 to ~5), or NAN when unavailable.
75+
*/
76+
float indoorAirQuality() const;
77+
/**
78+
* @brief Get the interpreted indoor air quality value.
79+
* @return Human-readable IAQ category (Very Good, Good, Medium, Poor, Bad) or "unknown" when unavailable.
80+
*/
81+
String indoorAirQualityInterpreted() const;
82+
/**
83+
* @brief Get the indoor relative air quality value.
84+
* @return Relative IAQ percentage in the range 0-100, or NAN when unavailable.
85+
*/
86+
float indoorRelativeAirQuality() const;
87+
88+
/**
89+
* @brief Get the CO2 value.
90+
* @return Estimated CO2 concentration in ppm, or NAN when unavailable.
91+
*/
5892
float CO2() const;
59-
/** @brief Get the TVOC value in mg/m^3. */
93+
/**
94+
* @brief Get the TVOC value.
95+
* @return Total volatile organic compounds concentration in mg/m^3, or NAN when unavailable.
96+
*/
6097
float TVOC() const;
61-
/** @brief Get the ethanol value in ppm. */
98+
/**
99+
* @brief Get the ethanol value.
100+
* @return Ethanol concentration in ppm, or NAN when unavailable.
101+
*/
62102
float ethanol() const;
63-
/** @brief Get the odor intensity value. */
103+
/**
104+
* @brief Get the odor intensity value.
105+
* @return Odor intensity (sensor-specific scale), or NAN when unavailable.
106+
*/
64107
float odorIntensity() const;
65-
/** @brief Get the sulfur odor-detected value (true or false). */
108+
/**
109+
* @brief Get the sulfur odor-detected flag.
110+
* @return true when sulfur odor is detected, false otherwise.
111+
*/
66112
bool sulfurOdor() const;
67113

68114
/**
69115
* @brief Returns the last error message received over UART, empty when none.
116+
* @return Error string from the device, or an empty String when no error is present.
70117
*/
71118
String lastErrorMessage() const;
72119

0 commit comments

Comments
 (0)