AirGradient Forum

Bad software experience for non-cloud users

#1

I’d like to start by saying that this is a lovely product! Thank you for making air monitoring accessible.

However, as someone who didn’t want the dashboard and only wanted polling the device over HTTP WiFi, the first-time experience was very, very confusing.

1. I could not find any information on what the different display readings mean (CO2, PM2.5)

Only after watching some YouTube videos I learned that this type of documentation is only available after logging in to the dashboard and pairing the device. It should be available in the regular documentation for everyone, even those who haven’t bought the product yet. I had to make an account only to be able to see the documentation.

2. Airgradient insists on connecting to the server

On first WiFi setup, the air gradient offers you the option of preventing cloud connection. This option is ignored as of firmware 3.1.21 I-9PSL , and whenever the device connects to WiFi, it will also connect to the server.

3. Configuration options unavailable without the dashboard

I couldn’t find documentation on how to adjust the settings (LED settings, pm2.5 correction formula, etc) without the cloud dashboard.

4. Update without permisssion

After giving up and connecting to the dashboard, for the sole purpose of seeing the docs and adjusting the settings, the device immediately updated from 3.1.13 to 3.1.21, a version not even available in the changelog. I panicked and thought I was being hacked, until I read in the forums this version is real but not yet in the changelog.

5. http routes are poorly documented

After finally setting it all up, I couldn’t find any mention of how to poll the sensor data. I eventually found the /measures/current route in the changelog. And it made me wonder what other routes have I missed. I wish there was a route for adjusting the settings.

All in all, great hardware, great software, but the non-dashboard experience looks like an afterthought, and there’s lots of low hanging fruit you can do to make it a lot better with very little effort. Thanks!

1 Like
#2

Thank you for pointing these out. I am on my phone, so just some quick answers:

  1. Good point. We will put something directly on our website
  2. This is an unfortunate bug that we already fixed and will be rolled out in the next release.
  3. This is part of the GitHub documentation. See arduino/docs/local-server.md at master · airgradienthq/arduino · GitHub
  4. The firmware can be fixed on the dashboard under Place Administration.
  5. I believe also documented in arduino/docs/local-server.md at master · airgradienthq/arduino · GitHub

I hope that helps.

2 Likes
#3

Does this help with what the different readings mean?
AirGradient Cheatsheet

2 Likes
#4

Thank you! The GitHub documentation is great, but as someone who scanned the barcode that came with the product, followed the build instructions, and looked in the “documentation” tab in the website, I did not know it exists!

Proposal: Add two “entry points” to the Github doc:

  1. In the integrations page, add a “HTTP API” section.

  2. In the build instructions, right after the dashboard section, create a “Other integrations / server options” section, which links to the Integrations page.

Sample text for #2

Other than the cloud dashboard, air gradient supports various other integrations such as OpenHab, Home Assistant, an HTTP API, and more. See the integrations page for more information.

Rationale:
The dashboard section in the build instructions is exactly where my confusion started. I was expecting non cloud abilities but couldn’t find an HTTP API in and the dashboard was the focus. Then I looked in the integrations but it didn’t help.

2 Likes
#5

Regarding (4), maybe add a cloudAutoUpdate boolean to /config?

Rationale: Without this, a non-cloud user who decides to enable the cloud (whether permanently or temporarily for testing) might get an unexpected firmware update.

#6

More good news for you:

  1. You are not the only one who wants these improvements
  2. It looks like the ticket from last June about not being able to compile will soon be fixed, which (in combination with the fix to not phone home to AirGradient’s servers) will make it possible for me to do development work without setting up an entirely separate WiFi network without any internet access

So it does look like help is coming in the foreseeable future.

1 Like
#7

Note regarding docs:

After a second look, the build instructions already has a link to the web server API.

However, it’s under the section “Home Assistant & Local Server”. I had completely overlooked that section because I thought it’s something specific to home assistant. I think a very minor re-write similar to what’s proposed in my previous comment can better direct people who are looking for using the local server.

1 Like
#8

Here’s an update/how-to-guide for those who Do not want to use any cloud / Home Assistant features and are evaluating the Airgradient for such a use case. Relevant use cases:

  • You just want to see the physical displays.
  • You just want a local HTTP API you can query

Brief Summary: The product is more than capable of working in the above modes! These things are mostly documented. My problem was only with the onboarding/discoverability of the docs (see the start of this thread) which the Airgradient team seem to be working on improving.

How-to guide:

If you just want to look at the displays in completely offline mode:

When the Airgradient starts up, you have a brief opportunity to press the button on the back and switch to completely offline mode (the display will indicate that it’s waiting for such a press). You don’t have to use WiFi at all.

If you want a local HTTP Server on the airgradient

The Airgradient creates its own access point for 3 minutes. (Password is “cleanair”), When connecting to the AP, you are greeted with a web page which can configure:

  • Which WiFi access point the Airgradient connects to.
  • Whether the airgradient should ever connect to the cloud.
    • This option had a bug which was fixed in Firmware 3.2.0.

Once configured, the airgradient will no longer create an access point and instead connects to the existing WiFi as configured. You can then query it using the local server API . You can also change most config from there.

Changing the access point

The only way to re-trigger the greeting screen and to make the Airgradient re-create its own access point, is to turn on the Airgradient out of reach of its host AP. E.g. you can turn off your router and re-start the Airgradient.

Changing connect-to-cloud toggle (Internally called disableCloud)

See “Changing the access point”. You have the opportunity to also adjust the checkbox responsible for this. You cannot change this setting from /config

1 Like
#9

I’ve submitted a merge request for that aforementioned bug. Help with testing would be appreciated.