Tridium - EC-NetAX-3.x Best Practices

EC-NetAX-3.x Best Practices FAQ

Is it important to connect to a EC-BOSAX using the exact same version of Workbench and all the same version jar files?

Distech Controls always recommends using the same version of Workbench that was used to commission the EC-BOSAX controller. It is also important to use the same versioned jar files on the engineering PC as are installed on the EC-BOSAX.

It is possible to use a computer with a newer version of Workbench installed to make a platform connection to a EC-BOSAX that is running an older version. When using a computer with an older version of Workbench than which is running in the EC-BOSAX, the platform connection will fail.

When installing EC-NETAX software on a PC and the checkbox for "this instance of Workbench will be used as an installation tool" is selected, the installation creates a folder called "sw" under the installation directory. All of the jar files which are installed under the "modules" directory are also installed under the "sw" directory in subfolders which indicate the applicable version.

  • If a newer version of an existing jar file is copied into the "modules" directory, it is automatically copied to the "sw" directory under the appropriate version subfolder.
  • When connecting with Workbench to a EC-BOSAX which has a previous versioned jar file installed, copy the correct versioned jar file from the "sw" directory to the "modules" directory and then restart Workbench.
  • When using the Software Manager view to install jar files on remote EC-BOSAX's, the list of available jar files is determined by parsing the "sw" directory. If multiple versions of the same jar file exist in the "sw" directory, the Software Manager only lists the most current version as the available version. It may be necessary to temporarily move a subfolder from the "sw" directory if trying to install an older versioned jar file to a remote EC-BOSAX platform.

Are there any views accessible through browsers that are similar to R2 such as prism?

http://<ipAddress>:3011/platformInfo - this view provides much of the same information that is available through Workbench when looking at the Platform Administration view.

http://<ipAddress>:3011/qnx - this view is only available for EC-BOSAXs which use the QNX operating system. This view provides much of the same information that is available through Workbench when looking at the spy pages.

How do I use the serial shell mode on a EC-BOSAX controller?

The serial shell mode allows connecting a PC using a null modem cable to the RS-232 port on a EC-BOS controller. This can be extremely useful if the IP address is unknown or a Workbench connection cannot be established with the EC-BOSAX.

Setting up a connection to the QNX shell mode is detailed in the User's Guide under the "recovery tips" section.

  • Connect a null modem from the com port on the PC to the RS-232 port on the EC-BOS Controller.
  • Start hyper terminal and configure the connection speed based on EC-BOSAX model (EC-BOSAX -2/6=115200, EC-BOSAX -4/5=57600)
  • Position the mode jumper on the EC-BOSAX to "serial shell mode", and power cycle the EC-BOSAX.

If telnet is enabled on the EC-BOSAX, then it is possible to connect to the EC-BOS via a telnet session which provides the same QNX shell access via a TCP/IP connection instead of having to use the null modem cable to the serial port.

I've lost the IP address of the EC-BOSAX, how can I determine the address?

There are detailed instructions in the User's Guide under the "recovery tips" section.

Method 1
Connect to the EC-BOSAX using the serial shell mode, the IP address of the EC-BOS will be shown during the boot sequence. The IP address of the EC-BOS may also be changed while in the QNX shell mode.
Method 2
In Workbench using the nav side bar, expand the file system for the localhost. Under sysHome/users/<username> there is a file called ipchanges.bog. The bog file contains folders named with date/timestamps which correspond to any TCP/IP settings which were changed when using this instance of Workbench. Each folder contains two components that indicate what the TCP/IP settings were prior to and after the change.
Method 3
Connect a laptop running an ethernet packet analyzer (e.g. wireshark.org) and monitor packets as the EC-BOS boots up. This is best done if the EC-BOSAX and laptop are the only devices on the LAN.
Method 4
If there is a station running on the platform, using the Workbench menu select File -> Open -> Find Stations. This creates a table of all running stations on the local network segment, the scan does not pass through ethernet routers.

What can the second Ethernet port on the EC-BOS-2AX and EC-BOS-6AX be used for?

Currently the only drivers that can be configured to use the second Ethernet port are Bacnet, ModbusTCP and EibIp.

