Visualize sensor data from any machines

Once you have used the data management service to capture data, you can visualize your data with a variety of third-party tools, including Grafana, Tableau, Google’s Looker Studio, and more. You can choose to visualize data from a component on one machine, from multiple components together, or from many components across a fleet of machines.

For example, you can configure data capture for several sensors across multiple machines to report the ambient operating temperature. You can then visualize that data to easily understand how the ambient temperature affects your machines’ operation.

You can do all of this using the Viam app user interface. You will not need to write any code.

Prerequisites

Captured sensor data. Click to see instructions.
Follow the guide to capture sensor data.
The Viam CLI to set up data query. Click to see instructions.

You must have the Viam CLI installed to configure querying with third-party tools.

To download the Viam CLI on a macOS computer, run the following commands:

brew tap viamrobotics/brews
brew install viam

To download the Viam CLI on a Linux computer with the aarch64 architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-arm64
sudo chmod a+rx /usr/local/bin/viam

To download the Viam CLI on a Linux computer with the amd64 (Intel x86_64) architecture, run the following commands:

sudo curl -o /usr/local/bin/viam https://storage.googleapis.com/packages.viam.com/apps/viam-cli/viam-cli-stable-linux-amd64
sudo chmod a+rx /usr/local/bin/viam

You can also install the Viam CLI using brew on Linux amd64 (Intel x86_64):

brew tap viamrobotics/brews
brew install viam

If you have Go installed, you can build the Viam CLI directly from source using the go install command:

go install go.viam.com/rdk/cli/viam@latest

