Utilizing the Connect GraphQL API to troubleshoot FCU issues
When a piece of equipment is malfunctioning, getting closer to the source of the data can speed up the troubleshooting and root cause analysis work. When you have an occupied space, like an office or data center, quickly gathering details is of the utmost importance. For Connect users, the GraphQL API is an indispensable tool for triaging issues in the field before you (or a sub-contractor) go on site.
Using the Connect API to gather data directly from the integrated system allows for the removal of one more layer of the system, completely eliminating the visualization layer (Noda or another integrated UI) from the list of possible root causes. Given the complexity of today's built environment, removing every layer you can from the list of possible reasons something is not working, is a troubleshooting best practice.
If this is your first time using the API, please read through these introductory articles before continuing here:
In the following example, we will walk through how to gather real time values from Connect, using queries run in the Altair GraphQL client. From there, we will look for any Insights that might have been generated from the historical database.
The background for this troubleshooting exercise is that we have received a report from the building manager that one Fan Coil Unit is no longer applying the latest command from the BAS or attached thermostat. We want to find out what could be causing an issue that is preventing the FCU from responding to new inputs from occupants.
Troubleshooting FCUs via Connect
1) Query for the building IDs in your portfolio to search the results and find the affected building. This query will return the building IDs and names for all buildings in your Connect portfolio. If you only have one building in your portfolio, only one building will be returned in this query.
query{
buildings{
id
name
}
}Pro Tip: You can save these results for future reference by commenting them out in your query panel of the API client.
2) Filter through your results, choose the right ID for the building with the malfunctioning equipment. Your results will look like the below:
{
"data": {
"buildings": [
{
"id": "Alpha Numeric ID",
"name": "100 - Building Name"
}Pro Tip: You can "CTRL + F" inside the results pane of most API clients, like Altair. You can enter the name of the building to search the results and quickly find the right ID.
3) Copy the building ID for the affected building and prepare your query for equipment. You do this by asking the API to return results that include your equipment name, ID and label.
query{
building(id:"Alpha-Numeric-Equip-ID"){
equipment{
name
id
label
}
}
}For this example, we are looking for equipment with name and/or label FCU and a specific number. The results from this query will return and look like this:
{
"data": {
"building": {
"equipment": [
{
"name": "FCU0204",
"id": "Alpha-Numeric-Equip-ID",
"label": "FCU 2.4/CU2.2/BSB 2.2"
}Now that we have the specific ID for the FCU, we can ask the API to return data specific to that equipment.
4) We want to know the equipment name in Connect so we can match our equipment with the installed FCU in the space. This avoids troubleshooting the wrong piece of equipment, a common mistake when supporting field personnel remotely. Additionally, the query below will return OAP Code (which defines how the equipment is modeled in the backend), what points are available on it and most importantly, the current value and external name.
query{
equipment(id:"Alpha-Numeric-FCU0234-ID"){
name
label
ontology{
oap{
code
}
}
points{
name
curValue
type
id
code
externalName
}
}
}Note: If you have integrated through a platform like Niagara, the external name will be the name applied to the equipment in the JACE and/or Web Supervisor.
5) In that result, the best first step is to verify that equipment is online by looking for the Communication Status point.
{
"name": "Communication Status",
"curValue": "Online",
"type": "SENSOR",
"id": "Site-AlphaNumeric",
"code": "CMST",
"externalName": "DeviceStatus"
}If the unit is not online, that must be resolved before continuing. Always verify the unit has power before getting farther along in remote troubleshooting.
At this point, we have the latest real time values of the equipment. A quick look at set points, overrides and zone temps to find any outliers is a good idea. That takes a trained eye, so now we will ask the system to do the heavy lifting for us. The next best step is to have Connect provide any known issues, based on our analytics engine.
6) This next API query will search the defined time period for any Insights that have been generated automatically based on the historical data we have collected on the equipment. Be sure to include the right time span - typically going back a week from the current date is sufficient.
query{
equipment(id:"Alpha-Numeric-FCU0234-ID"){
name
insights(startDate:"2022-09-20", endDate:"2022-09-28"
){
id
name
description
priority{
priority
category
}
recommendation
}
label
id
points{
name
id
externalName
curValue
}
}
}In our query results we will see Insights for this FCU0234 that the unit has been going back and forth between heating and cooling too quickly. At this point, we have identified behavior that can have a few root causes, and our Insights will recommend you to confirm the FCU is not oversized and the install location of the zone temperature sensor is not improperly installed.
{
"data": {
"equipment": {
"name": "FCU0234",
"insights": [
{
"id": "Alpha-Numeric-Equip-ID",
"name": "AHU Heat and Cool Cycling",
"description": "The FCU0234 is short cycling between heating and cooling for at least 2h. The minimum OFF time between heating and cooling is less than 1 hour.",
"priority": {
"priority": 2,
"category": "Low"
},
"recommendation": "The FCU0234 may be oversized for the space in which it serves or the zone temperature sensor may be installed too close to the supply diffuser."
}If there is an issue with the zone temp sensor or the size of the unit, it is not uncommon for an FCU to have trouble executing commands from an attached thermostat or BAS.
At this point, the final step is to engage with the appropriate controls or mechanical contractor to have someone investigate the mechanical design, controller logic, and physical equipment for any installation errors.
To confirm the issue has resolved once corrective action has been taken, you can query the Insights again. Once the behavior that generates an Insight is gone, the analytics engine will recognized this in the data and stop showing it as active. It's standard practice to give it at least a few days to collect new data and ensure the issue does not resurface.
There is SO much more we could cover here, but for now we will stop. There are many ways to leverage the real time data stream coming over our Connect API, this is just one!
If you have specific queries you would like us to cover in this section, submit the request and we will work on a write-up.
Final Pro Tip: Enable the "Export to CSV" feature on your GraphQL client and you can export the results from any query into a tabular format that can easily be reviewed and shared. You can send the details of the equipment over to the appropriate contractor so they are armed with the latest information, giving them a head start on troubleshooting before the site visit even begins.