The EC-BOSAX does not act as an Ethernet router or switch, meaning it does not allow TCP/IP traffic to pass from one port to the other.

The second Ethernet port can be used to isolate a BACnet Ethernet or IP network from the primary LAN. All BACnet devices would be connected on the network segment that was connected to the secondary Ethernet port on the EC-BOSAX. BACnet points that are proxied in the station could then be viewed or commanded through graphics that are served up by the webService via the primary Ethernet port.

The Niagara Network and the webService will be available on both network interfaces. With BACnet, you select which network interface to use on the link settings of the IP-port and/or Ethernet-port object under the BACnet network. With Modbus TCP the IP layer decides which network interface to use based on the IP address assigned to the Modbus TCP Device Object.

The second port must be on a different subnet. The second subnet cannot also have a default gateway - so you will be limited to one subnet on the second network interface.

How can I tell if I am overloading a EC-BOS?

When using Workbench, right-click on the connected station in the nav sidebar and select View -> Resource Manager.

  • The CPU usage should be less than 80% on a continuous basis.
  • The heap.used should be less than 75% of the heap.max value. Execute garbage collection before evaluating the heap.max value by right-clicking on the connected station in the nav sidebar and selecting Spy -> util -> gc.
  • For a Soft EC-BOS  ensure that the resource.total is less than the licensed resource limit. Soft EC-BOS's are licensed for either a 10,000 KRU or 30,000 KRU limit. If actual station resources exceed 110% of the licensed limit for a Soft EC-BOS, the station will fail to start.

If running AX 3.1 or later, when using Workbench right-click on the connected station in the nav sidebar and select 'Spy'. On the Remote Spy page select 'platform diagnostics' and then 'fd usage'. This displays a list of processes and the number of open file descriptors for each.

QNX-based EC-BOS controllers are limited to 1000 open file descriptors. File descriptors include but are not limited to directories, files, histories, and socket connections. If the number of open file descriptors exceeds the limit, the station will behave erratically such as misreporting available file space, missing history collections, etc. A maximum of 800 histories per station is recommended to avoid exhausting the pool of available file descriptors. Per issue 8943, in AX 3.2 and newer the maximum file descriptor count for EC-BOS-4, 5, and 6 has been increased from 1000 to 2000. This allows customers to use up to 1600 histories in a EC-BOS. Note that the limit on a EC-BOS-2 remains 800 histories.

How many field controllers can I connect to a given EC-BOS and how much control logic, scheduling and trending can I add to the station?

Distech Controls does not have any established metrics for the various hardware platforms at this time. There are almost infinite possible combinations based on how the station is configured and what vendor hardware is used on the field buses. The best practice is to examine the resource manager views of your own existing projects and establish your own metrics based on your specific engineering practices and field hardware. Evaluate CPU usage and heap.used values to determine whether additional field devices and programming can be added to the station.

Table - Maximum Heap Size By Model Number
Model heap.max
EC-BOS-2 64 MB RAM version 14 MB
EC-BOS-2 128 MB RAM version without NPM-128 option 16 MB
EC-BOS-2 128 MB RAM version with NPM-128 option 48 MB
EC-BOS-4/5 128 MB RAM version 48 MB
EC-BOS-4/5 256 MB RAM version 96 MB
EC-BOS-6 without NPM-256 option 48 MB
EC-BOS-6 with NPM-256 option 96 MB
Soft EC-BOS configurable using nre.properties file, limit based on available physical RAM

For the Soft EC-BOS, it is licensed based on the allowed station resources. There are two license levels offered, 10,000 KRU and 30,000 KRU. Using Workbench there is a resource estimator available under the menu options Tools -> Resource Estimator. This can be used to calculate the expected resource.total for the Soft EC-BOS station.

How many histories can I have in a station and how many records are allowed per history? Do histories affect the heap.used value?

Regardless of platform type, histories are stored under the station’s file system (file:^history/).

Stations running on a PC-based system (AxSupervisor or Soft EC-BOS) store the histories in subdirectories using segmented files; this provides improved search capabilities over a flat file system.

