It took me a long time to figure out how to flash custom software to my AirGradient ONE and then even longer to figure out how to do it entirely from the command-line, so I wrote up a tutorial for anyone else interested in doing the same:
Suggestions welcome for improving this process.
Nice article, thanks for sharing.
The Aside section is a bit harsh. Yes, there were issues, but they were fixed. Also, AG people are actually spending time on improving the displayed data and adding correction algorithms where necessary. And all this happens in the open. If you’re still unhappy, you can always flash esphome and use that. Not sure how many other companies are this open and allow this level of freedom with their monitors.
Thanks for reading!
The
Asidesection is a bit harsh. Yes, there were issues, but they were fixed. Also, AG people are actually spending time on improving the displayed data and adding correction algorithms where necessary. And all this happens in the open.
I still support the project and want it to improve, but candidly, I do find the quality of the documentation and software disappointing at this stage.
When you open the box, the only documentation is a link to the thank you page (https://www.airgradient[.]com/thank-you/), and then it’s four separate page navigations to find documentation for the device I purchased. And then there’s not even advice about how to set it up, just a link to the API documentation. I talked about this a year ago and AirGradient said they’d improve the documentation, and I haven’t seen any progress. Meanwhile, they’re quick to write a detailed rebuttal to a negative review.
I don’t know what issues you’re referring to that have been fixed, but I’m experiencing more issues with the latest firmware (3.3.8) than I had with the version I installed in January 2024.
I’m not trying to rag on the project, but I am frustrated and would like to see more investment in the documentation and pre-release quality assurance testing.
And, as I’m posting this, the forum software is blocking me with opaque “You can’t post a link to that host” messages because I’m trying to link to pages on the airgradient domain, so it just feels like I keep hitting careless errors.
If you have suggestions for improving the documentation in the GitHub repo, I encourage you to submit a PR with your suggested changes and maybe we can get it improved for the community.
If you have suggestions for the website, I encourage you to fill out the support form at https://www.airgradient.com/support/ and explain what is a rough user experience along with some suggestions on how to improve. This way it is tracked in their system and they can share it with the different team members.
The forum is a good place for discussions with other users as well, but when it comes to how the business is operating, I’ve had better experience with direct support.
I’ve also been asking for improvements on the API documentation that I haven’t seen yet, so I hear you on things that need to improve, but I try to offer some direct suggestions so it isn’t just “This isn’t good” and leave it up to them to live up to my expectations in a vacuum.
Yep, I’m contributing on their Github repos. I can’t link to them because Github is bizarrely one of the banned domains on this forum.
But I’m reporting issues and making fixes slowly, as I don’t want to waste my time. Last time I tried contributing, I spent several hours making fixes to my fork, and they rejected all of them because they did a complete rewrite of the code without warning anyone, so I don’t want to get burned again.
Apparently, every time I post to this thread, my previous post to this thread gets marked as spam?
@Achim_AirGradient - Is this intentional?
@mtlynch – I agree with your points about documentation, but I’d also like to mention that the team at AirGradient is always listening and working to improve. @Achim_AirGradient especially is always trying to ensure that everyone is heard by constantly engaging with the community. With my recent addition to the team, we’ve specifically allocated resources to enhancing our documentation and creating a more user-friendly FAQ on our website. This is one of the projects that @Ethan_AirGradient and I will be focusing on. We’re aware of our current limitations, and we’re committed to addressing them as best as we can.
RE: the firmware issues, it would be helpful if you could contact us via https://www.airgradient.com/support/ and let us know of the issues you’re having on 3.3.8 so we could document these and inform the team.
My original post in this thread is still blocked. Is that intentional?
I’ve also started a thread to discuss the link blocks, as I’m not sure why the forum is treating legitimate links to AirGradient or Github as spam:
Should be unblocked now. No, as I said before, this is not intentional. The forum hides posts with external links until they are reviewed manually. This is to prevent spam and potential phishing.
If repeat links are posted in comments, the post goes into review again.
Just a few quick notes from my side (it’s 4am here).
We unfortunately had a lot of spam coming into the forum and that somehow triggered discourse to be quite restrictive on published links etc. obviously our own ones should not be affected and we are looking into it.
As @Altair_AirGradient already mentioned we have put considerably additional resources into support and part of it is improving documentation. Our firmware quality made huge improvements over the last year as can be seen by many releases. This includes the documentation in the GitHub repository.
As some of the previous posters mentioned, we spent a very considerable amount last 12 months on improving calibration features in the dashboard and firmware. So the software gside has also been continuously improved.
The open-source nature of the product unfortunately makes it more complex to manage it as it allows a lot more customizations that a regular product doesn’t have.
Having said that, I agree that we need to improve the documentation and are working on it. However you also mention you find the software disappointing. Do you mean the firmware or dashboard? Can you give some examples what you are missing?
Lastly you mention the Wired review rebuttal. I am personally involved in this, and there is much more to the story than I can publish here but I don’t think it was necessary for you to pull this topic into this conversation. Let’s keep this focused on how we can improve the documentation.
Also, please let me know if you would be interested to hop on a call with me and Altair and we can also personally discuss your frustrations. Sometimes a more personal conversation can be very helpful (this is not to sidetrack this public conversation here, just an opportunity to get to know each other better).
The firmware.
I ran a version from January 2024 until recently, but it would lose WiFi connectivity several times per day. I thought maybe I just had a dud piece of hardware, but I saw the same behavior when I bought a second unit recently.
I flashed both to 3.3.8, and now one periodically gains and loses WiFi connectivity, and the other was doing the same and then just permanently lost it. I’ve never experienced a device that loses WiFi connectivity when it’s sitting six feet away from my WiFi AP, unobstructed.
I tried flashing to 3.3.9, which is marked as a stable release on Github, but it caused both units to fail to measure CO2 and temperature.
I also discovered the hard way that saying, “Never send data to AirGradient” means, “Never send data to any server, even a local one I specify explicitly.” And it seems that the only way to undo the setting is to totally erase flash and start over.
The meta-issue is that there are a lot of bugs that I just don’t even report or remember because I see AirGradient neglecting bug reports and PRs. For example, issue #316 on the Github repo has been sitting unaddressed for 3.5 months even though it’s a well-formed question. I submitted what I think is a pretty uncontroversial PR to airgradient-client and there’s been no response.
Sure, that would be great. Feel free to email me (either through my blog or to the email I used to place my AirGradient order), and we can figure out a time to hop on a call.
Sent you an email and looking forward to chat. After the call, we keep the forum here informed.
I ran a version from January 2024 until recently, but it would lose WiFi connectivity several times per day. I thought maybe I just had a dud piece of hardware, but I saw the same behavior when I bought a second unit recently.
It may be your wifi. I had the same issue until I upgraded my wifi to Unifi and created a specific SSID for these types of devices (with unifi’s option to optimize for IoT enabled). Now it’s rock-solid.
I just got off the call with @Achim_AirGradient, @Samuel_AirGradient, and @Altair_AirGradient. It was a very nice discussion, and I think we covered a lot of important topics.
I’ll try to summarize from my end, but the AirGradient folks are welcome to add or correct details if they had different takeaways.
My biggest note was that I felt a disconnect between the AirGradient team and the community. I had a recent PR and a recent issue that have sat without acknowledgment from the AirGradient team for two weeks.
I don’t expect issues to be fixed or PRs to be merged immediately, but I’d feel much more encouraged to contribute to development if there was a timely response (i.e., within 2-3 business days) to at least acknowledge the contributions and set expectations about next steps.
The AirGradient team didn’t realize that the issue and PR had sat unaddressed for two weeks, but they’re aware that they need to do a better job staying on top of user contributions.
Resolution: AirGradient will explore ways of keeping better track of untriaged issues/PRs and unaddressed support forum posts so that users can feel confident that when they report an issue / make a PR, they’ll get a response from AirGradient.
I shared that I found AirGradient’s branching strategy confusing, as I had contributed docs improvements, but they’re still not discoverable on the repo README because the repo’s default branch is master and my changes were merged into the develop branch.
The AirGradient team explained that they use develop for development and they leave master unchanged until they’re ready to cut a new tagged release. They worried that if they merged changes directly into master that users who are making customizations might unintentionally branch from master and not realize it’s an unstable branch.
I suggested AirGradient get rid of the separate develop branch and do all development in master. For a project with tagged releases, I think it’s most common for master to be be unstable and the tagged releases to be stable. If AirGradient ever needs to do a minor bugfix on a tagged release, they can still branch from the release tag. End-users who want to customize the firmware can branch from a tagged release for stability or from master for a bleeding edge version.
Resolution: AirGradient will consider consolidating master and develop branches into a single master branch.
The latest tagged release on Github is 3.3.9, but the latest release on the AirGradient website is 3.3.8.
The AirGradient team shared that they’d like to fully automate this so that the tags always match globally, but currently they do not match. The canonical release is what’s on the AirGradient website
Resolution: The AirGradient team will consider marking the Github release as “pre-release” until it’s officially the release. The AirGradient team will work on automating the release more so that there’s a single, canonical release on both Github, the website, and the Airgradient dashboard.
I shared that my onboarding flow as a new AirGradient customer felt shaky both times I purchased the One indoor unit. The instructions in my package tell me to visit Thank You for Purchasing our Kit for setup instructions, but that’s the URL all AirGradient products share. It’s another four clicks to get to the AirGradient ONE indoor unit (pre-assembled).
Once I get to the AirGradient ONE instructions, I’m dumped here, which still doesn’t tell me the basics of setting up my device (e.g., how to connect to my Wi-Fi, how to put on the feet). The first option (AirGradient Cloud) requires me to create an account before seeing any instructions.
Resolution: I suggested that devices ship with a product-specific instructions URL so that the user could visit instructions for their specific product directly like airgradient.com/ag1-a to show the basics and then once that’s complete, allow them to pick how to collect data from their unit.
We discussed this recent issue I filed:
The AirGradient team shared that they make the disableCloudConnection connection especially strict (read-only after initial Wifi setup) to prevent users from accidentally uploading data to AirGradient cloud.
I suggested an overhaul of the REST API, as a lot of the semantics are confusing (e.g., I thought disableCloudConnection disables the default connection to AirGradient Cloud, but it actually disables external connections to any server, even if the user specifies one, I thought bootCount measures how many times the device has booted, but it’s actually the number of measurement cycles since boot).
Resolution: The AirGradient team will consider making disableCloudConnection writable after initial WiFi setup, which will at least create a path where the user can upload measurements to a local server without leaking data to AirGradient Cloud. The AirGradient team will consider a revision of the REST API to make it easier for API client development.
Thanks again for taking the time to speak with me! I look forward to further collaboration.
Thanks for the summary!
Yes the call was very good and extremely helpful to see things from a user and customer perspective which sometimes get difficult to have from the inside.
The open nature of our products unfortunately adds an additional level of complexity which locked down, proprietary products don’t have and at the same time being bootstrapped we need to manage our resources.
However I do agree with above points and we have already started addressing some of them, and the others are in the pipeline.
I agree with nearly every topic you mentioned and look forward to seeing the improvements.
I have also experienced the confusion with the branching strategy where changes are merged into develop but take even longer to make it to main, particularly when it comes to just documentation that isn’t made available for quite some time. Especially frustrating after a PR has been sitting for a long time without comment.
On the release versions, I completely agree with using a git tag to indicate the actual release version. Once a version is being pushed by the Dashboard to actual devices, it should be considered a full release and be available on the Firmware website and in GitHub with all the same version. If that takes manual work to update on the Firmware page, so be it, until full automation can update that, but if the work is done to get it pushed on the Dashboard, that is about as official as you can get and everything needs to be in sync at that point.
I’m glad you got to discuss your Local Data Server topic with them. Since the devices already have a local API server that can be queried, are discoverable by Home Assistant, and can send metrics to an MQTT destination, there are lots of options available. Having another of expecting users to have setup their own clone of the AirGradient API server to receive data isn’t something I would expect to be a regular use case, but I’m all for options.
These two seem closely related.
I don’t think it’s so much the fact that AirGradient is open-source that causes complexity, but I think customers that seek out open-source products tend to want to interact with the product in ways that aren’t possible with proprietary products.
If the AirGradient team is struggling with keeping up with maintenance, I think the right solution is to narrow scope. And a pretty easy cut is to eliminate two different APIs that do the same thing (REST API for querying measurement values + custom httpDomain value to push measurements to a custom server).
I’m fine with querying the AirGradient REST API rather than pointing my device at a server that replicates the AirGradient Cloud API. The reason I reimplemented the AirGradient Cloud API was that I wanted OTA updates, which are not possible through the REST API.
Is one path more supported than the other? Perhaps the AirGradient team can mark the one they don’t want people to build on as deprecated and schedule it for EOL in a future release.
I’m fine with deprecation, as we don’t need multiple ways of doing the same thing, but I would like to know which is the supported, blessed way of doing things like collecting measurements or doing OTA updates without AirGradient Cloud so that I can focus on building around that path.