Interpreting and Generating LonWorks XIF Files

What A XIF File Is

A XIF file is the device interface file for a LonWorks device. LonMark formally calls it a device interface file (DIF), but the .xif extension and the “XIF” name are universal in field work. The file declares the network-visible interface of one or more LonWorks devices: the network variables they expose, the message tags, the configuration files, the buffer counts, the Neuron chip parameters, the channel and transceiver settings, and self-documentation text.

A XIF does not describe the internal algorithms of the device. It describes only the inputs the algorithm consumes and the outputs it produces over the LonWorks network. That is what a gateway, network management tool, or commissioning database needs to map and bind the device correctly.

The authoritative specification is the LonMark Device Interface File Reference Guide. The current published revision is 4.402 (May 2009), available from LonMark International. This article follows that specification. See the Reference Documents section for full citations.

[!NOTE] For the protocol context — what network variables, bindings, SNVTs, and Program IDs do at the LonTalk level — see the LonWorks XIF Files topic page and the LonWorks SNVT Reference and XIF Mapping Guide.

The XIF, XFB, And XFO File Family

LonWorks tools may produce three related files for the same device interface.

Extension	Form	Authored By	Purpose
`.xif`	Plain text	Development or network management tool	Authoritative human-readable interface description
`.xfb`	Binary	LNS (LonMaker, IzoT CT)	Binary device interface file used by LNS for performance
`.xfo`	Optimized	LNS	Further-optimized binary form created automatically by LNS

The text .xif is the canonical artifact. LNS converts it to .xfb for runtime use and to .xfo for cached lookup. Other network operating systems may produce their own binary forms. If only a binary file is present, the XIF32BIN utility (shipped with LNS) can convert it back to the text form for inspection.

File Structure

A XIF text file contains up to four sections, in this order. Only the header section is mandatory.

Header section — required. Identifies the device, the Program ID, the buffer counts, the Neuron chip parameters, the channel and transceiver, and the self-documentation text.
Network variable and message tag definitions — optional. One entry per static network variable and per message tag.
File definitions — optional, added in format version 4.0. Used for configuration files that hold SCPT and UCPT property values.
Network variable value definitions — optional, added in format version 4.0. Default values for configuration network variables.

The sections must appear in this order. Sections that have no content can be omitted entirely.

General Rules

These apply to every section:

A line whose first non-blank character is # is a comment. The entire line is ignored.
Multiple blank lines are allowed wherever a single blank line is required. Blank lines may appear between records and at the end of the file.
String fields contain an asterisk * when not applicable or when at their default value.
Integer fields contain 0 when not applicable. Some integer fields also use * to indicate a default value (added in format 3.0).
Maximum line length is 160 characters from format 4.0 onward.

Reading The Header

Here is a real header section, from an Echelon LonPoint AO-10 module XIF (the line numbers are for reference only and are not in the file):

1:  File: Ao10A.XIF generated by LONNCC32 Version 4.01.62, XIF Version 4.400
2:  Copyright (c) 1989 - 2003 Echelon Corp
3:  All Rights Reserved.  Run on Thu April 24 16:33:25 2002
4:
5:  90:00:01:05:19:8A:04:02
6:  2 15 0 21 0 3 3 3 3 4 11 11 9 9 0 0 9 14 1 1 128 21 0 0 0 0 0 0 0 0 2 15 0 0 0 0 0 0 2 1 0
7:  0 5 100 13 28 726 0 15 5 3 342 4 10000000
8:  1 7 1 0 4 4 4 15 200 0
9:  78125 0 0 0 0 0 0 0 0 0 0
10: 90 0 240 0 0 0 40 40 0 5 8 5 12 14 15
11: *
12: "x3.0@0,3[2]Analog Output,20006[2]PID Controller,20002[1]Digi
13: "tal Encoder,20005[2]Analog Fn Block,20010[2]Type Translator;
14: "Echelon LonPoint AO-10 Module version 2.x.  Supports two Anal
15: "og Outputs, two PID Controllers, one Digital Encoder, two An
16: "alog Function Blocks, and two NV Type Translators.
17:

Lines 1–4: Identity Block

Line	Contents
1	`File: <fileName> generated by <toolName>, XIF Version <majorNumber>.<minorNumber>`
2	Copyright information
3	Optional additional copyright plus required timestamp: `<info> Run on <day> <month> <date> <hour>:<min>:<sec> <year>`
4	Blank

