Automation Interface

Generating BACnet client/server objects

The System Manager offers the CreateChild procedure for generating TwinCAT configuration elements. A TreeItem name, sub-type (for BACnet always 48), an insert position string or sub-type-specific information can be used as parameter.

serverItem.CreateChild("Bi_Demo", 48, "", 0x03060203);

The last parameter is also referred to as Class-ID. It identifies the element to be created. It is possible to create a BACnet device (CID_TcIoBACnetBACnetDevice), a BACnet server (CID_TcIoBACnetServer) or a BACnet client (CID_TcIoBACnetClient). BACnet server objects can be created with the Class-ID CID_TcIoBACnetObjBase together added with the object type. A BinaryInput object has the Class ID 0x03060203. BACnet client objects with base Class-ID CID_TcIoBACnetObjRemoteBase.

ULONG CID_TcIoBACnetBACnetDevice   = 0x03060001;
ULONG CID_TcIoBACnetServer     = 0x03060110;
ULONG CID_TcIoBACnetClient     = 0x03060120;
ULONG CID_TcIoBACnetObjBase    = 0x03060200;
ULONG CID_TcIoBACnetObjRemoteBase  = 0x03060300;
ULONG CID_TcIoBACnetDynamicObject  = 0x030602FE;

Property configuration

The procedures ProduceXml and ConsumeXml are used to configure the individual TwinCAT components. Use the System Manager menu "Action" > "Export XML Description ..." to export and view the XML description for test purposes.

<Parameter>
  <Name>TcIoBACnetPropCfg_PropTimeDelay</Name>
  <BaseType GUID="{18071995-0000-0000-0000-000000000007}">DWORD</BaseType>
  <PTCID>#x03060171</PTCID>
</Parameter>
...
<Value>
  <Name>TcIoBACnetPropCfg_PropTimeDelay</Name>
  <Value>0</Value>
</Value>

The figure shows a section of the XML description of a BACnet object generated with ProduceXml. The structure and the type of a parameter are described in the Parameter section. The actual value is specified in the Value section. The parameter ID of BACnet properties consists of 0x03060100 plus the respective property ID. The following C# source code extract shows how the value of the property TimeDelay, as shown in the "Settings" tab, can be read.

XmlDocument doc = new System.Xml.XmlDocument();
s = objItem.ProduceXml(true);
doc.LoadXml(s);
XmlNodeList list = doc.SelectNodes("//Value[./Name='" + "TcIoBACnetPropCfg_PropTimeDelay"+ "']/Value");
UInt32 timeDelay = Convert.ToUInt32(list[0].InnerText);

When writing the property data it is advisable to first read the XML description via ProcuceXml, then to edit the parameter value and finally to read the parameter data via ConsumeXml.

XmlDocument doc = new System.Xml.XmlDocument();
s = objItem.ProduceXml(true);
doc.LoadXml(s);
XmlNodeList list = doc.SelectNodes("//Value[./Name='" + "TcIoBACnetPropCfg_PropTimeDelay"+ "']/Value");
list[0].InnerText = 10;
objItem.ConsumeXml(doc.OuterXml);

Depending on the data type of the property, the parameter section may have to be adjusted, in addition to the parameter value. For string data types the string length must be entered under data type STRING(XX).

<Parameter>
  <Name>TcIoBACnetPropCfg_PropObjectName</Name>
  <BaseType GUID="{18071995-0000-0000-0000-000000010006}">STRING(5)</BaseType>
  <PTCID>#x0306014d</PTCID>
</Parameter>
...
<Value>
  <Name>TcIoBACnetPropCfg_PropObjectName</Name>
  <String>CAL_0</String>
</Value>

For properties with complex data types the configuration data are stored as byte arrays. Data coding is described in more detail in section "Data types". To change complex parameter data, the BitSize and the Elements of the ArrayInfo which specifies the number of bytes must be adjusted in the Parameter section. The actual data are coded in HEXBIN format in the Value section ( 2 hexadecimal values per byte ).

