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 below).

Click + and add the data management service. Toggle Syncing to the on position and set the sync interval to 0.05 minutes so that data syncs to the cloud every 3 seconds.

Add a tag to all your data so that you can query data from all your air quality sensors more easily in later steps. In the Tags field, type air-quality and click + Tag: air-quality when it appears to create a new tag. This tag will now automatically be applied to all data collected by this data manager.

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

• Type :Readings.
• Frequency: 0.1

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);
  });
});

To test the dashboard with your development machine, you can temporarily set your machine’s API key, API key ID and machine ID at the top of the main() function.

You can obtain your API key and API key ID from your machines CONNECT tab. You can copy the machine ID using the … menu at the top right and clicking Copy machine ID.

Now that you have the connection code, you are ready to add code that establishes a connection from the computer running the code to the Viam Cloud where the air quality sensor data is stored. 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);

Remove any API key or IDs before continuing.

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 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 harddrive called FILE>viam.json.

Run the preinstall script

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.