If the file was created manually, <toolName> is Manual 0.0.0. The current format version is 4.400.

Line 5: Program ID

Eight 2-digit hex values separated by colons, no spaces. The first hex digit determines the format:

First digit 7 or less: an ASCII program-name string in hex.
First digit 8 or 9: structured ID with the layout FM:MM:MM:CC:CC:UU:TT:NN:

Field	Meaning
FM	Format and category
MM:MM	Manufacturer ID (assigned by LonMark)
CC:CC	Device class
UU	Device subclass
TT	Channel category
NN	Model number

The Program ID drives binding compatibility and device-replacement workflows. Two devices with the same Program ID present the same interface; two with different Program IDs are different interfaces even when they look identical otherwise. The full structured Program ID format is documented in the LonMark Application-Layer Interoperability Guidelines.

Line 6: Header Capabilities (42 Fields)

Line 6 is the largest line in the header. The spec defines 42 fields, although most projects only need a handful. Key fields:

Field	Format Version	Purpose
1	All	Number of non-ECS domains. Must be 2.
2	All	Number of non-ECS address table entries (0–15).
3	All	Boolean: 1 if the application handles incoming application messages.
4	All	Number of static network variable declarations (0–4096 host, 0–62 Neuron-hosted).
5	All	Number of non-ECS message tags (0–15).
6	All	Number of network input buffers (encoded — see table below).
7	All	Number of network output buffers (encoded).
8	All	Number of priority network output buffers (encoded).
9	All	Number of priority application output buffers (encoded).
10	All	Number of application output buffers (encoded).
11	All	Number of application input buffers (encoded).
12–15	All	Buffer sizes (encoded — see table below).
16	2.0	Application type (Unknown, MIP, Neuron-hosted, host-application, etc.).
17	2.0	Network variable configuration table size for MIP applications.
18	2.0	Number of receive transaction buffers.
19	3.1	Number of network variable alias table entries.
20	3.1	Relaxed binding constraints flag.
21	3.1	Statistics-relative address references allowed. Set to 1.
22	3.1	Maximum size memory block writable at a time.
23	3.2 / 4.1	Maximum number of network variables (static + dynamic).
24–27	4.2	ECS protocol version range, binding constraint level, ECS flags.
28–32	4.2	Reserved. Set to 0.
33	4.2	Number of domains (ECS).
34	4.2	Number of address table entries (ECS).
35	4.2	Number of message tags (ECS).
40–41	4.3	Network management version and capabilities.
42	4.4	Reserved. Set to 0.

The buffer count encoding is non-obvious:

Buffer Count	Encoded Value
0	0
1	2
2	3
3	4
5	5
7	6
11	7
15	8
23	9
31	10
47	11
63	12
95	13
127	14
191	15

Buffer sizes use a similar table mapping 20, 21, 22, 24, 26, 30, 34, 42, 50, 66, 82, 114, 146, 210, 255 bytes to encoded values 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0 respectively.

Lines 7–10: Neuron, Channel, And Transceiver Parameters

Four lines describe the device hardware in detail.

Line	Purpose
7	Neuron processor configuration: chip model, clock rate, firmware version, transaction block size, RAM and EEPROM sizes, table sizes, and (since 4.4) base clock rate factor. Set fields 1–12 to 0 for host-based devices where the network image is not downloadable.
8	Channel parameters: transceiver type ID (from `StdXcvr.xml` at lonmark.org), interface type, interface rate, priority slots, minimum clock rate, average packet size, oscillator accuracy and wakeup time.
9	Transceiver parameters: channel bit rate and special-purpose-mode settings.
10	Channel timing: receive start and end delays, indeterminate time, interpacket time, preamble length, turnaround time, packet qualification time.

The protocol-processor model field on line 7 identifies the silicon:

Value	Model
0	Neuron 3150 Chip or FT 3150 Smart Transceiver
1	PL 3150 Smart Transceiver
8	Neuron 3120 Chip
9–13	Neuron 3120E1 through E5 variants
14	Neuron CY3120E4 Chip or FT 3120 Smart Transceiver
15	PL 3120 Smart Transceiver

Line 11: End-Of-Transceiver Marker

A single asterisk marks the end of the transceiver section.

Lines 12–N: Self-Documentation String

One or more lines of device self-documentation. Each line begins with a double quote ", ends with a newline (no closing quote), and may be up to 60 characters. Non-printable characters use \xHH hex escapes with uppercase A–F. Multiple lines concatenate into a single string with no separators.

