Monitor Air Quality with a Fleet of Sensors

Navigate to the Viam app in a web browser. Create an account and log in.

Click the dropdown in the upper-right corner of the FLEET page and use the + button to create a new organization for your air quality machine company. Name the organization and click Create.

Click FLEET in the upper-left corner of the page and click LOCATIONS. A new location called First Location is automatically generated for you. Use the … menu next to edit the location name to Development, then click Save.

Connect a PM sensor to a USB port on the machine’s SBC. Then connect your device to power.

If the computer does not already have a Viam-compatible operating system installed, follow the operating system setup section of the Quickstart guide to install a compatible operating system. You do not need to follow the “Install viam-server” section; you will do that in the next step!

Enable serial communication so that the SBC can communicate with the air quality sensor. For example, if you are using a Raspberry Pi, SSH to it and enable serial communication in raspi-config.

Add a new machine using the button in the top right corner of the LOCATIONS tab in the app. Follow the Set up your machine part instructions to install viam-server on the machine and connect it to the Viam app.

When your machine shows as connected, continue to the next step.

Navigate to the CONFIGURE tab of the machine, click the + button and select Component or service. Click sensor, then search for sds011 and add the sds001:v1 module. Name the sensor PM_sensor and click Create.

In the newly created PM_sensor card, replace the contents of the attributes box (the empty curly braces {}) with the following:

{
  "usb_interface": "<REPLACE WITH THE PATH YOU IDENTIFY>"
}

To figure out which port your sensor is connected to on your board, SSH to your board and run the following command:

ls /dev/serial/by-id

This should output a list of one or more USB devices attached to your board, for example usb-1a86_USB_Serial-if00-port0. If the air quality sensor is the only device plugged into your board, you can be confident that the only device listed is the correct one. If you have multiple devices plugged into different USB ports, you may need to choose one path and test it, or unplug something, to figure out which path to use.

Now that you have found the identifier, put the full path to the device into your config, for example:

{
  "usb_interface": "/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0"
}

Save the config.

On your sensor configuration panel, click on the TEST panel to check that you are getting readings from your sensor.

If you do not see readings, check the LOGS tab for errors, double-check that serial communication is enabled on the single board computer, and check that the usb_interface path is correctly specified.

Click + and add the data management service.

On the data manager panel:

• Toggle Syncing to the on position.
• Set the sync interval to 0.05 minutes (every 3 seconds).
• In the Tags field, add air-quality. This tag will now automatically be applied to all data collected by this data manager which will make querying data easier.

On the PM_sensor panel, click Add method to add data capture.

• Type: Readings.
• Frequency: 0.1 (every 10 seconds).

Save the config.

You can check that your sensor data is being synced by clicking on the … menu and clicking View captured data.

Make sure you have the latest version of Node.JS installed on your computer.

Create a directory on your laptop or desktop for your project. Name it aqi-dashboard.

Create a file in your aqi-dashboard folder and name it package.json. The package.json file holds necessary metadata about your project. Paste the following contents into it:

{
  "name": "air-quality-dashboard",
  "description": "A dashboard for visualizing data from air quality sensors.",
  "scripts": {
    "start": "esbuild ./main.ts --bundle --outfile=static/main.js --servedir=static --format=esm",
    "build": "esbuild ./main.ts --bundle --outfile=static/main.js --format=esm"
  },
  "author": "<YOUR NAME>",
  "license": "ISC",
  "devDependencies": {
    "esbuild": "*"
  },
  "dependencies": {
    "@viamrobotics/sdk": "^0.42.0",
    "bson": "^6.6.0",
    "js-cookie": "^3.0.5"
  }
}

Install the project’s dependencies by running the following command in your terminal:

npm install

Create another file inside the aqi-dashboard folder and name it main.ts. Paste the following code into main.ts:

// Air quality dashboard

import * as VIAM from "@viamrobotics/sdk";
import { BSON } from "bson";
import Cookies from "js-cookie";

let apiKeyId = "";
let apiKeySecret = "";
let hostname = "";
let machineId = "";

