Issue
When troubleshooting LonWorks devices, configuration parameters (SCPTs and UCPTs) stored inside the FILE section of a XIF file can be difficult to interpret. The FILE template and value blocks contain encoded definitions that determine how device configuration data is stored and retrieved. Without understanding this structure, diagnosing NCI-related issues becomes challenging.
For information regarding NCI's that are not part of a FILE definition, refer to Understanding the NVVAL part of a XIF file
Product Line
EcoStruxure Building Operation, Satchwell MicroNet, Satchwell Sigma, TAC IA Series, TAC Vista
Environment
- LonWorks Networks
- XIF files containing FILE template and FILE value sections
- Devices where configuration parameters (CPTs) are part of a FILE block rather than NVVAL
Cause
Certain configuration parameters (SCPT/UCPT values) are stored in the FILE section of a XIF file.
FILE template 0 2
"1.1;"
"2,23.24.25.26.27.28.29.30.31.32.33.34.35.36.37.41.42.43.45.46,0\x80,49,2;"
"1,1,0\x80,60,12;"
"1,1,0\x80,52,2;"
"2,0.2.3.5.6.7.8.9.10.16.17.18.19.20.21,0\x80,48,2;"
"1,0,0\x80,17,31;"
"1,1,0\x80,34,2;"
"1,1,0\x80,23,2;"
"1,1,0\xA4,169,1;"
"1,1,4\x80,3,8;"
"1,1,4\x80,5,17;"
"1,1,3\x80,1,2;"
"1,1,4\x80,4,9;"
"1,1,4\xA4,13,1;"
"1,1,4\xA4,14,1;"
"1,1,4\xA4,15,1;"
"1,1,4\xA4,16,1;"
"1,1,4\xA4,17,1;"
"1,1,4\x80,18,1;"
"1,1,0\x80,42,2;"
"1,1,0\x80,36,2;"
"1,1,0\x80,193,2;"
"1,1,4\x80,8,2;"
"1,0,3\x80,2,2;"
"1,0,0\x84,165,1;"
"1,0,0\xA4,166,1;"
"1,1,6\xA4,2,8;"
FILE value 1 1 116
0x0B, 0xB8, 0x09, 0x1D, 0x09, 0xFB, 0x0B, 0x80, 0x08, 0x77, 0x07, 0x98, 0x06, 0x13, 0x00, 0x02,
0x23, 0x28, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x78, 0x7F, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
0x00, 0x80, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00,
0xFF, 0xFF, 0x7F, 0xFF, 0x7F, 0xFF, 0x13, 0x88, 0x00, 0x00, 0x02, 0x0B, 0x00, 0x00, 0x00, 0x00,
0x00, 0x00, 0x00, 0x00This section can appear cryptic because:
- CPT definitions use multi-field encodings.
- Flags (e.g. device-specific, read-only, manufacturing-only) are encoded as hex.
- Byte offsets and lengths are defined indirectly via the template.
- Vector lengths must be interpreted via combined fields.
- The value block is a raw byte array that must be decoded using the template.
These factors make interpreting configuration values difficult without a breakdown of the template format.
Resolution
The FILE section contains two parts that work together: FILE template and FILE value.
1. FILE Template (Structure Definition)
The FILE template defines how each CPT is stored.
Example:
"1,1,0\x80,60,12;"
Each entry follows the format:
"A,B,C\xDD,E,F,G;"
Field meanings
- A – Ownership
- 0 device
- 1 function block
- 2 network variable
- B – Function block or variable index
- C – Type selector
- 0 SCPT
- 3,4,5,6 UCPT
- DD – Handling flags (bitfield)
- a: Always 1
- c: Device-specific
- d: Manufacturing-only
- e: Reset required after change
- f: Read-only
- g: Device must be offline to write
- h: FB must be disabled to write
- E – CPT index
- F – CPT byte length
- G – Optional vector multiplier
Example interpretation:
"1,1,0\x80,60,12;"
- CPT belongs to FB 1
- Standard CPT (SCPT)
- No special flags set (0x80)
- Index 60 → SCPTsetPnts (based on SNVT_temp_setpt)
- Length 12 bytes
2. FILE Value (Encoded Data Block)
The FILE value section contains the raw bytes for all CPTs defined in the template.
Example:
FILE value 1 1 116
0x0B, 0xB8, 0x09, 0x1D, ...
- First two numbers identify a value section.
- The optional length (116 bytes) should match total CPT byte requirements.
Each CPT’s data must be decoded using:
- Its offset (from template sequence)
- Length (field F × optional G)
- SNVT/SCPT resolution rules
Example decoding:
CPT entry:
"2,23.24...45.46,0\x80,49,2;"
Refers to SNVT_time_sec (index 49).
First two bytes:
- 0x0B 0xB8 = 101110111000 (binary) = 3000 decimal → 300.0 seconds.
Example: SCPTsetPnts (12 bytes)
"1,1,0\x80,60,12;"
SNVT_temp_setpt values decoded:
| Bytes | Decimal | Adjusted | Member |
|---|---|---|---|
| 09 1D | 2333 | 23.33 | occupied_cool |
| 09 FB | 2555 | 25.55 | standby_cool |
| 0B 80 | 2944 | 29.44 | unoccupied_cool |
| 08 77 | 2167 | 21.67 | occupied_heat |
| 07 98 | 1944 | 19.44 | standby_heat |
| 06 13 | 1555 | 15.55 | unoccupied_heat |
Troubleshooting Tips
- Verify the total byte length in FILE value matches all template-defined CPT lengths.
- Confirm SCPT/UCPT index maps to correct SNVT type.
- If TAC Vista cannot import CPTs linked to NVs, update entries:
"2,..." → "1,1,..."
