Lon Markup Language

Overview

This document defines the content of a lon XML interface file. Basic syntax: The xml interface file represents a collection of objects. These objects may contain predefined elements and/or undefined elements. LonDevice contains the predefined element deviceData and any number of undefined NetworkVariables. As a general rule, elements which are not a defined element of the parent must have a type attribute. Defined elements must provide a value "v" attribute or contain defined elements.

  
<name  type="XLonXmlType">
<name  v="value">
  

Example:

  
<T7300h type="XLonDevice">
 <!-- Defined element deviceData with no type specified -->
 <deviceData
  <!-- Defined element with value -->
  <programID v="80 0 c 50 3c 3 4 17"/>
  . . .
 </deviceData>
 
 <!-- Undefined element with specified type -->
 <nviRequest type="XNetworkVariable"> 
  <index v="0"/>
 </nviRequest>
<T7300h type="XLonDevice">
  

The set of valid LonXmlTypes are: XLonXMLInterfaceFile, XLonDevice, XEnumDef, XTypeDef, XNetworkVariable, XNetworkConfig, XConfigProperty, XMessageTag

LonXMLInterfaceFile

The root type is LonXMLInterfaceFile. It may contain EnumDefs, TypeDefs, and LonDevices. It may also reference other LonXMLInterfaceFiles to allow for EnumDefs, and TypeDefs to be shared. The file attribute indicates the element is an included file

  
<!-- Example with reference to other interface files. -->
<T7300h type="XLonXMLInterfaceFile">
 <HwTherm file="datatypes\HwTherm.lnml"/>
 <HwCommon file="datatypes\HwCommon.lnml"/>
 <T7300h type="XlonDevice">
</T7300h>

<!-- Example with enumDefs and typeDefs included in single file. -->
<T7300h type="XLonXMLInterfaceFile">
 <HwThermAlarmEnum type="XenumDef"> . . . </HwThermAlarmEnum>
 <HwThermAlarm type="XTypeDef"> . . . </HwThermAlarm>
 <T7300h type="XLonDevice"> . . . </T7300h>
</T7300h>     
  

TypeDefs

EnumDefs and TypeDefs elements are needed to define the data portion of nvs, ncis, and config properties. An EnumDef contains a set of tag/id pairs where the name of the element is the tag and the value is the id.

  
<HwThermAlarmEnum type="XEnumDef">
 <NoAlarm v="0"/>
 <T7300CommFailed v="2"/>
 <AlarmNotifyDisabled v="255"/>
 </HwThermAlarmEnum>
  

A TypeDef contains a set of data elements. Each data element contains a name and set of qualifiers. The "qual" attribute contains a type field(u8, s8, b8, e8 ..), type restrictions (min,max) and encoding (resolution, byteOffset, bitOffset, len) information. For a description of valid element values see Appendix B. If an element is an enumeration then the enumDef attribute must be included to specify the name of the EnumDef used.

  
<HwThermAlarm type="XTypeDef">
 < elem n="subnet" qual="u8 res=1.0 off=0.0"/>
 < elem n="type" qual="e8" enumDef="HwThermAlarmEnum"/>
</HwThermAlarm>
  

A TypeDef element may also include "default" and "engUnit" attributes.

  
<HwThermConfig type="XTypeDef">
 <TODOffset qual="u8 byt=0 bit=0 len=4 min=0.0 max=15.0 "
    default="0" engUnit="F"/>
 <DeadBand qual="ub byt=0 bit=4 len=4 min=2.0 max=10.0 "
    default="2" engUnit="F"/>
</HwThermConfig>   
  

A TypeDef may have nonstandard features which require a software implementation. This is the case for typedefs with unions. Unions are not currently supported. A typeSpec attribute can be used to specify a class file in a baja module as the implementation of the TypeDef. The class must be a subclass of BLonData and provide overrides to byte[] toNetBytes() and fromNetBytes(byte[] netBytes).

  
<FileStatus type="XTypeDef">
 < typeSpec v="lonworks:LonFileStatus"/>
</FileStatus>
  

LonDevice

A LonDevice consists of a defined element deviceData and sets of 0 or more of each XNetworkVariable, XNetworkConfig, XConfigProperty, and XMessageTag type elements.

  
<T7300h type="XLonDevice">
 <deviceData> . . . </deviceData>
 <nviRequest type="XNetworkVariable"> . . . </nviRequest>
 <nvoAlarmLog type="XNetworkVariable"> . . . </nvoAlarmLog>
  <nciApplVer type="XNetworkConfig"> . . . </nciApplVe>
 <ScheduleFile type="XConfigProperty"> . . . </ScheduleFile>
 <fx_explicit_tag type="XMessageTag"> . . . </fx_explicit_tag>