async function main() {
  const opts: VIAM.ViamClientOptions = {
    serviceHost: "https://app.viam.com",
    credentials: {
      type: "api-key",
      payload: apiKeySecret,
      authEntity: apiKeyId,
    },
  };

  // <Insert data client and query code here in later steps>

  // <Insert HTML block code here in later steps>
}

// <Insert getLastFewAv function definition here in later steps>

document.addEventListener("DOMContentLoaded", async () => {
  machineId = window.location.pathname.split("/")[2];
  ({
    id: apiKeyId,
    key: apiKeySecret,
    hostname: hostname,
  } = JSON.parse(Cookies.get(machineId)!));

  main().catch((error) => {
    console.error("encountered an error:", error);
  });
});

For developing your app on localhost, add the same information to your browser’s local storage.

Navigate to Camera Viewer and log in, then select your development machine.

Open Developer Tools, go to the console and paste the following JavaScript to obtain the cookies you need:

function generateCookieSetterScript() {
  // Get all cookies from current page
  const currentCookies = document.cookie.split(";");
  let cookieSetterCode = "// Cookie setter script for localhost\n";
  cookieSetterCode +=
    "// Copy and paste this entire script into your browser console when on localhost\n\n";

  // Process each cookie
  let cookieCount = 0;
  currentCookies.forEach((cookie) => {
    if (cookie.trim()) {
      // Extract name and value from the cookie
      const [name, value] = cookie.trim().split("=");

      // Add code to set this cookie
      cookieSetterCode += `document.cookie = "${name}=${value}; path=/";\n`;
      cookieCount++;
    }
  });

  // Add summary comment
  cookieSetterCode += `\nconsole.log("Set ${cookieCount} cookies on localhost");\n`;

  // Display the generated code
  console.log(cookieSetterCode);

  // Create a textarea element to make copying easier
  const textarea = document.createElement("textarea");
  textarea.value = cookieSetterCode;
  textarea.style.position = "fixed";
  textarea.style.top = "0";
  textarea.style.left = "0";
  textarea.style.width = "100%";
  textarea.style.height = "250px";
  textarea.style.zIndex = "9999";
  document.body.appendChild(textarea);
  textarea.focus();
  textarea.select();
}

// Execute the function
generateCookieSetterScript();

Copy the resulting script. It will look like this:

// Cookie setter script for localhost
// Copy and paste this entire script into your browser console when on localhost

document.cookie = "<SECRET COOKIE INFO>; path=/";
document.cookie = "machinesWhoseCredentialsAreStored=<MACHINE ID>; path=/";

console.log("Set 2 cookies on localhost");

Run the following command to serve the app you are building:

npm run start

Open the app in your browser at http://127.0.0.1:8000/.

Then, open developer tools, go to the console and paste the copied JavaScript code to set your cookies.

You’ll first create a client to obtain the organization and location ID. Then you’ll get a dataClient instance which accesses all the data in your location, and then query this data to get only the data tagged with the air-quality tag you applied with your data service configuration. The following code also queries the data for a list of the machines that have collected air quality data so that later, depending on the API key used with the code, your dashboard can show the data from any number of machines.

Paste the following code into the main function of your main.ts script, directly after the locationID line, in place of // <Insert data client and query code here in later steps>:

// Instantiate data_client and get all
// data tagged with "air-quality" from your location
const client = await VIAM.createViamClient(opts);
const machine = await client.appClient.getRobot(machineId);
const locationID = machine?.location;
const orgID = (await client.appClient.listOrganizations())[0].id;

const myDataClient = client.dataClient;
const query = {
  $match: {
    tags: "air-quality",
    location_id: locationID,
    organization_id: orgID,
  },
};
const match = { $group: { _id: "$robot_id" } };
// Get a list of all the IDs of machines that have collected air quality data
const BSONQueryForMachineIDList = [
  BSON.serialize(query),
  BSON.serialize(match),
];
let machineIDs: any = await myDataClient?.tabularDataByMQL(
  orgID,
  BSONQueryForMachineIDList,
);
// Get all the air quality data
const BSONQueryForData = [BSON.serialize(query)];
let measurements: any = await myDataClient?.tabularDataByMQL(
  orgID,
  BSONQueryForData,
);