If the device has no self-documentation, line 12 is a single asterisk.

If the device’s static interface contains functional blocks (LonMark profile blocks), the self-documentation string is formatted per the LonMark Interoperability Guidelines and encodes the functional blocks, member NVs, and configuration property assignments.

Reading A Network Variable Definition

After the header, each declared network variable produces one record. Example:

1: VAR nvo01Value 2 0 0 0
2: 0 1 63 1 0 1 0 1 0 1 0 0 0
3: "@1|2
4: 95 *  2
5: 1 0 0 0 0
6: 1 0 0 1 0

Line 1: Identity And Rate

VAR <name> <index> <avgRate> <maxRate> <arraySize>

Field	Range	Meaning
name	up to 16 chars	NV name (e.g. `nvoSpaceTemp`)
index	0–4095	NV index number on the network
avgRate	0–250	Encoded average rate; rate = 2^((n/8)−5) updates per second, or 0 if unspecified
maxRate	0–250	Encoded maximum rate, same formula
arraySize	0 or 1–N	0 if not an array; otherwise the number of elements

Line 2: Behavior Flags (13 Fields)

Field	Meaning
1	Offline-update flag: 1 if the variable must be updated only when offline
2	Must be set to 1
3	Must be set to 63
4	Direction: 0 = input (NVI), 1 = output (NVO)
5	Default service type: 0 = acknowledged, 1 = repeated, 2 = unacknowledged
6	Service type changeable in field: 1 = yes, 0 = no
7	Authentication default: 1 = authenticated, 0 = not
8	Authentication changeable in field: 1 = yes, 0 = no
9	Priority default: 1 = priority, 0 = no
10	Priority changeable in field: 1 = yes, 0 = no
11	Polled attribute: depends on direction
12	Synchronized attribute: 1 if updates are transmitted in order
13	Configuration attribute: 1 if this is a configuration-class NV

Lines 3–N: Self-Documentation

Same format as the device-level self-documentation: double-quote-prefixed lines, \xHH hex escapes, up to 60 characters each. If the NV is part of a LonMark functional block, the format follows the LonMark Interoperability Guidelines for member-NV encoding.

A single * line means no self-documentation.

Line N+1: SNVT Index And Element Count

<snvtIndex> * <elementCount>

Field	Meaning
snvtIndex	1–255 = a standard SNVT (see the SNVT and SCPT Master List). 0 = user-defined type.
elementCount	Number of elements in a structure or union. 1 if scalar.

Lines N+2 To M: Per-Element Type Information

One line per element (scalar NVs have one line; structures and unions have one line per field):

<type> <offset> <size> <signedFlag> <arraySize>

Field	Values
type	0 = Character, 1 = 8-bit Integer, 2 = 16-bit Integer, 3 = Bitfield, 4 = Union, 5 = Typeless
offset	Bitfield offset 0–7, or 0 if not a bitfield
size	Bitfield size 1–7 or union size 1–31 bytes, else 0
signedFlag	1 if signed, 0 if unsigned or not applicable
arraySize	Array size 1–31 if the element is an array, else 0

Reading A Message Tag

Message tags follow the same general shape as NVs but use the TAG keyword:

1: TAG user_tag 0 69 76 0
2: 0 1 63 1 0 1 0 1 0 1 0 0 0

Line 1 fields: <name> <index> <avgRate> <maxRate> 0. Index range 0–14.

Line 2 follows the NV behavior-flag layout, with field 1 holding the bindFlag (1 if the tag is bindable, 0 if not — generally 1).

Reading File Definitions

Added in format 4.0 to declare configuration files used for SCPT and UCPT property values. There can be zero or one template file plus zero, one, or two value files.

FILE configTemplate 0 2
"This is the template file content

Line 1: FILE <name> <index> <type> [<length>]

Field	Values
index	0 for the template file, 1 or 2 for value files
type	2 for template, 1 for value file
length	Optional; auto-computed from contents if omitted

Subsequent lines are file contents in one of two encodings:

Character format — line starts with a double quote. Same \xHH rules as self-documentation.
Binary format — line is interpreted as hex bytes. 0x07, 0x89, 0xAB, 0xCD is equivalent to 0x0789abcd, 0789abcd, 7,89,ab,cd, or \x07\x89\xab\xcd.

Reading Network Variable Value Definitions

Added in 4.0 to carry default values for configuration network variables.

