What LonWorks XIF Files Are
A XIF file (external interface file) is the formal interface definition for a LonWorks device. It lists every network variable the device exposes, the Standard Network Variable Type and direction of each one, any configuration properties, message tags, buffer counts, and the device’s Program ID. It is the LonWorks equivalent of a vendor Modbus register map, but it is published by the device itself rather than written by hand.
A XIF can be a plain text .xif, a binary .xfb, or an extract pulled live by a network management tool from the device’s Neuron chip. Gateways such as the QuickServer consume a XIF to know which variables to read, which to write, how each value is encoded, and how to address the device on the network.
Why XIF Files Are A Hard Prerequisite
Most LonWorks gateway delays trace back to a missing or wrong XIF. Without one, the integrator cannot reliably name a network variable, cannot prove which variables are inputs versus outputs, and cannot confirm the Standard Network Variable Type that drives engineering-unit interpretation. Communication can be perfectly healthy while every mapped point is wrong because the assumptions about the interface were never verified.
[!WARNING] A device name alone is not enough to start configuration. Collect the XIF that matches the installed firmware revision before promising a mapping schedule.
File Structure
LonMark defines the XIF text format in the Device Interface File Reference Guide. The structure is consistent across format versions and breaks into four logical sections.
| Section | Purpose |
|---|---|
| Header | Identifies the file, the device model, the Program ID, and the format version |
| Network variable definitions | One entry per network variable: name, index, direction, Standard Network Variable Type, options |
| File definitions | Optional, used by devices that expose LonWorks file transfer objects |
| Network variable value definitions | Optional, used for default values and configuration property data |
The header is the first thing to read on an unfamiliar XIF. It carries the Program ID, the model number, the format version, and the buffer counts that constrain how the device handles inbound and outbound traffic.
Header Fields
The XIF header carries roughly ten fields that matter in field work.
| Field | What It Tells You |
|---|---|
| File name and copyright line | Identifies the source tool and vendor |
| Timestamp | Tool-generated; useful for spotting stale XIFs in vendor downloads |
| Program ID (12 hex bytes) | Unique identifier for the device interface; drives binding compatibility |
| Format version | Determines which optional fields and Standard Network Variable Type extensions are valid |
| Network input buffer count | Limits concurrent inbound transactions the device can absorb |
| Network output buffer count | Limits outbound transactions; matters for high-rate polling designs |
| Application input buffer count | Internal application-layer buffer sizing |
| Application output buffer count | Internal application-layer buffer sizing |
| Receive transaction count | Affects acknowledged-service performance |
| Number of network variables | Quick sanity check against the actual variable list that follows |
Format versions seen in the field range from 1.0 through 4.400. Newer versions add additional descriptors and Standard Network Variable Type support, but the core header layout is backward compatible.
Network Variable Definitions
The largest section of a typical XIF is the network variable list. Each entry describes one network variable.
| Attribute | Description |
|---|---|
| Index | Numeric identifier used to read or write the variable on the network |
| Name | Mnemonic such as nvoSpaceTemp or nviSetpoint (vendor-chosen) |
| Direction | nvi for input (write to device), nvo for output (read from device) |
| Standard Network Variable Type | Governs encoding, range, resolution, and unit |
| Service type | Acknowledged, unacknowledged, repeated, or request-response default |
| Authentication flag | Whether the variable requires authenticated updates |
| Polled flag | Whether the variable supports explicit polling |
A typical HVAC controller XIF extract looks like this in tabular form:
| NV Index | Name | Direction | Standard Network Variable Type | Description |
|---|---|---|---|---|
| 0 | nvoSpaceTemp | NVO (read) | SNVT_temp_p | Space temperature |
| 1 | nvoDischargeTemp | NVO (read) | SNVT_temp_p | Discharge air temperature |
| 2 | nviSetpoint | NVI (write) | SNVT_temp_p | Temperature setpoint |
| 3 | nvoOccupancy | NVO (read) | SNVT_occupancy | Occupancy status |
| 4 | nviHvacMode | NVI (write) | SNVT_hvac_mode | Operating mode command |
| 5 | nvoDamperPos | NVO (read) | SNVT_lev_percent | Damper position |
The mnemonic prefix (nvi or nvo) is a convention, not a contract. The direction field in the XIF entry is authoritative.
Configuration Properties
LonWorks devices can also expose configuration properties that sit outside the standard network-variable model. Two families exist.
| Family | Origin | Examples |
|---|---|---|
| SCPT | Standard Configuration Property Type, defined by LonMark | SCPTminRnge, SCPTmaxRnge, SCPTlocation |
| UCPT | User Configuration Property Type, defined by the manufacturer | Vendor-specific calibration, schedule, or behavior parameters |
[!NOTE] Some devices expose runtime data through configuration properties rather than standard network variables. If a value listed in the device sheet does not appear as a network variable in the XIF, search the SCPT and UCPT sections before assuming the data is missing.
Format Versions And Compatibility
XIF format versions matter when a tool refuses to load a file. Most modern tools accept versions back to 3.x; older FieldServer drivers and legacy LonMaker databases sometimes expect 2.x layouts. The format version is declared in the header and should be the first thing checked when an unfamiliar XIF will not import.
| Version Range | Notes |
|---|---|
| 1.0 – 2.x | Early Echelon tooling; rarely seen on new projects |
| 3.x | Common on installed-base devices through the 2000s |
| 4.0 – 4.400 | Adds extended Standard Network Variable Type support and richer property descriptors |
How To Obtain A XIF
Preferred sources, in order of reliability:
| Method | Tool Required | Notes |
|---|---|---|
| Export from the commissioning database | LonMaker, IzoT CT, or OEM tool | Most reliable; reflects the device as actually deployed |
| Extract live from the device | NodeUtil or equivalent | Pulls the default XIF directly from the Neuron chip |
| Request from the manufacturer | None | Ask for the file matching the installed firmware revision |
| Extract through a gateway | QuickServer NodeUtil mode | Discovers and extracts XIFs from connected devices |
[!TIP] Always verify the XIF matches the firmware on the actual device. Manufacturers add or remove variables between revisions. A mismatched XIF produces phantom points that never update and missing points that should have been visible.
For the step-by-step live-extraction procedure, see Using NodeUtil to Discover LonWorks Devices and Extract XIF Files.
From XIF To Gateway Point List
A XIF is not yet a point list. Converting it into one is a repeatable step:
- Filter the network variable list to the variables the supervisory system actually needs.
- Record the index, name, direction, and Standard Network Variable Type for each kept variable.
- Decide the destination object type (BACnet AI/AV/BI/BO/MSI/MSV, Modbus register, MQTT topic).
- Capture engineering-unit conversion where the source unit differs from the destination expectation.
- Note any SCPT or UCPT values that must be read alongside the network variables.
For full Standard Network Variable Type to BACnet mapping detail and the metric-to-imperial conversion table, see the LonWorks SNVT Reference and XIF Mapping Guide.
[!TIP] Steps 1–4 above can be automated. The LonWorks XIF -> QuickServer Converter accepts a
.xiffile in the browser and emits a ready-to-load FieldServer Bridge CSV for BACnet/IP or Modbus/TCP, including struct expansion and engineering-unit mapping. Drop the XIF, paste the Neuron ID, download the CSV. No upload to any server.
Common Failure Modes
| Failure | Likely Cause | Action |
|---|---|---|
| Tool will not open the XIF | Unsupported format version | Convert with a newer tool or request a compatible export |
| Mapped point never updates | XIF does not match firmware on the device | Re-extract the XIF live or request the correct revision |
| Value reads but units are wrong | Standard Network Variable Type in the XIF does not match the integrator’s assumption | Re-read the type field, not the variable name |
| Expected point is missing entirely | Data is exposed as an SCPT or UCPT, not as a network variable | Search the configuration-property section |
| Two devices look identical but bind differently | Different Program IDs in the headers | Treat as distinct interfaces; do not share a XIF |