Conversion from ONNX to XML and BML
The method for converting one or more ONNX files to the Beckhoff specific XML or BML format is described below.
Why convert ONNX to XML or BML?
The ONNX format cannot be directly loaded to the target platform by the ML Runtime. Therefore, a conversion step is necessary in the engineering before the ML description file can be transferred to the target system. The creation of an XML file has the advantage that it is openly readable. This allows all information in the XML to be viewed during the engineering phase using a simple XML editor. The BML file is binary and the contents are therefore no longer simply viewable. In addition, a BML file is loaded considerably faster by the ML Runtime, therefore the BML file is recommended for the delivery.
Which TwinCAT-specific information can be entered in the XML or BML file?
Creation of multi-engines
It is possible to load more than one ML model into an instance of the FB_MllPrediction. Switching between the models, referred to in the following as engines in this context, is possible without latency. This way, for example, a set of models can be trained for different work areas of the machine and the correct engine can be addressed without latency during the inference phase.
The condition for merging several models is that the model structure – the <Configuration> section in Beckhoff XML – is identical for all models. For example, this means that MLPs can only be merged if their structure (number of layers, number of neurons per layer and activation functions) is the same. Only the model parameters, i.e. the weights in the example of the MLPs, may be different.
Cf. the Beckhoff ML XML description: XML Tag Parameters.
During merging, therefore, several AI models with an identical structure but different parameters are combined in a description file. The individual models (= engines) are loaded via a single description file in the ML Runtime. The engine ID that is to be addressed is to be transferred in each case to the Predict method when calling in the PLC. The engine can be addressed via a string using the PredictRef method. A GetEngineIdFromRef method is also available for finding the associated ID from the reference.
Multi-engines should be regarded as an organization unit. Of course, it is also possible to instantiate several instances of a FB_MllPrediction in the PLC and to load a dedicated description file into each FB.
Minimum version of the ML Runtime driver
When converting the description file, two entries are automatically set in the XML or BML file. One is the version of the converting component and the other is a “required version” of the ML Runtime driver. On loading the model file into TwinCAT, the “required version” is checked and a warning is output if the result of the query is false.
Cf. the Beckhoff ML XML description: XML Tag Auxiliary Specifications.
Which application-specific information can be entered in the XML or BML file?
Input and output scalings
The inputs of the AI model are often scaled for the training process. This scaling must then also be performed for the inference. This can either be implemented by hand in the PLC or entered directly as information in the XML or BML file. If the scaling entries are set, the scaling is performed automatically. A scaling and an offset must be specified for the scaling. The following applies:
y = x * Scaling + Offset
If scaled inputs are used for a model, back-scaling of the model output is usually also necessary. Therefore, an output scaling is available in addition to the input scaling.
 | Output transformation for selected models only Whereas an input transformation is possible for all AI models, output transformations can only be used for models of the regression type. |
Cf. the Beckhoff ML XML description: XML Tag Auxiliary Specifications.
Model name, model version, model description, etc.
For the unambiguous identification of a model description file, it is possible to add various descriptions of a model. These can be used as a free string:
- A model version
- A model name
- A model description
- A model author
- Further optional tags
Cf. the Beckhoff ML XML description: XML Tag Auxiliary Specifications.
Free Custom Attributes section
Custom Attributes are optional and may be freely used by the user. The number of attributes and the number of XML tags are not limited. The attributes are typed in the XML/BML so that the entries can be read again in the PLC. The methods GetCustomAttribute_array, GetCustomAttribute_fp64, GetCustomAttribute_int64 and GetCustomAttribute_str are available for this. See also Detailed sample.
Examples of the use of Custom Attributes could be:
- Specification of an internal version or identification number
- Specification of the input range of the individual features
- Description of the inputs and outputs
- …
Cf. the Beckhoff ML XML description: XML Tag CustomAttributes.
How can I convert files and add information?
Different interfaces are offered for the simple conversion and information modeling step in your work process:
- A GUI in the TwinCAT XAE “Machine Learning Model Manager”
- A CLI “mllib_toolbox.exe”
- An API as a Python package “beckhoff.toolbox”
Not every interface offers the actions described above. The CLI is limited to basic applications – mainly conversion. The Python API and the GUI offer the largest functional scope.