NVVAL
# config network input long configNv1 = {5000};
0x13, 0x88
# config network input int configNv2 = {100};
0x64
# config network input long configNv3 = {2252};
0x08, 0xCC

NVVAL is the section keyword. Each subsequent non-comment line gives the default value bytes for one configuration NV, in the order the configuration NVs were declared in the variable definition section. Hex bytes follow the same notation as binary file definitions.

How XIF Files Are Generated

A XIF can come from four places. The right source depends on what you have access to.

From A Development Tool (Compile-Time)

When a device firmware engineer compiles Neuron C source, the compiler emits a XIF that matches the application’s network variable declarations and configuration. This is the highest-fidelity XIF because it includes everything the compiler knows about the interface, including the self-documentation strings.

Tool	Notes
NodeBuilder FX	Echelon’s last NodeBuilder release; emits format 4.x XIFs
LonBuilder	Legacy Echelon tool; emits older formats
Mini EVK / FX	Evaluation kits used for small devices; same XIF output
IzoT NodeBuilder	Renesas successor for current LonWorks development

This is the file the manufacturer ships with the device. Request it directly when starting a project, before any field work.

From A Network Management Tool (Export From Database)

LonMaker, IzoT CT, OpenLNS, and other LNS-based tools store the device interface inside the network database. They can export a XIF for any commissioned device. This is the right path when the original manufacturer XIF is lost but the network database is intact.

Tool	Notes
LonMaker (legacy)	LNS 3.x-based; still found on commissioning laptops
IzoT CT	Current Renesas tool; recommended for new work
OpenLNS Server	LNS API; XIFs can be exported programmatically

Live Extraction From The Device

The Neuron chip stores enough of its own interface to allow live extraction over the LonWorks network. Echelon’s NodeUtil reads this self-documentation block and reconstructs a XIF. The reconstructed file lacks the original developer’s comments and some manufacturer metadata, but it is enough to map and bind the device.

Tool	Notes
NodeUtil	Echelon CLI; ships in the OpenLDV release. Connects through a U10/U20 USB interface or PCLTA card.
Chipkin QuickServer NodeUtil mode	The QuickServer can extract XIFs from connected devices on its own LonWorks port

For the step-by-step extraction procedure, see Using NodeUtil to Discover LonWorks Devices and Extract XIF Files.

Manual Authoring

A XIF can be written by hand in a text editor. Line 1 must declare Manual 0.0.0 as the tool name. This is rare in practice — buffer-encoding tables, transceiver parameters, and the 42-field header line are easy to get wrong. Manual XIFs are most useful for stubbing a fictional device during driver development, not for production.

Tools For Reading And Generating XIF Files

Tool	Reads	Generates / Exports	Notes
NodeBuilder FX / IzoT NodeBuilder	Yes	Yes (from Neuron C compile)	Authoritative source for new devices
LonMaker (legacy LNS)	Yes	Yes (export from database)	Most installed-base tool in retrofit work
IzoT CT	Yes	Yes (export from database)	Current Renesas successor to LonMaker
OpenLNS Server	Yes (API)	Yes (API export)	Programmatic access to the LNS database
NodeUtil	Yes	Yes (live extract)	Echelon CLI; works on Neuron-hosted devices
XIF32BIN	Converts text↔binary	Yes	LNS utility for `.xfb` and `.xif` interconversion
Chipkin QuickServer NodeUtil mode	Yes	Yes (live extract)	Gateway can extract during commissioning
LonScanner Protocol Analyzer	Yes (consumes for decode)	No	Uses XIF to label captured traffic

[!TIP] If a XIF file refuses to import, check line 1’s XIF Version field against the importing tool’s documented format support before re-extracting. Versions 3.x and 4.x are not always interchangeable on older tools.

Format Versions

The format has evolved since 1990. Important versions:

Version	Notable Additions
1.0	First version
2.0	Network variable arrays in a single record; expanded transaction and size parameters
3.0	Comment indicator (`#`); string default `*`, integer default `0`
3.1	Neuron Chip firmware version 6 support; revised binding constraints
3.2	NV count includes dynamic NVs
4.0	Backward-compatibility rules; 160-character line limit; File and NVVAL sections added
4.1	Backward-compatible repackaging of 3.2
4.2	Extended command set (ECS) fields per ANSI/EIA/CEA-709.1B
4.3	Neuron firmware version and capability fields
4.400	Base clock rate factor field; minor format version widened to 3 digits
4.401	Dynamic functional block support; clarified handling of duplicate programmatic NV names
4.402	Increased network variable and alias limits; added LNS FX commissioning-credit field. Current published revision (May 2009).