To confirm viam is installed and ready to use, issue the viam command from your terminal. If you see help instructions, everything is correctly installed. If you do not see help instructions, add your local go/bin/* directory to your PATH variable. If you use bash as your shell, you can use the following command:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.bashrc

For more information see install the Viam CLI.

Configure data query

If you want to query data from third party tools, you have to configure data query to obtain the credentials you need to connect to the third party service.

1. Authenticate with the CLI

Authenticate using a personal access token:

viam login

2. Find your organization ID

To create a database user allowing you to access your data, find your organization ID:

viam organizations list

3. Configure a new database user

Configure a new database user for the Viam organization’s MongoDB Atlas Data Federation instance, which is where your machine’s synced data is stored.

Provide your organization’s org-id from step 2, and a password for your database user. Your password must be at least 8 characters long, and include at least one uppercase, one number, and one special character (such as $ or %):

viam data database configure --org-id=<YOUR-ORGANIZATION-ID> --password=<NEW-DBUSER-PASSWORD>

This command configures a database user for your organization for use with data query, and sets the password. If you have run this command before, this command instead updates the password to the new value you set.

4. Determine the connection URI

Determine the connection URI (also known as a connection string) for your organization’s MongoDB Atlas Data Federation instance by running the following command with the organization’s org-id from step 2:

viam data database hostname --org-id=abcd1e2f-a1b2-3c45-de6f-ab123456c123
MongoDB Atlas Data Federation instance hostname: data-federation-abcd1e2f-a1b2-3c45-de6f-ab123456c123-0z9yx.a.query.mongodb.net
MongoDB Atlas Data Federation instance connection URI: mongodb://db-user-abcd1e2f-a1b2-3c45-de6f-ab123456c123:YOUR-PASSWORD-HERE@data-federation-abcd1e2f-a1b2-3c45-de6f-ab123456c123-0z9yx.a.query.mongodb.net/?ssl=true&authSource=admin

This command returns both the connection URI to your organization’s MongoDB Atlas Data Federation instance, as well as its hostname and database name:

  • Most MQL-compatible database clients require the connection URI, along with your user credentials, to connect to this server.
  • Some MQL-compatible database client instead require a hostname and database name, along with your user credentials, to connect to this server.

You will need this information to query your data in the next section.

Visualize data with third-party tools

When you sync captured data to Viam, that data is stored in the Viam organization’s MongoDB Atlas Data Federation instance. Your chosen third-party visualization tool must be able to connect to a MongoDB Atlas Data Federation instance as its data store.

Select a tab below to learn how to configure your visualization tool for use with Viam:

1. Choose Grafana instance

Install or set up Grafana. You can use either a local instance of Grafana or Grafana Cloud, and can use the free trial version of Grafana if desired.

2. Install connector to MongoDB data source

Navigate to your Grafana web UI, and add the Grafana MongoDB data source plugin to your Grafana instance.

The Grafana plugin search interface showing the results for a search for mongodb

3. Configure a data connection

Navigate to the Grafana data source management page, and select the Grafana MongoDB data source that you just added.

Enter the following information in the configuration UI for that plugin:

  • Connection string: Enter the following connection string, and replace <MONGODB-ATLAS-DF-HOSTNAME> with your database hostname as configured with the viam data database configure command, and replace <DATABASE-NAME> with the desired database name to query:

    mongodb://<MONGODB-ATLAS-DF-HOSTNAME>/<DATABASE-NAME>?directConnection=true&authSource=admin&tls=true
    
  • User: Enter the following username, substituting your organization ID as determined earlier, for <YOUR-ORG-ID>:

    db-user-<YOUR-ORG-ID>
    
  • Password: Enter the password you provided earlier.

    The Grafana data source plugin configuration page, showing the connection string and username filled in with the configuration determined from the previous steps

4. Use Grafana for dashboards

With your data connection established, you can then build dashboards that provide insight into your data.

Grafana additionally supports the ability to directly query and transform your data within a dashboard to generate more granular visualizations of specific data. You might use this functionality to visualize only a single day’s metrics, limit the visualization to a select machine or component, or to isolate an outlier in your reported data, for example.

You can query your captured data within a Grafana dashboard using either SQL or MQL. See the guide on querying sensor data for more information.

1. Install connector to MongoDB data source

Some visualization clients are able to connect to the Viam MongoDB Atlas Data Federation instance natively, while others require that you install and configure an additional plugin or connector. For example, Tableau requires both the Atlas SQL JDBC Driver as well as the the Tableau Connector in order to successfully connect and access data.

Check with the documentation for your third-party visualization tool to be sure you have the required additional software installed to connect to a MongoDB Atlas Data Federation instance.

2. Configure a data connection

Most third-party visualization tools require the connection URI (also called the connection string) to that database server, and the credentials to authenticate to that server in order to visualize your data. Some third-party tools instead require a hostname and database name of the database server. This is what they look like:

If your client supports a connection URI, use the following format and replace YOUR-PASSWORD-HERE with your database password as configured with the viam data database configure command:

mongodb://db-user-abcdef12-abcd-abcd-abcd-abcdef123456:YOUR-PASSWORD-HERE@data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/?ssl=true&authSource=admin

You can also specify a desired database name in your connection URI, if desired. For example, to use the sensorData database, the default name for uploaded data, your connection string would resemble:

mongodb://db-user-abcdef12-abcd-abcd-abcd-abcdef123456:YOUR-PASSWORD-HERE@data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/sensorData?ssl=true&authSource=admin

If you client doesn’t use a connection URI, you can supply the hostname and database name of the database server instead. Substitute the hostname returned from the viam data database hostname command for <MONGODB-ATLAS-DF-HOSTNAME> and the desired database name to query for <DATABASE-NAME>:

mongodb://<MONGODB-ATLAS-DF-HOSTNAME>/<DATABASE-NAME>?directConnection=true&authSource=admin&tls=true

For example, to use the sensorData database, the default name for uploaded data, your connection string would resemble:

mongodb://data-federation-abcdef12-abcd-abcd-abcd-abcdef123456-e4irv.a.query.mongodb.net/sensorData?directConnection=true&authSource=admin&tls=true

If you are using a connection URI, the hostname and database name are already included in the URI string.

You database user name is of the following form:

db-user-<YOUR-ORG-ID>

Substitute your organization ID for <YOUR-ORG-ID>.

3. Use visualization tools for dashboards

Some third-party visualization tools support the ability to directly query your data within their platform to generate more granular visualizations of specific data. You might use this functionality to visualize only a single day’s metrics, limit the visualization to a select machine or component, or to isolate an outlier in your reported data, for example.

While every third-party tool is different, you would generally query your data using either SQL or MQL. See the guide on querying sensor data for more information.

Next steps

For more detailed instructions on using Grafana, including a full step-by-step configuration walkthrough, see visualizing data with Grafana.

On top of visualizing sensor data with third-party tools, you can also query it with the Python SDK or query it with the Viam app.

To see full projects using visualization, check out these resources:

Have questions, or want to meet other people working on robots? Join our Community Discord.

If you notice any issues with the documentation, feel free to file an issue or edit this file.