index.html

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>AirGradient Air Quality Monitor - Driver Documentation</title>
<style>
	body { font-family: Arial, Helvetica, sans-serif; margin: 24px; color: #222; line-height: 1.5; }
	h1 { font-size: 22px; border-bottom: 2px solid #444; padding-bottom: 6px; }
	h2 { font-size: 18px; margin-top: 28px; border-bottom: 1px solid #ccc; padding-bottom: 4px; }
	h3 { font-size: 15px; margin-top: 18px; }
	table { border-collapse: collapse; width: 100%; margin: 10px 0 20px 0; }
	th, td { border: 1px solid #ccc; padding: 6px 10px; text-align: left; font-size: 13px; vertical-align: top; }
	th { background: #f0f0f0; }
	code { background: #f4f4f4; padding: 1px 5px; border-radius: 3px; font-size: 13px; }
	.note { background: #fff8e1; border-left: 4px solid #e6b800; padding: 8px 12px; margin: 12px 0; }
	.warn { background: #fdecea; border-left: 4px solid #d93025; padding: 8px 12px; margin: 12px 0; }
</style>
</head>
<body>

<h1>AirGradient Air Quality Monitor (Local API)</h1>
<p>Connects a Local-API AirGradient monitor (ONE or Open Air) directly to Control4 - no
AirGradient cloud account required. Polls <code>/measures/current</code> and
<code>/config</code> on the monitor's built-in web server over your local network.</p>

<h2>Setup</h2>
<ol>
	<li>Add the driver to a room in Composer Pro.</li>
	<li>Open the driver's <strong>Properties</strong> tab and set <strong>Host or IP Address</strong>
		to your monitor's mDNS hostname (<code>airgradient_&lt;serial&gt;.local</code>) or its
		static IP address.</li>
	<li>Adjust <strong>Polling Interval</strong> and the alert thresholds if you want something
		other than the defaults.</li>
	<li>Data should begin populating within one polling interval. Turn on
		<strong>Debug Logging</strong> and check the Lua tab if it doesn't.</li>
</ol>

<h2>Navigator Display</h2>
<p>The device uses Control4's <code>thermostatV2</code> proxy in sensor-only mode (no heat/cool
control - this monitor doesn't operate equipment). It appears under the <strong>Comfort</strong>
experience menu, showing:</p>
<ul>
	<li><strong>Main tile</strong> - current temperature and humidity.</li>
	<li><strong>Extras tab</strong> - PM2.5, PM1.0, PM10, CO2, TVOC Index, and NOx Index. These are
		the calibrated/index readings, not the raw uncalibrated sensor output.</li>
</ul>
<div class="note">
	Fahrenheit/Celsius display follows Composer Pro's system-wide temperature unit setting,
	not a property on this driver.
</div>

<h2>Properties</h2>
<table>
	<tr><th>Property</th><th>Description</th></tr>
	<tr><td>Host or IP Address</td><td>Monitor's mDNS hostname or IP address.</td></tr>
	<tr><td>Polling Interval (seconds)</td><td>How often the driver polls the monitor. Minimum 3 seconds.</td></tr>
	<tr><td>Use Compensated Values</td><td>Whether the main temperature/humidity/PM2.5 properties use AirGradient's correction algorithms or raw sensor output.</td></tr>
	<tr><td>Temperature Display Unit</td><td>Only affects the informational "Temperature (Display)" property - not the Navigator tile, which follows the system-wide unit setting.</td></tr>
	<tr><td>Debug Logging</td><td>Prints detailed request/response info to the Lua debug tab.</td></tr>
	<tr><td>PM2.5 / CO2 / TVOC / NOx Alert &amp; Clear Thresholds</td><td>Levels used to fire the corresponding Programming events, with hysteresis between the alert and clear thresholds.</td></tr>
	<tr><td>PM1.0 / PM2.5 / PM2.5 Compensated / PM10 (ug/m3)</td><td>Live particulate readings.</td></tr>
	<tr><td>CO2 (ppm)</td><td>Live CO2 reading.</td></tr>
	<tr><td>Temperature / Temperature Compensated (C), Humidity / Humidity Compensated (%)</td><td>Live climate readings, raw and corrected.</td></tr>
	<tr><td>TVOC Index / Raw, NOx Index / Raw</td><td>Live VOC/NOx sensor readings.</td></tr>
	<tr><td>WiFi Signal, Firmware Version, Model, Serial Number, Boot Count, LED Mode</td><td>Device identity/status info reported by the monitor itself.</td></tr>
	<tr><td>Config: Country / PM Standard / LED Bar Mode / Display Brightness / LED Bar Brightness</td><td>Mirror of the monitor's own <code>/config</code> settings.</td></tr>
</table>
<div class="note">
	<strong>LED Mode</strong> and the LED-related <strong>Config:</strong> fields will stay blank
	on AirGradient <strong>Open Air</strong> (outdoor) units, which have no physical LED bar and
	don't report those fields. This is a hardware difference, not a driver issue.
</div>

<h2>Programming Actions</h2>
<table>
	<tr><th>Action</th><th>Description</th></tr>
	<tr><td>Refresh Sensor Data Now</td><td>Polls the monitor immediately instead of waiting for the next interval.</td></tr>
	<tr><td>Calibrate CO2 Sensor</td><td>Triggers a 400ppm reference calibration on the device.</td></tr>
	<tr><td>Run LED Bar Test Sequence</td><td>Runs the device's built-in LED test (ONE monitors only).</td></tr>
	<tr><td>Set LED Bar Mode</td><td>co2 / pm / iaqs / off</td></tr>
	<tr><td>Set Display Brightness</td><td>0-100</td></tr>
	<tr><td>Set LED Bar Brightness</td><td>0-100</td></tr>
	<tr><td>Set Device Display Temperature Unit</td><td>Sets the unit shown on the monitor's own physical display (c/f) - separate from Control4's Navigator display.</td></tr>
</table>

<h2>Programming Events</h2>
<table>
	<tr><th>Event</th><th>Fires when...</th></tr>
	<tr><td>PM2.5 / CO2 / TVOC / NOx Above Threshold</td><td>The reading rises to or above its Alert Threshold property.</td></tr>
	<tr><td>PM2.5 / CO2 / TVOC / NOx Back to Normal</td><td>The reading falls to or below its Clear Threshold property (separate from the alert threshold, to avoid rapid on/off flapping near the line).</td></tr>
	<tr><td>Monitor Came Online / Went Offline</td><td>Fires after 3 consecutive failed polls (offline) or the next successful poll after that (online).</td></tr>
	<tr><td>Sensor Data Refreshed</td><td>Fires after every successful poll - useful as a general-purpose trigger.</td></tr>
</table>

<h3>Example: turn off a fresh-air intake fan when PM2.5 is high</h3>
<p><em>When</em> AirGradient Air Quality Monitor &gt; <strong>PM2.5 Above Threshold</strong>
occurs, <em>then</em> [your fan/damper driver] &gt; Turn Off.
Add the matching <strong>PM2.5 Back to Normal</strong> event to turn it back on.</p>

<h2>Connections</h2>
<p>Two output connections are available for wiring directly into other drivers or Programming:</p>
<table>
	<tr><th>Connection</th><th>Class</th></tr>
	<tr><td>Temperature</td><td>TEMPERATURE_VALUE</td></tr>
	<tr><td>Humidity</td><td>HUMIDITY_VALUE</td></tr>
</table>
<div class="note">
	You may see an internal "Thermostat" connection classified under Audio/Video in the system-wide
	Connections view. This is required plumbing between this driver and the thermostatV2 proxy
	and can be ignored - it isn't something you need to wire up.
</div>

<h2>Troubleshooting</h2>
<ul>
	<li><strong>No data at all:</strong> confirm Host or IP Address is correct and reachable from
		the controller, and check the Lua debug tab with Debug Logging turned on.</li>
	<li><strong>PM2.5 reads 0 for genuinely low readings:</strong> this can happen with
		Use Compensated Values set to Yes, since AirGradient's correction algorithm can round very
		low true readings down to 0. Set it to No, or check the separate
		"PM2.5 Compensated (ug/m3)" property to see both values side by side.</li>
</ul>

<h2>Version</h2>
<p>Version 1 - built for the AirGradient Local Server API
(<a href="https://github.com/airgradienthq/arduino/blob/master/docs/local-server.md">documentation</a>),
firmware 3.0.10 and later.</p>

</body>
</html>