ANSI C Based OPC UA Client/Server/PubSub SDK
Address Space Generation

The SDK provides support for binary address space files. So if your system provides a file system, you can enable file support and you are able to load address spaces at runtime from these binary files.

The SDK contains the tool xml2bin for generating a binary file from XML NodeSet file(s) which then can be loaded at runtime.

Generating Binary Files

Binary address space files are very compact files compared to their XML counterparts and way more efficient to load. This means it uses just a fraction of the memory required for XML parsing and it is much faster. The file format is described in OPC UA Binary File Format.

Invoking xml2bin

The possible command line arguments can be listed by calling the tool with the option -h as usual: ./xml2bin -h. The help also gives you one simple example.

1 Usage: xml2bin [-h] [-o <outputfile>] [<base xml files...>] <xml file...>
2  -h: print this help
3  -V: print version information
4  -s: strip unused type nodes (experimental)
5  -o: output file name
6  -a: export all namespace (except ns0)
7  -e <val>: select extensions to export where <val> can be 'none', 'default', or 'all'.
8  none: no node extensions will be exported.
9  default: all known Unified Automation extensions will be exported.
10  all: All extensions will be exported. Unkown will be stored as XML extension also in the binary file
11  so that they can be handled on application level.
12  -i: specifies a SDK nsidx to export
13  -u: specifies an namspace URI to export
14  -v: more verbose output
15  -b: byte string limit in byte (default = 4 MB = 4096 KB = 4194304 Byte)
16  -p: print addressspace
17  -P: placeholder file name
18  -l: default locale
19  <base xml files>: must be specified in correct order, starting with the base model,
20  followed by models built on top of the previous model.
21  <xml file>: The information model which gets processed.
22 Example: Convert the DI model to binary.
23  xml2bin -i2 -v -o di.bin Opc.Ua.NodeSet2.xml Opc.Ua.Di.NodeSet2.xml

Important Notes:

  • You need to list all NodeSet XML file in correct order which are required to load the XML file which you want to convert. In the example above this was the DI model, which is based on standard UA model (which is always required). E.g. PLCOpen whould require DI, which again requireds UA, so the list of files would be: Opc.Ua.NodeSet2.xml Opc.Ua.Di.NodeSet2.xml Opc.Ua.Plc.NodeSet2.xml
  • -o: Specifies the output filename e.g. 'di.bin'.
  • -i select this namespace to be exported. The namspaces are normally numbered that way:
    • 0=UA (always)
    • 1=UA Server Diagnostics (always)
    • 2=First custom model (e.g. DI)
    • 3=Second custom model (e.g. PLCOpen) If unsure just call the command without -i. It will print the namespace table.
1 $> ./xml2bin Opc.Ua.NodeSet2.xml Opc.Ua.Di.NodeSet2.xml Opc.Ua.Plc.NodeSet2.xml
2 SDK Index XML Index Prefix URI
3 0 0 ua
4 2 2 ns2
5 3 1 ns3

Important here is the SDK Index, which is the index that will be used in the SDK and must be unique. The columne XML Index, shows the numeric index used in the XML file which is not unique across files. Prefix is used only for code generation. URI is the unique URI of the information model. Instead of selecting the SDK Index using -i you can also select the model using the option -u and the URI string.

Inspecting Binary Files

The SDK also contains two test applications:

  • fileinfo: Simply output information from the file header to get the number of nodes, references, etc.
  • filetest: Is an example application, which loads the complete file and can print its contents to console. Because this is no UA Server application the contents doesn't need to make sense. E.g. referenced types may not exist. This can be used to inspect the binary file contents which maybe cannot be loaded in real servers. By default it will print any error in loading the file to stderr, if the file could not be parsed properly, but not the complete file contents. By using the option '-v' (verbose output) it prints the complete file dump.

FileInfo Example:

1 $> ./fileinfo ns0.bin
2 File version: 1.5
3 File statistics:
4  number of global extensions: 0
5  number of required namespaces: 0
6  number of provided namespaces: 1
7  number of string tables: 1
8  number of data types: 130
9  number of variable types: 37
10  number of object types: 121
11  number of reference types: 27
12  number of variables: 1284
13  number of objects: 265
14  number of methods: 144
15  number of views: 0
16  number of references: 4813
17  number of strings: 0
18  number of guids: 0

FileTest Example:

1 $> ./filetest -v ns0.bin
2 Adding extension namespace 0:'extension://unifiedautomation'
3 Adding stringtable 0 for locale '' with 1309 strings.
4 Adding string for table 0: ''
5 Adding string for table 0: '<AdditionalGroup>'
6 Adding string for table 0: '<ClientName>'
7 Adding string for table 0: '<FileDirectoryName>'
8 Adding string for table 0: '<FileName>'
9 Adding string for table 0: '<NamespaceIdentifier>'
10 Adding string for table 0: '<VendorCapability>'
11 Adding string for table 0: 'A URI that uniquely identifies the dictionary.'
12 Adding string for table 0: 'A base type for a user identity token.'
13 ...
14 Adding node id=i=11939, nodeclass=DATATYPE, bn=0:OpenFileMode, dn=OpenFileMode, desc=
15 datatype attributes:
16  is_abstract: false
17  definition: Enum
18  num_fields: 4
19  fields:
20  Read -> 1
21  Write -> 2
22  EraseExisting -> 4
23  Append -> 8
24 ...
25 Adding reference i=30 -> i=2001 : i=45
26 Adding reference i=30 -> i=2002 : i=45
27 ...
28 File statistics:
29  header: 37 bytes
30  extensions: 22 bytes
31  stringtables: 36926 bytes
32  namespaces: 50 bytes
33  datatypes: 5779 bytes
34  referencetypes: 425 bytes
35  variabletypes: 696 bytes
36  objecttypes: 1689 bytes
37  variables: 377587 bytes
38  objects: 4000 bytes
39  methods: 2010 bytes
40  views: 0 bytes
41  references: 35729 bytes
42  # of strings: 1309
43 Successfully loaded file.