Visualize data

Build dashboards and monitoring views for your captured data. Visualization helps you spot trends, detect anomalies, and monitor machine health.

Viam stores captured data in a MongoDB Atlas Data Federation instance. This means that you can use any tool that can connect to MongoDB to access your data. This page covers four approaches to visualization, from simplest to most flexible.

Viam Teleop dashboards live inside the Viam app. They are scoped to a single machine and location, and they update in real time. You do not need to configure any database credentials or install any software. This makes them the right choice when you want a quick operational view of one machine.

External tools like Grafana connect to the underlying MongoDB data store. They can query data across machines and organizations, apply complex transformations, set up alerts, and share dashboards with team members who do not have Viam app access.

Custom visualization with Viam SDKs gives you complete control. You write code that queries data through the Viam SDK and renders it however you want – matplotlib charts, Plotly dashboards, HTML reports, or any other format.

Build a Viam Teleop dashboard

The Viam Teleop dashboard is the fastest way to visualize data from a single machine.

Create a workspace

1. Go to app.viam.com.
2. Click FLEET in the top navigation, then click the TELEOP tab. You can also navigate directly to app.viam.com/teleop.
3. Click + Create workspace.
4. In the top left of the page, replace the placeholder untitled-workspace text with a descriptive name for your workspace (for example, “Sensor Monitor” or “Factory Floor Cameras”).
5. Use the Select location dropdown to choose the location that contains your machine.
6. Use the Select machine dropdown to choose the machine you want to visualize data from.

Add widgets

1. Click Add widget and select a widget type. Available widget types include:

   • Time-series chart – plots sensor values over time.
   • Camera feed – shows a live camera stream.
   • Value display – shows the current reading from a sensor.
   • Button – triggers an action on the machine.

   Additional widget types may be available depending on your machine’s components.

2. To configure a widget, click the pencil icon in the top right corner of the widget. This opens the widget settings where you select which component and data source the widget displays.

   

3. Repeat for each widget you want on the dashboard. You can mix camera feeds, time-series charts, and value displays on the same workspace.

   

Arrange the layout

• Click and drag the grid icon in the top left corner of any widget to reposition it.
• Resize widgets by dragging their edges.
• The layout saves automatically.

You now have a live dashboard showing real-time data from your machine. The dashboard updates as new data arrives – no refresh needed.

Configure database access for third-party tools

To connect external visualization tools (Grafana, Tableau, Looker Studio, or any MongoDB-compatible client), you first need to set up database credentials using the Viam CLI.

Install the Viam CLI if you have not already:

brew tap viamrobotics/brews
brew install viam

sudo curl --compressed -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

sudo curl --compressed -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

brew tap viamrobotics/brews
brew install viam

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

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

For more information see install the Viam CLI.

viam login

viam organizations list

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

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

You now have three pieces of information needed by any external tool:

• Hostname (from the hostname command)
• Username: db-user-<YOUR-ORG-ID>
• Password (from the configure command)

Connect Grafana to your data

Grafana is a popular open-source visualization tool that works well with Viam’s MongoDB-backed data store.

Install Grafana

If you do not already have a Grafana instance:

• Grafana Cloud: Sign up at grafana.com. The free tier is sufficient for testing.
• Local Grafana Enterprise: Install following the official Grafana installation guide.

Install the MongoDB data source plugin

1. Open your Grafana web UI.

2. Navigate to Connections > Add new connection.

3. Search for MongoDB.

   

4. Install the Grafana MongoDB data source plugin.

Configure the data connection

1. After installing the plugin, go to its configuration page and click Add new data source.

2. Fill in the following fields:

   • Connection string:

     mongodb://<HOSTNAME>/sensorData?directConnection=true&authSource=admin&tls=true
     

     Replace <HOSTNAME> with the hostname from Configure database access.

   • User: db-user-<YOUR-ORG-ID>

   • Password: The password you set with the viam data database configure command.

   

   For more information on the Grafana MongoDB plugin, see Configure the MongoDB data source.

3. Click Save & test. Grafana should confirm the connection is working.

Build a Grafana dashboard

1. Click Dashboards in the left sidebar, then New > New dashboard.

2. Click Add visualization.

3. Select the MongoDB data source you just configured.