From 4.0 onward, interpreters must accept unknown records gracefully: discard any unrecognized record up to the next blank line, and accept up to 160 characters per line. A tool that claims to support version X.Y must also accept the known parts of any X.Z file where Z > Y.

Common Interpretation Pitfalls

Pitfall	Symptom	Action
XIF format newer than tool support	Tool refuses to import the file	Re-export from the device’s commissioning tool at a compatible version, or convert with XIF32BIN
XIF does not match installed firmware	Mapped points read but never update; phantom points appear	Re-extract live or request the correct firmware revision
NV name is `nv1`, `nv2`, etc. (no real names)	Live-extracted XIF lost the manufacturer’s name strings	Request the manufacturer XIF; live extraction preserves indexes and types but not always names
Self-documentation appears garbled	`\xHH` escapes were not decoded	Use a XIF-aware tool to render the documentation rather than reading raw
Expected configuration value missing	Value is in the `NVVAL` section, not the variable definition	Search for `NVVAL` and look for the matching declaration order
Two near-identical devices will not share a XIF	Program IDs differ	Treat as separate interfaces; do not share a XIF across Program IDs
Tool reports “binding constraint mismatch”	Line 6 field 20 or 26 differs from another node	Check ECS vs non-ECS device class on both ends

Re-Extracting A XIF

Re-extract when:

The site can produce a device but cannot produce the matching file.
Firmware was updated since the XIF was issued.
Line 1 declares a tool version not supported by your import path.
A mapped point exhibits phantom or missing behavior consistent with a mismatched interface.

Re-extraction does not preserve developer comments or some manufacturer-supplied metadata. When both a manufacturer file and a live extract are available, the manufacturer file is the authoritative source unless firmware has changed.

From XIF To Gateway Point List

Converting a XIF into a usable point list is the last step before configuring a gateway.

Filter the variable list to the variables the supervisory system actually needs.
Record the NV index, name, direction, and SNVT for each kept variable.
Decide the destination object type: BACnet AI/AV/BI/BO/MSI/MSV, Modbus register, MQTT topic.
Capture unit conversion where the source SNVT unit differs from the destination expectation.
Note any SCPT or UCPT values that must be read alongside the network variables.

For the full SNVT-to-BACnet mapping table and the metric-to-imperial conversion math, see the LonWorks SNVT Reference and XIF Mapping Guide.

Automate Steps 1–4 With The XIF Converter

The five steps above are mechanical once the XIF is in hand. The LonWorks XIF -> QuickServer Converter automates the first four: it parses the XIF, applies SNVT struct expansion (for example SNVT_switch to _Value + _State, SNVT_time_stamp to six date/time fields), assigns data-array offsets and BACnet Object IDs, and emits a ready-to-load FieldServer Bridge CSV for either BACnet/IP or Modbus/TCP. The tool runs entirely client-side in the browser — your XIF is not uploaded.

You still own step 5: review the configuration properties (SCPT/UCPT) section of the XIF separately, because runtime data exposed through properties rather than network variables needs different access paths.

To use the tool, you also need the device’s Neuron ID — the converter prompts for it on the page.

Reference Documents

LonMark Device Interface File Reference Guide, Revision 4.402 — the authoritative XIF text-format specification. May 2009, hosted by LonMark International. The file structure, header field layouts, network variable record format, buffer encoding tables, and format-version history in this article all derive from this specification. Previous revision 4.400 (Echelon document 078-0255-01A, June 2003) covers the same core format; revisions 4.401 and 4.402 added dynamic functional block support, raised network-variable and alias limits, and added the LNS FX commissioning-credit field.
LonMark Application-Layer Interoperability Guidelines — defines the structured Program ID layout (FM:MM:MM:CC:CC:UU:TT:NN) and the functional-block self-documentation format used inside XIF self-doc strings.
SNVT and SCPT Master List — the standard network variable type and standard configuration property type catalog. Required for interpreting the snvtIndex field on each NV record.
StdXcvr.xml — the standard transceiver type ID file referenced by line 8 field 2 of the XIF header.
Neuron C Programmer’s Guide — Echelon’s developer reference for the source code that compiles into the XIF declarations.
ISO/IEC 14908 — the standards-level definition of the LonTalk protocol family that the XIF describes.
NodeUtil User’s Guide — Echelon’s reference for the live XIF extraction tool.