For this project, your dashboard will display the average of the last five readings from each air sensor. You need a function to calculate that average. The data returned by the query is not necessarily returned in order, so this function must put the data in order based on timestamps before averaging the last five readings.

Paste the following code into main.ts after the end of your main function, in place of // <Insert getLastFewAv function definition here in later steps>:

// Get the average of the last five readings from a given sensor
async function getLastFewAv(all_measurements: any[], machineID: string) {
  // Get just the data from this machine
  let measurements = new Array();
  for (const entry of all_measurements) {
    if (entry.robot_id == machineID) {
      measurements.push({
        PM25: entry.data.readings["pm_2.5"],
        time: entry.time_received,
      });
    }
  }

  // Sort the air quality data from this machine
  // by timestamp
  measurements = measurements.sort(function (a, b) {
    let x = a.time.toString();
    let y = b.time.toString();
    if (x < y) {
      return -1;
    }
    if (x > y) {
      return 1;
    }
    return 0;
  });

  // Add up the last 5 readings collected.
  // If there are fewer than 5 readings, add all of them.
  let x = 5; // The number of readings to average over
  if (x > measurements.length) {
    x = measurements.length;
  }
  let total = 0;
  for (let i = 1; i <= x; i++) {
    const reading: number = measurements[measurements.length - i].PM25;
    total += reading;
  }
  // Return the average of the last few readings
  return total / x;
}

Now that you’ve defined the function to sort and average the data for each machine, you’re done with all the dataClient code. The final piece you need to add to this script is a way to create some HTML to display data from each machine in your dashboard.

Paste the following code into the main function of main.ts, in place of // <Insert HTML block code here in later steps>:

// Instantiate the HTML block that will be returned
// once everything is appended to it
let htmlblock: HTMLElement = document.createElement("div");

// Display the relevant data from each machine to the dashboard
for (let m of machineIDs) {
  let insideDiv: HTMLElement = document.createElement("div");
  let avgPM: number = await getLastFewAv(measurements, m._id);
  // Color-code the dashboard based on air quality category
  let level: string = "blue";
  switch (true) {
    case avgPM < 12.1: {
      level = "good";
      break;
    }
    case avgPM < 35.5: {
      level = "moderate";
      break;
    }
    case avgPM < 55.5: {
      level = "unhealthy-sensitive";
      break;
    }
    case avgPM < 150.5: {
      level = "unhealthy";
      break;
    }
    case avgPM < 250.5: {
      level = "very-unhealthy";
      break;
    }
    case avgPM >= 250.5: {
      level = "hazardous";
      break;
    }
  }
  let machineName = (await client.appClient.getRobot(m._id))?.name;
  // Create the HTML output for this machine
  insideDiv.className = "inner-div " + level;
  insideDiv.innerHTML =
    "<p>" +
    machineName +
    ": " +
    avgPM.toFixed(2).toString() +
    " &mu;g/m<sup>3</sup></p>";
  htmlblock.appendChild(insideDiv);
}

// Output a block of HTML with color-coded boxes for each machine
return document.getElementById("insert-readings")?.replaceWith(htmlblock);

Create a folder called static inside your aqi-dashboard folder. Inside the static folder, create a file called index.html. This file specifies the contents of the webpage that you will see when you run your code. Paste the following into index.html:

<!doctype html>
<html>
<head>
  <link rel="stylesheet" href="style.css">