Stations running on a QNX-based EC-BOS system store all of the stations histories in a single compressed file (history.zip). A running station opens the history.zip file in the EC-BOS's ram disk space, the histories are compressed and saved to flash whenever the station is saved. Opening the history.zip file to the ram disk eliminates the need to write to the flash drive each time a record is added to the history file.

  • When the station needs to write a record to a history, it opens the specific history into the running station (either from the file system if PC based, or from the ram disk if QNX-based). The open history does contribute to the heap.used of the station. The history service has one property 'max open time' (default 5 minutes) which causes the station to close the history from the running station heap if no records have been written to the history for a time period exceeding the 'max open time'.
  • Each history extension which is added to the station does add slightly to the station resources because the extension is represented in the bog file.
  • When the history is first enabled, the station creates the history file. The initial file includes a 1600 byte header (defines the configuration parameters) and a single page file of 4096 byte size. When triggered by either the collection interval or COV/COS, a record is added to the page file. When the page file becomes full, additional page files are created based on the capacity configuration of the history.

Table - History Record Size By Type
Point Type bytes/record
boolean 13
enum and single precision numeric 16
double precision numeric 20
string variable length, but a single record cannot exceed one page (4096 bytes)

Since histories count as file descriptors, there is a physical limitation on the number of histories allowed in a QNX-based EC-BOS station. It is recommended not to exceed 800 histories, given the file descriptor limit of 1000.

The platform services view of the QNX-based EC-BOS station includes a property to modify the size of the ram disk within defined limitations. Note that the alarm database is also maintained in the same ram disk space. Exercise caution when modifying the default ram disk size; note that allocating additional memory to the ram disk will limit the memory available for other functions by the QNX OS. Reducing the ram disk size too much could result in history or alarm records not being stored properly and erratic station behavior.

Understanding user permissions and NAV file relationships.

The category service is used to assign logical groupings to station resources, such as HVAC or lighting zones, user management, histories, etc.

Users should be assigned permissions to access the categories based on what type of user they are on what functions that they need access to.

  • Permissions are broken down into two groups, operator and admin.
  • Each group has three permissions which can be assigned. R = read, W = write, I = invoke. Operator permissions are indicated by lower case letters and admin permissions are indicated by upper case letters.
  • Individuals with only operator permissions can still be given authority to command a point which normally requires admin permissions by modifying the config flags of the action on the points slot sheet to include the 'operator' flag.
  • Checking the 'super user' option is a convenience for checking all permissions in all categories, but also provides access to the local file system through Workbench. Users with 'super user' status will see all of the available drives instead of just 'sysHome' when navigating My File System in the nav sidebar.

A user who has permission to manage users will only see other users listed in the user manager view for categories which they have permissions.

The nav file is used to provide a customizable link structure for graphics viewing without having to utilize framesets and custom navigation trees. Each user can be assigned one nav file to their user account. The nav file is not meant to be a security mechanism, although it can be used to limit the available navigation options when using basic profiles. It is important to understand that it does not prevent an operator from manually typing the correct ord in the URL field of the browser to access a resource which they are not intended to have access to. Do not use nav files to restrict a user's access to station resources, properly configure the categories and user permissions to do so.

How do I make global links and one to many links?

How do I make batch changes to all of the high and low alarm limits of points in the station monitoring zone temperature?

  • Using Workbench in the nav sidebar select the station and expand Config -> Services -> ProgramService. If the ProgramService is not present it may be copied from the program palette. Select the 'Batch Editor' view.
  • Click the 'Find Objects' button, which will launch the Bql Query Builder. Perform a Bql query to find the desired station components, in this case a custom type of alarm:OutOfRangeAlgorithm with a condition where parent.parent.name is like ZoneTemp*.
  • Click the 'Edit Slot' button, which launches a popup window. Select the desired property from the drop down list, enter the desired value and click the 'OK' button.
  • A popup window displays a confirmation of what actions have been performed.

Note it is also possible to add, remove or rename slots for multiple components using the Batch Editor.

How do I relativize a Px page when I have more than one field bus device? For example, I have three Lon controllers that need to display data on the same Px page (AHU controller, SFan VFD, RFan VFD)

  • Under the LonNetwork create a folder called AHUx.
  • Organize the required controllers under the AHUx folder.
  • Assign the Px view to the AHU folder, the graphic can have relativized links to the proxy points of the multiple Lon controllers.