4. In the query editor, enter an MQL query. For example, to plot sensor readings over time:

   sensorData.readings.aggregate([
     {
       $match: {
         component_name: "sensor-1",
         time_received: { $gte: ISODate(${__from}) }
       }
     },
     { $sort: { time_received: 1 } },
     { $limit: 1000 }
   ])
   

   Replace sensor-1 with the name of your component.

   The ${__from} and ${__to} variables are Grafana global variables populated by the time range selector at the top of your dashboard. When you change the time range, the query updates automatically.

5. Click Run query to see results.

6. Choose a visualization type (Time series, Gauge, Stat, Table, etc.) from the panel options on the right.

7. Click Apply to add the panel to your dashboard.

Useful query patterns for Grafana

Average sensor value per hour:

sensorData.readings.aggregate([
  {
    $match: {
      component_name: "my-sensor",
      time_received: { $gte: ISODate(${__from}), $lte: ISODate(${__to}) }
    }
  },
  {
    $group: {
      _id: {
        $dateToString: { format: "%Y-%m-%d %H:00", date: "$time_received" }
      },
      avg_value: { $avg: "$data.readings.temperature" },
      count: { $sum: 1 }
    }
  },
  { $sort: { _id: 1 } }
])

Count of readings per component:

sensorData.readings.aggregate([
  {
    $match: {
      time_received: { $gte: ISODate(${__from}) }
    }
  },
  {
    $group: {
      _id: "$component_name",
      count: { $sum: 1 }
    }
  },
  { $sort: { count: -1 } }
])

Connect other third-party tools

The database credentials from Configure database access work with any tool that supports MongoDB Atlas Data Federation as a data store. The general pattern is the same:

1. Install the tool’s MongoDB connector or driver. For example:

   • Tableau requires the Atlas SQL JDBC Driver and the Tableau Connector.
   • Google Looker Studio supports MongoDB connections natively through community connectors.

2. Configure the connection using one of these formats:

   Connection URI format (most tools):

   mongodb://db-user-<YOUR-ORG-ID>:<YOUR-PASSWORD>@<HOSTNAME>/sensorData?tls=true&authSource=admin
   

   Hostname + credentials format (tools that ask for fields separately):

   • Hostname: the value from viam data database hostname
   • Database name: sensorData
   • Username: db-user-<YOUR-ORG-ID>
   • Password: from the configure command

3. Build dashboards using the tool’s native interface.

Custom visualizations with Viam SDKs

When you need full control over visualization – embedding charts in your own application, generating reports, or running in a Jupyter notebook – use the Viam SDK to query data and a plotting library to render it.

pip install viam-sdk matplotlib

import asyncio
from datetime import datetime, timedelta, timezone

import matplotlib.pyplot as plt
import matplotlib.dates as mdates
from viam.rpc.dial import DialOptions, Credentials
from viam.app.viam_client import ViamClient


API_KEY = "YOUR-API-KEY"
API_KEY_ID = "YOUR-API-KEY-ID"
ORG_ID = "YOUR-ORGANIZATION-ID"


async def connect() -> ViamClient:
    dial_options = DialOptions(
        credentials=Credentials(
            type="api-key",
            payload=API_KEY,
        ),
        auth_entity=API_KEY_ID,
    )
    return await ViamClient.create_from_dial_options(dial_options)


async def main():
    viam_client = await connect()
    data_client = viam_client.data_client

    # Query the last 24 hours of sensor data.
    data = await data_client.tabular_data_by_mql(
        organization_id=ORG_ID,
        query=[
            {"$match": {
                "component_name": "my-sensor",
                "time_received": {
                    "$gte": {"$date": (
                        datetime.now(timezone.utc) - timedelta(hours=24)
                    ).isoformat()}
                },
            }},
            {"$sort": {"time_received": 1}},
            {"$limit": 1000},
            {"$project": {
                "time_received": 1,
                "temperature": "$data.readings.temperature",
                "_id": 0,
            }},
        ],
    )

    if not data:
        print("No data returned. Check your component name and time range.")
        viam_client.close()
        return

    # Extract timestamps and values.
    timestamps = [entry["time_received"] for entry in data]
    temperatures = [entry["temperature"] for entry in data]

    # Plot the data.
    fig, ax = plt.subplots(figsize=(12, 5))
    ax.plot(timestamps, temperatures, linewidth=1.5, color="#3b82f6")
    ax.set_xlabel("Time")
    ax.set_ylabel("Temperature")
    ax.set_title("Sensor Temperature - Last 24 Hours")
    ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M"))
    ax.grid(True, alpha=0.3)
    fig.autofmt_xdate()
    plt.tight_layout()

    # Save to file and show.
    plt.savefig("temperature_chart.png", dpi=150)
    print("Chart saved to temperature_chart.png")
    plt.show()

    viam_client.close()