<Parameter>
  <Name HideSubItems="1">TcIoBACnetPropCfg_PropDatelist</Name>
  <BitSize>96</BitSize>
  <BaseType GUID="{18071995-0000-0000-0000-000000000001}">BYTE</BaseType>
  <ArrayInfo>
    <LBound>0</LBound>
    <Elements>12</Elements>
  </ArrayInfo>
  <PTCID>#x03060117</PTCID>
</Parameter>
...
<Value>
  <Name>TcIoBACnetPropCfg_PropDatelist</Name>
  <Data>00000000ffffffff00000000</Data>
</Value>

Process data configuration

The process data configuration within the XML description can also be modified via the Automation Interface. Each property that was activated as a process data variable has an entry in section DataArea. In TwinCAT BACnet/IP two DataAreas are available, one for input process data and one for output process data. The example shows the configuration of the DataArea with two input process data. A symbol exists for each activated property. The symbol contains the BitOffset, which determines the position of the property data in the process data image. It is important that the properties start at an aligned address (WORD symbol at addresses that can be divided by 2, DWORD symbols at addresses that can be divided by 4). The ByteSize of the DataArea indicates the size of the symbols.

<DataAreas>
  <DataArea>
    <AreaNo AreaType="InputSrc" ChildArea="1">0</AreaNo>
    <Name>Inputs</Name>
    <ContextId>1</ContextId>
    <ByteSize>4</ByteSize>
    <Symbol>
      <Name>PresentValue</Name>
      <BaseType GUID="{18071995-0000-0000-0000-000000000004}">WORD</BaseType>
      <BitSize>16</BitSize>
      <BitOffs>0</BitOffs>
    </Symbol>
    <Symbol>
      <Name>StatusFlags</Name>
      <BaseType GUID="{18071995-0000-0000-0000-000000000004}">WORD</BaseType>
      <BitSize>16</BitSize>
      <BitOffs>16</BitOffs>
    </Symbol>
  </DataArea>
  <DataArea>
    <AreaNo AreaType="OutputDst" ChildArea="1">1</AreaNo>
    <Name>Outputs</Name>
    <ContextId>1</ContextId>
    <ByteSize>0</ByteSize>
  </DataArea>
</DataAreas>

In addition to the configuration of the DataArea symbols, the parameters TcIoBACnetPdInCfg and TcIoBACnetPdOutCfg must contain information for the BACnet stack as to which property data should be treated as process data. If the parameters TcIoBACnetPdInCfg and TcIoBACnetPdOutCfg are changed, the data length must be adjusted in the Parameter section. The structure of the two parameters is explained below.

<Value>
  <Name>TcIoBACnetPdInCfg</Name>
  <Data>0000000055000000100000006f000000</Data>
</Value>

BACnet Server

For each activated process data property, the parameters TcIoBACnetPdInCfg and TcIoBACnetPdOutCfg must contain an element with structure ProcessDataServerCfg. The structure must specify to which bit offset the data should be copied, the property type (propId), and for output process data the priority with which the property data are to be copied to the PriorityArray.

Struct ProcessDataServerCfg
{
    ULONG bitOffs;
    USHORT propId;
    USHORT priority;
}

BACnet Client

Client objects also have further parameters in addition to the symbol configuration, which specify the configuration of the property process data. In client objects a distinction is made between input process data and output process data. The structure fields match the configuration dialogs in the System Manager.

Struct ProcessDataClientInCfg
{
    USHORT propId;
    USHORT useCov      : 1;
    USHORT usePolling  : 1;
    USHORT reserved    : 6;
    USHORT tickModulo  : 8;
    ULONG timeDataCOV;
    ULONG timeDataPoll;
    ULONG bitOffs;
    ULONG bitLen;
    floatcovIncrement;
}

struct ProcessDataClientOutCfg
{
    USHORT propId;
    USHORT useWriteOnChange : 1;
    USHORT usePeriodicWrite : 1;
    USHORT usePriority      : 1;
    USHORT reserved         : 5;
    USHORT tickModulo       : 8;
    ULONG priority;
    ULONG cycleTime;
    ULONG bitOffs;
    ULONG bitLen;
}