Transcript
Introduction
Welcome to today’s Ask a Pro session. I’m Scott Windsor, the lead software engineer over here at PMI. Today we’re gonna be talking about PQ Canvass API access.
In this presentation, we’re gonna cover what PQ Canvass API access provides and why that matters, the architecture and security behind the API, how to use the API, including the available commands and a real-world example, and how to get API access for your organization.
What PQ Canvass API Access Provides
PQ Canvass API access provides electric utilities a way to monitor their grid reliability, regulatory requirements, et cetera, as their monitoring deployments grow, all this in the context of PQ Canvass.
PQ Canvass, PMI’s cloud-based power quality platform, gives utilities centralized access to data from their deployed monitoring devices. The PQ Canvass web interface is well-suited for manual review, investigation, even our Merlin AI analysis tool, but it was not designed for machine-to-machine integration.
The PQ Canvass API access extends the platform with a secure programmatic interface to record data that has been streamed from PMI recorders to PQ Canvass. It enables utilities to retrieve data on demand and integrate it directly into their own systems.
Through the API, users can query their device inventory, retrieve waveform captures, pull continuous strip chart data, and access our one-second RMS average trending data. They can then summarize energy consumption, kilowatt totals by channel for any timespan that’s been recorded, along with data completeness percentage.
All the data returned in this API is returned in base engineering units: volts, amps, watts, et cetera. So there’s no conversion unless you want to consolidate those into kilovolts, et cetera.
Architecture and Security
PQ Canvass API access is designed to be both secure and straightforward to integrate. The protocol was intentionally kept simple so the client implementations can be built in virtually any programming language with standard networking libraries.
The API operates over a direct TCP connection secured with TLS 1.2 or higher. All communication is encrypted end-to-end. The client connects, performs a TLS handshake, and then you can begin exchanging messages immediately.
All requests and responses use the JSON format, which is supported by robust, well-maintained libraries in virtually every programming language and operating system. This makes client development straightforward regardless of platform.
Authentication and Sessions
Clients authenticate using the exact same credentials that you have for your PQ Canvass web interface, just like you were signing into the website. Sessions are short-lived and scoped to a single connection with no persistent API keys to provision, rotate, or secure at rest.
Multi-Account Support
The API supports users with access to multiple PQ Canvass accounts. After authentication, users can select which account they wanna query data from and can easily switch between accounts within the same session without reauthenticating.
Most customers, I believe, have one account, so this won’t apply to most people, but some do have multiple accounts. That just means you’ll connect, authenticate, and then you can say, “I want to select the devices on this account,” and without having to reauthenticate, you can simply say, “I’d like to look at the devices on this other account,” as long as they’re contained under that same user.
Using the API
A typical session follows a simple workflow:
- Establish a connection and authenticate with your PQ Canvass credentials.
- Select which account.
- Query the list of recorders to identify available monitors.
- Start requesting data—waveform captures, strip charts, the one-second RMS traces, energy summaries—and then you pick the timeframe you’re looking for.
Available Commands
The API provides a focused set of commands each designed around a common data retrieval need.
List Devices returns the full inventory of monitored recorders in the selected account.
List Captures returns metadata for all waveform captures recorded by a device in a given time window. That includes trigger type and cycle information.
Waveform Capture request gets you the actual voltage and current sample data for a specific capture event. You would follow the List Captures with a Waveform Capture request if you wanna see the actual waveform captures.
Start and End request returns the available data range for a recorder, so clients can know what time periods are available for querying.
Strip Chart Requests retrieve continuous time series data for a selected measuring channel with support for minimum, maximum, and average values. You would make a request for voltage, channel one, average, and so on and so forth.
Canvass Trace is our API’s name for the one-second RMS data. That request retrieves the one-second RMS averages for voltage, current, and real power traces, each a separate request, for supportive devices such as Boomerangs, Seekers, Guardians, Tensors, and Bolts.
Canvass Kilowatt Hours returns the energy consumption summaries for the one-second RMS averages by channel in a given time span.
All of these responses are returned in JSON, making them easy to parse and integrate regardless of whatever technology stack your client’s built in—Python, C++, Qt, whatever.
Example Use Case
Consider a utility wants to automatically pull daily voltage THD data from a feeder monitor. You would authenticate, select the appropriate account, query the device list to find the target monitor, and then request strip chart data for the measure over the previous 24 hours. The response will come back with the time series values ready to be stored or visualized with no further transformation.
This pattern applies to any data type the API supports. Swap the command and parameters and the workflow’s exactly the same.
Since device lists probably change infrequently for most customers, you could have your clients periodically pull and cache those device inventories locally. That would allow you to map PQ Canvas device IDs to your own internal asset records and skip the device list query during more routine data retrieval sessions. Obviously, not a requirement, just something we’ve noticed in some usage patterns.
Here is an example graph. I did a canvas trace request for voltage and current and a kilowatt request as well on one of our recorders for a particular time span. It’s the same kind of information you would see in the PQ Canvas web interface. It’s the same exact data. You’ve just pulled it programmatically now into your environment.
How to Get API Access
PQ Canvass API access is available to customers with an active PQ Canvass account. Access requires a one-time fee in addition to the standard annual PQ Canvass subscription.
To get started, contact your PMI technical support and they can walk you through the onboarding process and get everything set up for you. Once you’re established, your team will receive detailed technical documentation and even some client library examples to get you up and running quickly.
Summary
PQ Canvass gives utilities a powerful platform for monitoring, analysis, and data review at any scale. For teams that need to go further, such as feeding data back into your in-house systems, the PQ Canvass API provides a straightforward path to do so.
It bridges the gap between the data utilities collect with power monitor devices and the systems they use to act on it. It provides a secure, lightweight interface that fits naturally into existing workflows. The protocol is simple by design, the data comes back ready to use, and integration can be accomplished with standard tooling in any language.
For utilities looking to get even more value from their power quality monitoring investment, PQ Canvass API access is a straightforward next step. Don’t forget to check out all the links, especially the Merlin™ demo. If you haven’t seen that yet, that’s really cool. Thanks for everyone who tuned in. And as always, have a great rest of your day.
