Foobot Air Quality Monitor

The Unofficial SmartThings Blog
Jump to navigation Jump to search

The Foobot Air Quality Monitor is a device that connects to your home's Wifi network and provides valuable information about the air quality in your house, including attributes such as temperature, humidity, volatile organic compounds, particulate matter, and carbon dioxide levels. This device integrates to SmartThings through a custom device type handler (DTH) that can be configured to periodically poll the Foobot API.



Product: Foobot Air Quality Monitor

Capabilities: Temperature, Humidity, Pollution state/percentage

Type: Air quality (CO2, Particles, Volitile Organic Compounds, etc)

Protocol: Physical device to cloud (API call)

Device Type Author: MichaelStruck (talk) 17:02, 3 January 2016 (EST) with code originally from @AdamV and @Kristopher

ST Community handle:

Latest Version

The latest version of the device code is as follows (as of 3/24/18):

   Foobot Air Quality Monitor DTH: 
   Version: 3.0.1

Open Source License/Trademarks

Licensed under the Apache License, Version 2.0 (the "License"); you may not use the Foobot Air Quality Monitor code except in compliance with the License. You may obtain a copy of the License at:

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

Obtain Your API Key and Device UUID

The setup of the DTH is a bit more involved than your normal SmartThings device. Because the device is setup on the cloud (and not through the SmartThings hub), you must configure the DTH to speak to the Foobot API to refresh the device data presented on the device page. To do this, you must obtain some specific information from Foobot to put into the DTH. Fortunately, this process for obtaining this information is well documented on the Foobot web site [1]. However, for the novice user you can use the consolidated instructions below.

To begin, navigate to the Foobot API site [2] or while on scroll to the very bottom of the screen and click the menu item API.

From there you will be presented with the opportunity to request an API. Click on the <<Request an API key>> link and enter your username and password.


You will then be presented with a very long string of character and numbers. This is your API key; make note of this (It is recommended to keep a text editor file with this information, along with your UUID which you will obtain next.)


Next, you will need to get the UUID (universally unique identifier) of the device you want the DTH to connect to. There are a couple ways to do this. The more manual way is in a web browser using your login ID along with the API key you obtained above to send a URL request to the Foobot site. Simply type this format into your url web address bar like this:{username}/device/?api_key={API_Key}

The web site should response with a bit of text that should display your UUID.


Make note of this UUID (the numbers between the quotation marks). Please note that if you have multiple devices you will be presented with a UUID for each of them. Be sure to use the correct UUID with the correct device.

The second way is to use the Foobot API web site [3]. If you obtained your API key from here, simple scroll down to the Identity API and type in your username in the space provided. The API Key should still be in memory and simply press <<Try it out!>>. Within the formatted response below this line you should also find your devices and the corresponding UUID for the device.



First, copy the code from the following GitHub location:

Click the Raw link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard. Then go to the SmartThings IDE at Log into the site and proceed to the link at the top labeled My Device Types. Click on this link.


This will present you with a list of custom device types that you may have within your account. If you do not yet have the virtual dimmer listed, click the link +New Device Type in the upper right-hand corner of the screen.


There will be three tabs at the top, which represent the different ways to add a device. Choose From Code and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.

From here, simply Save and Publish this code.


   The code for the Foobot device only needs to be installed in this manner once; 
   you can create multiple air quality monitors as long as this code is in place.

Find the section labeled My Devices at the top of Click this link.


On this next page you will be presented a list of all of the devices within your SmartThings account. These are typically the physical devices within your account. From here, find the button in the upper-right corner of the page labeled +New Device. Click this link and you will be presented a number of fields to fill in.


Starting at the top of the fields, fill out the name of the device. You can always change this name later within the SmartThings mobile application or the IDE.

Once you fill out the name, simply use the same name for the Label.

Since this is a virtual device, leave the Zigbee Id field blank.

For the field labeled Device Network Id, fill in a number that is unique to your environment (you may need to look at the list from the previous screen to determine what is unique.) This field is required, however, the number is not used anywhere else, so a simple “1234567890” could work well for this. Any subsequent devices created could build off of this (for example: “223456790”).

In the next field labeled Type, choose “Foobot Air Quality Monitor”.


The Version field should remain as “Published”, and both the Location and Hub should have your location’s hub listed. Ensure both of these fields are not empty, however Group can remain empty. When you are happy with your entries, click the Create button. You will be taken back to the My Devices page, which should now include your newly created virtual switch. You can always click on the switch again and edit it should you need to, or you can edit some of the attributes (such as the name) in the SmartThings mobile application on your phone or tablet.

Finally, you should include this newly added devce in any app that can use temperature, humdity or carbon dioxide measurements.

Advanced Installation

For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here:

Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions.

  • First, find the Settings button at the top of your SmartThings IDE page under My SmartApps or My Device Handlers(this button will only appear after you integrate with GitHub). For the virtual dimmer, ou should be under the My Device Handlers section


  • Clicking this button will open the GitHub Repository Integration page. To find the Foobot Air Quality Monitor code, enter the information as you see it below:

Owner: MichaelStruck

Name: SmartThingsPublic


  • Close the GitHub Repository Integration page
  • Next, click the Update from Repo button at the upper-right corner of the IDE
  • On the right-hand column, scroll down to click the apps you want to install. This will typically be:
   Foobot Air Quality Monitor: devicetypes/michaelstruck/foobot-air-quality-monitor.src/foobot-air-quality-monitor.groovy
  • Click the Execute Update in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.


Using the data obtain above (Foobot_Air_Quality_Monitor#Obtain_Your_API_Key_and_Device_UUID), you can configure your device handler. While in the handler on your mobile device, go to the upper-right corner of the screen and tap the small gear icon. This will bring you to the settings page.


From here, you should see the name you configured the IDE, along with different settings.

DTH Setting Notes
Device Name This is what the device is named within SmartThings (You set this up when setting up the device in the IDE). While recommended you keep this consistent with the name you gave the device when setting it up within the Foobot app, it is not required
UUID Obtained from the Foobot API web site. See Foobot_Air_Quality_Monitor#Obtain_Your_API_Key_and_Device_UUID
Region United States (US) or Europe (EU)
Temperature Units Either Celsius or Fahrenheit. You will need to refresh the data if you change this to see the new settings
Data Refresh Rate You are limited to 200 refreshes per day. This setting will allow you to refresh the data presented to the DTH from every 10 minutes to once per day.

For a more advanced way to enter this infomation, you can configure the settings via the IDE settings. It should be noted that you SHOULD NOT configure the Data Refresh Rate to anything less than 10 (minutes) on this page per the recommendations from Foobot.


API Key Installation

Unfortunately, the API Key is quite long and can not be entered using the DTH settings page. It must be installed into the code. To do this, go back to your SmartThings IDE and find the code you entered previously in the My Device Handlers section. Open it to edit the code.

Scroll down to the section labeled "getAPIKey().


Between the quotation marks, paste the API Key in this area. Then click Save, then Publish.


If everything went as it should, if you refresh the DTH page (using the refresh button), you will see the data populate on the screen.


There is a lot of useful information on the device screen.


Item Name Notes
A Global Pollution index An overall number representing the "pollution" from the readings from the device. The lights on the Foobot device mirror the color of the background (Blue being good, red being bad)
B GPI Summary Between "Great" and "Poor" based on the GPI number above. Great: 0-24, Good: 25-49, Fair:50-75, Poor: >75. This area also displays the local date/time the data was refreshed
C CO₂ Level According to Foobot, this level is derived from the VOC reading. The color of the background indicates relative safety levels, with levels below 1300ppm typically considered acceptable
D Volatile Organic Compounds The color of the background indicates relative safety levels, with levels below 300 ppb typically considered good
E Particulate Matter The color of the background indicates relative safety levels, with levels below 25 µg/m³ typically considered good
F Temperature This will reflect the units measurement you sent up here: Foobot_Air_Quality_Monitor#Setup
G Humidity Relative Humidity as reported by the device. Foobot recommends mid to low range to prevent mold growth
H Refresh Tapping this button will manually refresh the data. This will also reduce the number of daily polls from the Foobot API
I Remaining Daily Refreshes Foobot rate limits the refreshes to 200 per 24 hour period.

Developer Notes

The device type handler is set up with various attributes that can be accessed by Smartapps that have temperature, humidity, or carbon dioxide measurement capabilities. The access method for each of these attributes are outlined below:

Foobot Attribute Groovy Code Access Method Notes
Temperature {deviceName}.currentValue("temperature") Integer value (C or F depending on the Foobot_Air_Quality_Monitor#Set_up)
Relative Humidity {deviceName}.currentValue("humidity") Integer value (%)
Pollution {deviceName}.currentValue("pollution") Integer value (%)
GPI State {deviceName}.currentValue("GPIstate") String: "Great", "Good", "Fair" or "Poor"
Carbon Dioxide {deviceName}.currentValue("carbonDioxide") Integer value (parts per million)
GPI and Updated {deviceName}.currentValue("GPIupdated") Combination of the pollution measurement and the last updated date (format: "EEE, d MMM yyyy HH:mm:ss")
Volatile Organic Compounds {deviceName}.currentVoc Integer value (parts per billion)
Particulate Matter {deviceName}.currentParticle Integer value (µg/m³)
Last Updated {deviceName}.currentLastUpdated Date format: "EEE, d MMM yyyy HH:mm:ss"
Refreshes Remaining {deviceName}.currentRefreshes Integer value from the Foobot API with the number of remaining refreshes for the day

The only available commands for this DTH are poll() and refresh(). These will refresh the data in your DTH.

   Please Note
   Foobot recommends polling no less than at 5 minutes intervals as that is how often the device updates 
   the cloud database. You may poll on demand from your app using the poll() or refresh() command, or you 
   can have the DTH refresh (re-poll) on its own under the settings (see: Foobot_Air_Quality_Monitor#Setup). 
   Again, Foobot limits the number of polls during the day to 200, and the current number remaining is displayed
   on the main DTH page.