if __name__ == "__main__":
    asyncio.run(main())

python visualize_data.py

mkdir visualize-data && cd visualize-data
go mod init visualize-data
go get go.viam.com/rdk
go get gonum.org/v1/plot

package main

import (
    "context"
    "fmt"
    "time"

    "go.viam.com/rdk/app"
    "go.viam.com/rdk/logging"
    "gonum.org/v1/plot"
    "gonum.org/v1/plot/plotter"
    "gonum.org/v1/plot/vg"
)

func main() {
    apiKey := "YOUR-API-KEY"
    apiKeyID := "YOUR-API-KEY-ID"
    orgID := "YOUR-ORGANIZATION-ID"

    ctx := context.Background()
    logger := logging.NewDebugLogger("visualize-data")

    viamClient, err := app.CreateViamClientWithAPIKey(
        ctx, app.Options{}, apiKey, apiKeyID, logger)
    if err != nil {
        logger.Fatal(err)
    }
    defer viamClient.Close()

    dataClient := viamClient.DataClient()

    // Query the last 24 hours of sensor data.
    cutoff := time.Now().UTC().Add(-24 * time.Hour)
    mqlStages := []map[string]interface{}{
        {"$match": map[string]interface{}{
            "component_name": "my-sensor",
            "time_received": map[string]interface{}{
                "$gte": map[string]interface{}{
                    "$date": cutoff.Format(time.RFC3339),
                },
            },
        }},
        {"$sort": map[string]interface{}{"time_received": 1}},
        {"$limit": 1000},
        {"$project": map[string]interface{}{
            "time_received": 1,
            "temperature":   "$data.readings.temperature",
            "_id":           0,
        }},
    }

    results, err := dataClient.TabularDataByMQL(ctx, orgID, mqlStages, nil)
    if err != nil {
        logger.Fatal(err)
    }

    if len(results) == 0 {
        fmt.Println("No data returned. Check your component name and time range.")
        return
    }

    // Build plot data points.
    pts := make(plotter.XYs, len(results))
    for i, entry := range results {
        // Extract timestamp as float (seconds since epoch).
        if t, ok := entry["time_received"].(time.Time); ok {
            pts[i].X = float64(t.Unix())
        }
        // Extract temperature value.
        if temp, ok := entry["temperature"].(float64); ok {
            pts[i].Y = temp
        }
    }

    // Create the plot.
    p := plot.New()
    p.Title.Text = "Sensor Temperature - Last 24 Hours"
    p.X.Label.Text = "Time"
    p.Y.Label.Text = "Temperature"

    line, err := plotter.NewLine(pts)
    if err != nil {
        logger.Fatal(err)
    }
    p.Add(line)

    // Save to file.
    if err := p.Save(10*vg.Inch, 4*vg.Inch, "temperature_chart.png"); err != nil {
        logger.Fatal(err)
    }
    fmt.Println("Chart saved to temperature_chart.png")
}

go run main.go

Try It

1. Build a Viam Teleop dashboard. Create a workspace, add a time-series widget for a sensor and a camera feed widget, and verify that data appears in real time.

2. Connect Grafana. Run the CLI commands to configure database access, set up the Grafana MongoDB data source, and run the example MQL query. Create a time-series panel and verify the chart updates when you change the time range selector.

3. Run the Python or Go script. Copy one of the programmatic examples, fill in your credentials, and run it. You should see a temperature_chart.png file in your working directory.

Troubleshooting

What’s next

• Query Data – learn the full range of SQL and MQL queries you can use to extract insights from your data.
• Data pipelines – set up aggregated views and derived metrics to power your dashboards more efficiently.
• Filter at the Edge – reduce noise in your visualizations by filtering data before it leaves the machine.