</head>
<body>
  <div id="main">
    <div>
      <h1>Air Quality Dashboard</h1>
    </div>
    <script type="module" src="main.js"></script>
    <div>
      <h2>PM 2.5 readings</h2>
      <p>The following are averages of the last few readings from each machine:</p>
    </div>
    <div id="insert-readings">
      <p><i>Loading data...
        It may take a few moments for the data to load.
        Do not refresh page.</i></p>
    </div>
    <br>
    <div class="key">
      <h4 style="margin:5px 0px">Key:</h4>
      <p class="good">Good air quality</p>
      <p class="moderate">Moderate</p>
      <p class="unhealthy-sensitive">Unhealthy for sensitive groups</p>
      <p class="unhealthy">Unhealthy</p>
      <p class="very-unhealthy">Very unhealthy</p>
      <p class="hazardous">Hazardous</p>
    </div>
    <p>
      After the data has loaded, you can refresh the page for the latest readings.
    </p>
  </div>
</body>
</html>

Now you’ll create a style sheet to specify the fonts, colors, and spacing of your dashboard. Create a new file inside your static folder and name it style.css.

Paste the following into style.css:

body {
  font-family: Helvetica;
  margin-left: 20px;
}

div {
  background-color: whitesmoke;
}

h1 {
  color: black;
}

h2 {
  font-family: Helvetica;
}

.inner-div {
  font-family: monospace;
  border: .2px solid;
  background-color: lightblue;
  padding: 20px;
  margin-top: 10px;
  max-width: 320px;
  font-size: large;
}

.key {
  max-width: 200px;
  padding: 0px 5px 5px;
}

.key p {
  padding: 4px;
  margin: 0px;
}

.good {
  background-color: lightgreen;
}

.moderate {
  background-color: yellow;
}

.unhealthy-sensitive {
  background-color: orange;
}

.unhealthy {
  background-color: red;
}

.very-unhealthy {
  background-color: violet;
}

.hazardous {
  color: white;
  background-color: purple;
}

#main {
  max-width:600px;
  padding:10px 30px 10px;
}

Create a meta.json in your project folder using this template:

{
  "module_id": "<your-namespace>:air-quality",
  "visibility": "public",
  "url": "https://github.com/viam-labs/air-quality-fleet/",
  "description": "Display air quality data from a machine",
  "applications": [
    {
      "name": "air-quality",
      "type": "single_machine",
      "entrypoint": "static/index.html"
    }
  ]
}

In the Viam app, navigate to your organization settings through the menu in upper right corner of the page. Find the Public namespace and copy that string. Replace <your-namespace> with your public namespace.

Register your module with Viam:

viam module create --name="air-quality" --public-namespace="your-namespace"

Package your static files and your meta.json file and upload them to the Viam Registry:

npm run build
tar -czvf module.tar.gz static meta.json
viam module upload --upload=module.tar.gz --platform=any --version=0.0.1

For subsequent updates run these commands again with an updated version number.

Try your app by navigating to:

https://air-quality_your-public-namespace.viamapplications.com

Log in and select your development machine. Your dashboard should now load your data.

For each machine, flash the operating system to the device’s SD card. If you are using the Raspberry Pi Imager, you must customize at least the hostname for the next steps to work.

Then run the following commands to download the preinstall script and make the script executable:

wget https://storage.googleapis.com/packages.viam.com/apps/viam-agent/preinstall.sh
chmod 755 preinstall.sh

Create a file called viam-defaults.json with the following configuration:

{
  "network_configuration": {
    "manufacturer": "Pollution Monitoring Made Simple",
    "model": "v1",
    "fragment_id": "<FRAGMENT-ID>",
    "hotspot_prefix": "air-quality",
    "hotspot_password": "WeLoveCleanAir123"
  }
}

Replace "<FRAGMENT-ID>" with the fragment ID from your fragment.

In Organize your fleet you created several locations. Navigate to one of the locations and create a machine. Select the part status dropdown to the right of your machine’s name on the top of the page.

Click the copy icon next to Machine cloud credentials. Paste the machine cloud credentials into a file on your hard drive called FILE>viam.json.

Run the preinstall script without options and it will attempt to auto-detect a mounted root filesystem (or for Raspberry Pi, bootfs) and also automatically determine the architecture.

sudo ./preinstall.sh

Follow the instructions and provide the viam-defaults.json file and the machine cloud credentials file when prompted.