How do I create a relative hyperlink on my Px page to display the History Chart view for a particular point?

  • In the hyperlink field of the widget, use the Component Browser to select the history extension of the point. At the far right of the ord field, there is a folder icon. To the right of the folder icon, select from the drop down list to pick the 'History Chart' view.
  • The resulting relativized hyperlink will be similar to this;
slot:Points/ZoneTemp/NumericInterval|view:history:HistoryChart

If I have two Px views assigned to the same folder, how do I create a relative hyperlink between the two Px views?

  • In the hyperlink field of the widget use this format:
slot:view|<nameOfView>
Note that certain characters such as spaces and dashes are represented by their ASCII equivalent (i.e. a space character is $20, a dash character is $2d).

How do I use default colors and fonts for my Px bound labels and text labels?

  • Modify a bound label to setup the desired default properties, and delete the ord field so that the label is not actually bound to a component.
  • Modify a text label to setup the desired default properties.
  • Copy both Px widgets to sysHome/Workbench/newWidgets.bog file and save the file.
  • The default widgets will now be available when performing a right mouse click in the Px Editor.

How do I make a mass change to the bound ords in a Px page?

  • In the Px editor, there are three available side bars: Bound Ords, Widget Tree, and Properties. If the Bound Ords side bar is not available, click on the Side Bars icon in the tool bar (next to the icon to toggle edit mode) and select the Bound Ords option.
  • In the top right corner of the Bound Ords side bar, the right-most icon is for replacing text in the ords (mouse over the icon to display a popup reading 'Replace In Ords'). Select the icon.
  • In the popup window enter the desired text to replace in the 'Search' field, and the new desired text in the 'Replace With' field.
  • The popup window indicates how the ords will be modified in the before and after columns.
  • Click the 'OK' button to apply changes.

How do I create a new Px page with customized settings?

  • Create a new Px file, which will have the default canvas pane.
  • Modify the Px file to have the desired panes, scroll bars, size, colors and images.
  • After saving the file, copy the Px file to sysHome/Workbench/newFiles.
  • When you right-click on the file system to add a new Px file, the customized Px file will be available from the list.

How do I use BFormat Text, the help talks about 'Foo' and I don't understand?

I forgot to enable the history extension on my points, is there any easy way to do this or do I have to go to the property sheet for each extension?

  • The default view of the HistoryService is the History Extension Manger, which shows a list of all the configured history extensions in the station.
  • Use the Ctrl or Shift key in conjunction with left mouse clicks to select multiple history extensions in the list.
  • Right-click on one of the selected history extensions and select 'Enable Collection' from the popup menu. This sets all of the selected history extensions to enabled.

How do I see the alarm database records, after I acknowledge an alarm in the console it disappears from the console view?

One of the views for the AlarmService is the Alarm Db Maintenance view, which shows all of the records in the alarm database. At the top of the view there is a date filter which may be applied to narrow down the search of the records.

This view allows the user to also delete records from the alarm database if desired. Because a user who has access to this view will have the ability to delete records, the view is restricted to users with admin level permissions.

Beginning with the 3.2.x build there is also an Alarm Db view which provides the same information as the Alarm Db Maintenance view, less the ability to delete records.

How do I globally disable alarms for a whole station or a particular piece of equipment?

  • One of the views of the AlarmService is the Alarm Ext Manager, which lists all of the alarm extension which are in the station.
  • Use the Ctrl or Shift key in conjunction with left mouse clicks to select multiple alarm extension in the list.
  • Right-click on one of the selected alarm extensions and select 'toOffnormal Enabled' or 'toFault Enabled' as required. If adding the check in the popup box, it will enable the algorithm for all of the selected extensions. If clearing the check in the popup box, it will disable the algorithm for all of the selected extensions.
  • Batch changes to the alarm class and alarm instructions may also be made from the Alarm Ext Manager view using the same method.

In the case of disabling the alarms for a particular piece of equipment, it would be more functional to add a BooleanWritable point which was linked to the alarmInhibit slot of the alarm extensions. An operator could then issue a command to the Boolean point, which when true would inhibit the associated alarm extensions from functioning.

Add Feedback