Fox Protocol Support¶

The Fox protocol is a proprietary protocol created by Tridium, Inc. for use in its Niagara Framework. It is the native means of communication between Niagara stations, workbench instances, and supervisors. Technically speaking, Fox is a stream-based protocol which runs either directly over TCP, or inside an encrypted stream using TLS. The protocol contains its own framing mechanism to multiplex different simultaneous request/response pairs into a single stream and to break large responses into smaller chunks to avoid head-of-line blocking.

Normal implements a subset of the Fox protocol to allow users to interoperate seamlessly with Niagara stations without the need for configuring BACnet export tables, installing modules, enabling other protocols such as MQTT or oBIX. This provides the most straightforward integration possible since the only requirement is a valid login for the Niagara station. Normal supports the following functionality over Fox:

• Loading the object database into Normal;
• Trending of Niagara points, either by polling or via Niagara subscription; and
• Writing to the Writeable point types (NumericWritable, BooleanWritable, and EnumWritable)

Fox authenticates clients using its n4digest protocol; which is an implementation of SCRAM running within the Fox protocol. Normal implements the same mechanism as other Niagara stations, so as long as the username and password are secured on the Normal instance, integrating in this way should not result in a decrease in security.

Configuring a Niagara Integration¶

In order to connect to a Niagara station, you will need the same connection information which would be required to connect via Workbench: IP address or hostname; username and password; port number; and if TLS is required. Using this information, construct a Fox URL using the following format:

fox://username:password@ipaddress:port

or

foxs://username:password@ipaddress:port

Fox (without TLS) is typically run on port 1911, while Foxs (with TLS) is usually on port 4911. Once you have constructed this URL, add it to the list of Fox connections in the 🦊 section of the Normal settings.

The Connection Procedure¶

When a new connection is edited, Normal will create a new Fox connection to the station and log any errors encountered. Niagara stores internal objects in a tree structure, where each tree node is identified by an Object Resource Descriptor (ord). Using the ord, clients can load children of nodes (a special getRoot facility returns the ord of the root of the station).

Each node also has a type, which generally corresponds to the Java class implementing that node within Niagara. To avoid problems with discovery, Normal only explores nodes which have been explicitly white-listed. The list of node types which will be explored is also available on the settings page.

In order to initiate a download of the remote stations' database, click the "Run Discovery". This will populate the tree of available Niagara objects, which matchs what is available in Workbench.

Because some node types are not discovered by default, you may need to examine the tree and manually expand nodes which were not explored. You can use this UI to select which objects will be imported as Normal points; or use the "select all" checkbox to import all valid points.

Normal imports each Niagara point as a Normal point, creating a new object in the object database. It also imports metadata such as the Niagara facets and the path to that node or point within the station; this corresponds to the location of the point within the tree available to users using the Niagara Web UI or Workbench.

Using Fox Points¶

Once Fox points are imported, they can be interested with like most other points. The fox driver respects the trending configuration set in Object Explorer, and will either create a Niagara subscription (if the "CoV" flag is set) or periodically load the points' latest values. The points can also be read and written using the Point details page.