Niagara Best Practices

Introduction

Niagara is a very open-ended framework; This flexibility is incredibly powerful, but it can also result in a lack of consistency in many cases. Often, integrators don’t have explicit standards in place, and when they do, they can be vague or ill-defined. It’s common for the focus to be on completing a job as quickly as possible, without regard for future scalability or ease of troubleshooting/updating. However, there are some basic practices that, when applied consistently, will achieve both speed and predictability for future work.

This guide is somewhat unlike what I’ve previously written. While before, I’ve written primarily on specific Niagara features and how to utilize them, this won’t be quite as objective. Every company and individual will have unique standards and best practices, and while the practices I’m going to cover below have proven very useful in my work, they may not align with your company’s goals or procedures. Just remember, as long as your work is being done efficiently, is fully functional, and you can think about adding on to your systems in the future without a pit forming in the bottom of your stomach, then keep on doing things the way you’re doing them! I intend to illustrate some practices that many often don’t think about, but it’s most important to do what works in your specific position!

Utilize a Point Naming Standard

The absolute most important practice I’ll be covering is this one. Too often, integrators will simply pull in points from a piece of equipment and keep point names exactly the way they are. This rarely works well; No two products tend to use the same naming scheme! For Zone Temp, as an example, Siemens VAVs use CTL_TEMP, JCI FX uses ZN-T, Daikin MTIII AHUs use SpaceTemp… When we have completely dissimilar naming conventions being used, this prevents many time-saving tricks we can use. Inconsistent naming will prevent us from using auto-tags, using the batch editor, re-using graphics, using BQL to collect data and many other critical tools for working at large scales!

This particular practice is often skipped due to time constraints; Unfortunately, on small jobs, this step can result in using more hours overall. However, on small jobs, this standardization of point names usually only takes half an hour or so. If we never re-visit that job, whether that’s to expand to additional devices or bring to a supervisory server, then yes, we used slightly more time toward the job. However, if we ever go back to it, it’s hard to understate how helpful it is to already know a system like this. No referencing point lists while making graphics, no manual tagging if you’re applying analytics, and no comparing to manuals to determine whether you should be looking at ActiveTemp, SpaceTemp, or LocalSpaceTemp!

The specifics of your naming standard aren’t particularly important. If there is already an established standard at your employer, then 100% follow that standard. However, if you’re determining one yourself, there are a few tips that can be helpful:

Avoid special characters! In Niagara, these will generally function fine most of the time. However, to interact with these names, you’ll sometimes need to use escape characters (IE, $2d is -, $20 is a space), and readability will be harmed wherever names are shown using special characters. Use an underscore instead of spaces or dashes; This is natively understood, and not automatically escaped.
Avoid leading numbers! This is a particularly odd quirk, but Niagara puts a leading special character in automatically before the slot name, if you start it with a number. I believe this has to do with how Java likes to specify special characters. However, this can cause some hard-to-identify issues in some cases where you’re trying to enter ORDs.
Keep things reasonably short! This is becoming less important in newer versions, but many text fields have character limits. For example, in history extensions, the history name cannot exceed 40 characters (Increased to 200 characters as of 4.12). RooftopUnit49A_ComputerLab_HardwareSpaceTempSensor is too long to be a resulting history name pre-4.12!

Use Consistent Folder Depth

Often, integrators will be inconsistent in their folder structure in JACEs. Config→Drivers→BacnetNetwork→AHU1→points→Sensors→ZN_T is fine on its own as a filepath. However, when the next AHU over has a Zone Temp at Config→Drivers→BacnetNetwork→AHU2→points→ZN_T, you start having to special-case a lot of your procedures. Suddenly, your history extensions need separately specific BFormat strings per unit to get proper names, and your alarm source names need the same treatment. Your BQL statements also become much more complex; Normally, you could snag all AHU zone temps with BQL:select * where name = ‘ZN_T‘ and parent.parent.name like ‘AHU*‘ With inconsistent folders, you suddenly need to split things up to check multiple levels for the AHU device name.

Some devices can be better off with slightly different structures; For example, I always put my VAVs into subfolders under the network based on the AHU that serves them, while the AHUs and other standalone pieces of equipment will generally be placed directly under the network. However, even in this case, it’s done consistently and predictably.

Provide Accurate Metadata

Let’s say you have an office building, served by AHUs 1, 2, and 3. Are you able to tell what areas each unit controls without taking a walk on the roof, or turning fans on and off? Metadata is, essentially, “Data about your data”. There are a lot of ways this can be accomplished; Niagara’s documentation, for example, uses string tags for this purpose. These string tags certainly work, and if they’re your preference, go for it!

My preference is stringWritable points alongside the rest of the points in a device. I rarely provide graphics and access directly within the JACE, and usually build these things on centralized supervisor servers. Tags don’t (easily) transfer upward this way from the device level, so using string points fits my needs better, and may work for you as well! This allows for a few benefits outside of supervisor import, too. This allows the customer to change metadata like AreaServed as their needs change, easier usage of metadata on graphics, and usability in other features such as BQL. In fact, you can even set up custom auto-tag rules utilizing BFormat tags to auto-populate with the data from these tags, so you can get the best of both worlds this way.

While I specify naming areas served, there is a lot of very useful metadata to record, based on your application. If you’re doing diagnostics on DX cooling systems, you may want to record the refrigerant used. If you’re trying to do some performance analysis frequently on a system, it would be useful to have rated airflow and sizing information associated with your equipment. If this metadata is stored within proxy points, you can even access it through Niagara Analytics!

Avoid Display Names

This one is listed nearly last, particularly because I think many may disagree, and it’s not all that critical. As I said above in regards to point naming, if you have a particular case where display names are your best option, then use them! However, there are definite downsides to using display names. Having a mismatch between what’s shown in your ORD for a slot and what you see in workbench is the absolute biggest downside. This can get incredibly confusing, and I’ve spent a lot of time needlessly troubleshooting, due simply to misuse of display names.

I most often see this used in device folders and names; It seems unusually common to give the “device” name as the proper name (AHU1, VAV43, etc), and the “area” as the display name (Northwest AHU, Coleman’s Office, etc). In these cases, you’re generally far better off just using your “device” name, and adding the user-friendly names as metadata, as explained above. This not only removes any confusion regarding file paths and slot names but allows more functionality and ways to interact with the friendly name.

Don't Just "Band-Aid" Problems

One of the times I got caught up by display name usage was actually due to a time-saving measure. Two units had been mixed up in the initial integration in the JACE. However, this didn’t get fixed properly; We should have disabled trends, renamed the devices, cleared out old history data on those units to prevent conflict, re-enabled trends, and rediscovered the points into new folders in the supervisor. Instead, all that was done was a switch of folder display names in the supervisor, to switch the names being shown on the graphic. All history names, alarms, and point IDs still had the incorrect unit name and were just hidden from the customer (Except for the names populated in trends).

It feels obvious and cliche to point this out, but it’s important: Things should be fixed correctly and completely! It should look as if the integration had just been completed when you have to go back and change something because the quick and easy fixes will almost always break whatever standards you have in place, and cause issues if you try to work with that system again in the future. What started as something to save time, ultimately just costs you more of it in the long run if you plan on continuing to support that customer’s system.