</T7300h>
  

DeviceData

DeviceData is a defined set of values need to describe or qualify a lonworks device. A complete list of elements and their default values provided later.

  
<deviceData>
 <majorVersion v="4"/>
 <programID v="80 0 c 50 3c 3 4 17"/>
 <addressTableEntries v="15"/>
 . . .
</deviceData>
  

NVs, NCIs, ConfigProps

NetworkVariable, NetworkConfig (nci), and ConfigProperty elements share a common structure. Each one consists of a set of defined elements and a data definition. See Appendix A for a complete list of defined elements and their default values.

The data definition can take one of three forms:

  1. for standard types a snvtType(for nv/nci) or scptType(for nci/cp) element
  2. a typeDef element to specify the XTypeDef containing the data elements
  3. a set of elem entries contained in the nv,nci,cp with the same definition as used for TypeDef
   
<nvoAlarmLog type="XNetworkVariable>
 <index v="38"/>
 <direction v="output"/>
 <typeDef="HwThermAlarmLog"/>
</nvoAlarmLog>

<nviRequest type="XNetworkVariable">
 <index v="0"/>
 <snvtType v="objRequest"/>
 . . .
</nviRequest>

<nciSetpoints type="XNetworkConfig">
 <index v="17"/>
 <snvtType v="tempSetpt"/>
 . . .
</nciSetpoints>

<bypassTime type="XConfigProperty">
  <scptType v="CpBypassTime"/>
 <scope v="object"/>
 <select v="0"/>
 . . .
  </bypassTime>
  

File Attribute

There will be cases where it is desirable to nest interface files. This will provide a means to share type definitions between multiple device interface files. It may also ease the process of auto generating the files when the data is contained in multiple forms (i.e. xif files, resource files, ...).

To include a file an element with the "file" attribute is included in the root. The path in the file attribute entry is specified relative to the containing file.

The following is an example of nested files. File #1 contains enum definitions, File #2 contains type definitions which use the enumDefs and file #3 contains the device definition which may use both.

File #1 ..\honeywell\enum\ HwThermEnum.xml
  
<?xml version="1.0" encoding="UTF-8"?>
<HwThermEnum type="XLonXMLInterfaceFile">
 <HwThermAlarmEnum type="XEnumDef">
  <NoAlarm v="0"/>
  <InvalidSetPtAlrm v="1"/>
  . . .
 </HwThermAlarmEnum>
 . . .
</HwThermEnum>
  
File #2 ..\honeywell\datatypes\ HwTherm.xml
  
<?xml version="1.0" encoding="UTF-8"?>
<HwTherm type="XLonXMLInterfaceFile">
 <HwThermEnum  file="..\enum\HwThermEnum.xml"/>
 <HwThermAlarm  type="XTypeDef">
  <elem n="subnet" qual="us res=1.0 off=0.0 "/>
  <elem n="node" qual="us res=1.0 off=0.0 "/>
  <elem n="alarmType" qual="en " enumDef="HwThermAlarmEnum"/>
 </HwThermAlarm>
 . . .
</HwTherm>
  
File #3 ..\honeywell\
  
<?xml version="1.0" encoding="UTF-8"?>
<T7300h type="XLonXMLInterfaceFile">
 <HwTherm  file="..\datatypes\HwTherm.xml"/>
 <T7300h type="XLonDevice"> 
   <nvoAlarm type="XNetworkVariable" >
   <typeDef="HwThermAlarm"/>
   <index v="36"/>
   <direction v="output"/>
...
  </nvoAlarm>
 </T7300h>
</T7300h>
  

XDeviceData Definition

XDeviceData definition: see LonMark External Interface File Reference Guide 4.0B

TypeNameDefaultValid Values
intmajorVersion0-
intminorVersion0-
byte[]programID0 0 0 0 0 0 0 0-
intdomains2-
intaddressTableEntries0-
booleanhandlesIncomingExplicitMessagesfalse-
intnumNvDeclarations0-
intnumExplicitMessageTags0-
intnetworkInputBuffers0-
intnetworkOutputBuffers0-
intpriorityNetworkOutputBuffers0-
intpriorityApplicationOutputBuffers0-
intapplicationOutputBuffers0-
intapplicationInputBuffers0-
intsizeNetworkInputBuffer0-
intsizeNetworkOutputBuffer0-
intsizeAppOutputBuffer0-
intsizeAppInputBuffer0-
StringapplicationTypeunknownunknown,mip,neuron,hostSelect,hostNISelect
intnumNetworkVariablesNISelect0-
intrcvTransactionBuffers0-
intaliasCount0-
booleanbindingIIfalse-
booleanallowStatRelativeAddressingfalse-
intmaxSizeWrite11-
intmaxNumNvSupported0-
intneuronChipType0-
intclockRate0-
intfirmwareRevision0-
intrcvTransactionBlockSize0-
inttransControlBlockSize0-
intneuronFreeRam0-
intdomainTableEntrySize0-
intaddressTableEntrySize0-
intnvConfigTableEntrySize0-
intdomainToUserSize0-
intnvAliasTableEntrySize0-
booleanstandardTransceiverTypeUsedtrue-
intstandardTransceiverTypeId0-
inttransceiverType0-
inttransceiverInterfaceRate0-
intnumPrioritySlots0-
intminimumClockRate0-
intaveragePacketSize0-
intoscillatorAccuracy0-
intoscillatorWakeupTime0-
intchannelBitRate0-
booleanspecialBitRatefalse-
booleanspecialPreambleControlfalse-
StringspecialWakeupDirectioninputinput,output
booleanoverridesGenPurposeDatafalse-
intgeneralPurposeData10-
intgeneralPurposeData20-
intgeneralPurposeData30-
intgeneralPurposeData40-
intgeneralPurposeData50-
intgeneralPurposeData60-
intgeneralPurposeData70-
intrcvStartDelay0-
intrcvEndDelay0-
intindeterminateTime0-
intminInterpacketTime0-
intpreambleLength0-
intturnaroundTime0-
intmissedPreambleTime0-
intpacketQualificationTime0-
booleanrawDataOverridesfalse-
intrawDataClockRate0-
intrawData10-
intrawData20-
intrawData30-
intrawData40-
intrawData50-
StringnodeSelfID""-

NetworkVariable and Network Config common elements

TypeNameDefaultValid Values
StringsnvtType"xxx"from SNVT Master List."SNVT_angle_vel" becomes "angleVel".
intindex-1-
intaverateRate0-
intmaximumRate0-
intarraySize1-
booleanofflinefalse-
booleanbindabletrue-
Stringdirection"input"input,output
StringserviceType"unacked"acked, repeat, unacked, unackedRpt
booleanserviceTypeConfigurabletrue-
booleanauthenticatedfalse-
booleanauthenticatedConfigurabletrue-
booleanpriorityfalse-
booleanpriorityConfigurabletrue-

NetworkVariable only elements

TypeNameDefaultValid Values
StringobjectIndex""-
intmemberIndex-1-
intmemberArraySize1-
booleanmfgMemberfalse-
booleanchangeTypefalse-

NetworkConfig only elements

TypeNameDefaultValid Values
StringscptType""-
Stringscope"node"node,object,nv
Stringselect""If for node select=-1. Possible formates are n n~m n-m n.m n/m
StringmodifyFlag"anytime"anytime, mfgOnly, reset, constant, offline, objDisable, deviceSpecific
floatmaxFloat.NaN-
floatminFloat.NaN-
booleanchangeTypefalse-

ConfigParameter elements

TypeNameDefaultValid Values
StringscptType""-
Stringscope"node"node,object,nv
Stringselect""If for node select=-1. Possible formates are n n~m n-m n.m n/m
StringmodifyFlag"anytime"anytime, mfgOnly, reset, constant, offline, objDisable, deviceSpecific
intlength0-
intdimension1-
floatmaxFloat.NaN-
floatminFloat.NaN-
StringprincipalNv""if the scope is object and the scpt is inherited then this specifies the memberNumber of the principalNv in the selected object. Prefixed with '#' if mfgDefined member '|' if standard member.

Element Qualifier

The format for an element attribute is:

qual="Type [qualifier=xx]"
example: qual="u8 res=0.1 min=5 max=12"
TypeDevice Data TypeValid Qualifiers
c8character - 1 byte-
s8signed short - 1 byteres, off, min, max, invld
u8unsigned short - 1 byteres, off, min, max, invld
s16signed long - 2 byteres, off, min, max, invld
u16unsigned lon - 2 byteres, off, min, max, invld
f32float - 4 byteres, off, min, max, invld
s32signed int - 4 bytesres, off, min, max, invld
b8boolean - 1 byte-
e8enumeration - 1 byte-
bbboolean in bit fieldbyt, bit, len
ebenumeration in bit fieldbyt, bit, len
ubunsigned int in bit fieldbyt, bit, len, min, max, invld
sbsigned int in bit fieldbyt, bit, len, min, max, invld
ststringlen
nano type - byte arraylen
Qualifier CodeDescriptionDefault
resresolution float1.0
offOffset0.0
minMinimum legal valueNot specified
maxMaximum legal valueNot specified
invldInvalid valueNot specified
bytByte offset - 0 based-1
bitBit offset - 0 based, 7 for msb, 0 for lsb0
lenNumber of bytes(na), char(st) or bits(bb,eb,ub)1