4. MAL Mappings¶
User’s Manual
Revision: |
2.4 |
|---|---|
Status: |
Released |
Repository: |
|
Project: |
ELT CII |
Folder: |
/trunk/deliverables/phase3 |
Document ID: |
CSL-MAN-18-155953 |
File: |
MAN-MAL_mappings.docx |
Owner: |
Matej Šekoranja, Cosylab Sweden |
Last modification: |
Sep 7, 2021 |
Created: |
July 21, 2018 |
Prepared by |
Reviewed by |
Approved by |
|---|---|---|
Matej Šekoranja, CSL SWE |
Aljaž Podboršek Gregor Čuk |
Gregor Čuk |
Revision |
Date |
Changed/rev iewed |
Section(s) |
Modificatio n |
|---|---|---|---|---|
0.1 |
2018-07-21 |
msekoranja |
All |
Created. |
0.9 |
2018-08-03 |
msekoranja |
3 |
Added Python sections, properties. |
1.0 |
2018-08-10 |
msekoranja |
All |
Minor updates, release. |
2.0 |
2019-02-02 |
msekoranja |
All |
Updated property names, removed duplicated parts from MAL API manual and Transfer document. |
2.1 |
2019-04-16 |
msekoranja |
3 References |
Updated OPC UA C++ properties. References update |
2.2 |
2020-03-24 |
msekoranja |
3 |
Added ZPB C++/Java send queue size property. |
2.3 |
2021-09-07 |
dkumar |
3 |
Added OPCUA logging description for open62541 |
2.4 |
2021-09-24 |
dkumar |
3 |
Added ZPB C++/Java disable type check property. |
Confidentiality
This document is classified as a confidential document. As such, it or parts thereof must not be made accessible to anyone not listed in the Audience section, neither in electronic nor in any other form.
Scope
This document is a Middleware Abstraction Layer user manual document for the ELT Core Integration Infrastructure Software project.
Audience
Users and Maintainers of the ELT Core Integration Infrastructure Software.
Glossary of Terms
API |
Application Programmers Interface |
|---|---|
CII |
Core Integration Infrastructure |
DDS |
Data Distribution Service |
MAL |
Middleware Abstraction Layer |
URI |
Uniform Resource Identifier |
ZPB |
ZeroMQ and Protocol Buffers |
OPC UA |
OPC (Object Linking and Embedding for Process Control) Unified Architecture |
References
Cosylab, MAL Design document, CSL-DOC-17-147260 v1.5
Cosylab, ELT CII MAL Transfer document, CSL-DOC-18-168015, version 1.8
Cosylab, Python MAL Bindings Design document, CSL-DOC-18-152412, version 1.3
Cosylab, MAL API User Manual document, CSL-MAN-17-150198, version 2.1
4.1. Overview¶
This document describes configuration options for the following MAL mappings: DDS, ZPB and OPC UA. All the details on the MAL API and its functionality are covered by the MAL design document [1] and MAL User Manual [4].
4.2. Installation¶
See MAL Mappings Transfer document [2] on how to install MAL mappings.
4.3. C++¶
4.3.1. DDS¶
The following table enumerates mapping specific properties:
Name |
Type |
Description |
Used by |
Default |
|---|---|---|---|---|
dds.domain |
integer |
DDS domain ID. |
MAL |
0 |
dds.qos.profile.library |
string |
DDS QoS profile library. |
MAL |
(none) |
dds.qos.profile.name |
string |
DDS QoS profile name. |
MAL |
(none) |
dds.qos.profile.name. participant |
string |
DDS QoS profile name for participant. |
MAL |
(none) |
dds.qos.profile.name. topic |
string |
DDS QoS profile name for topic. |
MAL |
(none) |
dds.qos.profile.name. writer |
string |
DDS QoS profile name for writer. |
MAL |
(none) |
dds.qos.profile.name. reader |
string |
DDS QoS profile name for reader. |
MAL |
(none) |
dds.qos.profile.name. subscriber |
string |
DDS QoS profile name for subscriber. |
MAL |
(none) |
dds.qos.profile.name. publisher |
string |
DDS QoS profile name for publisher. |
MAL |
(none) |
dds.wait_for_ack. timeout_ms |
integer |
DDS wait for ack. before tearing down writer and publisher. |
MAL |
5000ms |
Table 1 C++ DDS MAL mapping specific properties
Additional info for DDS QoS profile name selection:
Custom QoS profiles are enabled only when a user sets the “dds.qos.profile.library” mal property pointing to the file containing the QoS profiles. If the user sets only the “dds.qos.profile.name” mal property, then the same QoS profile name will be used for the creation of the following DDS entities: participant, topic, writer, publisher, reader, and subscriber. User has the option to override the default QoS profile name when creating a participant (“dds.qos.profile.name.participant”), a topic(“dds.qos.profile.name.topic”), a writer (“dds.qos.profile.name.writer”), a reader(“dds.qos.profile.name.reader”), a subscriber(“dds.qos.profile.name.subscriber”), and a publisher(“dds.qos.profile.name.publisher”). If the user does not override the profile name for a specific DDS entity, the default profile name is used.
Additional info for DDS Wait for acknowledgment timeout property:
If this property is not provided, a default timeout of 5000 ms shall be assumed as the timeout value. If the timeout value is larger than 0 then writer->wait_for_acknowledgements() and publisher->wait_for_acknowledgements() shall be called before tearing down the writers and the publisher. This means that developers can still suppress calling wait_for_acknowledgements if they specify the new property with a timeout value of 0, otherwise the call to wait_for_acks will always happen from now on.
4.3.2. ZPB¶
The following table enumerates mapping specific properties:
Name |
Type |
Description |
Used by |
Default |
|---|---|---|---|---|
zpb.ps.slow JoinerDelay Ms |
integer |
Slow joiner delay. Time in millisecond s to wait after publisher has been instantiate d. This mitigates slow joiner delay problem but does NOT guarantee that first N messages will not be lost. |
Publisher |
0 (no delay) |
zpb.schedul edExecutorT hreads |
integer |
Number of thread pool threads to handle internal timer based tasks (e.g. QoS deadline timeouts). |
MAL |
3 |
zpb.rr.call TimeoutSec (C++ only) |
integer |
Client asynchronou s method call timeout in seconds. |
Client |
0 (no timeout) |
zpb.ps.zmq. sndhwm |
integer |
Publisher send queue size. Use to limit memory usage when dealing with large messages. 0 stands for unlimited. |
Publisher |
1000 (ZMQ timeout) |
zpb.ps. disableType HashCheck |
boolean |
Disable subscriber’s check for type hash correctness |
Subscribers |
false |
zpb.rr. zmqReconnect IvlMs |
integer |
Set reconnection interval in ms |
Client |
100 ms |
zpb.rr. zmqReconnect IvlMaxMs |
integer |
Set maximum reconnection interval in ms |
Client |
0 ms |
Table 2 C++ ZPB MAL mapping specific properties
4.3.3. OPC UA¶
The following table enumerates mapping specific properties:
Name |
Type |
Description |
Used by |
Default |
|---|---|---|---|---|
opc.asyncLo opExecution PeriodMs |
integer |
The sleep period of the asynchronou s process loop. |
MAL |
50 |
opc.asyncCa llSubmitTim eoutMs |
integer |
Timeout for submitting an asynchronou s call. |
Client |
1000 |
opc.asyncCa llRetryPeri odMs |
integer |
The retry period for failed asynchronou s calls. |
MAL |
250 |
opc.log4cpl us.filename |
string |
log4cplus file name. |
MAL |
undefined |
opc.ps.poll ingPeriodMs |
integer |
Multi-node subscriber polling period in millisecond s. |
Subscriber, MrvSubscrib er |
1000 |
opc.ps.outs tandingPubl ishRequests |
integer |
Number of outstanding publish requests. |
Publisher, Subscriber, MrvSubscrib er |
10 |
opc.ps. usePollSubsc riber |
boolean |
Force subscriber to poll for value updates instead of a monitor subscription |
Subscriber, MrvSubscrib er |
false |
opc.ps.reque stedPublishi ngIntervalMs |
integer |
Server-side sampling interval of a subscripti on (i.e. an interval to sample/poll/ monitor an item) |
Subscriber, MrvSubscrib er |
5000 |
Table 3 C++ OPC UA MAL mapping specific properties
Additional info for opcua logging:
Open62541 library (client part) will log events via log4cplus malOpcuaOpen62541 logger. If a user does not provide a log4cplus configuration with the malOpcuaOpen62541 logger or a root logger, no log output will be generated from the open62541 library. Bellow is an example configuration pertaining to the open62541 library logging: malOpcuaOpen62541 logger configured for only ERROR and FATAL logging with additivity set to false (events won’t be propagated to the root logger). With this configuration all other mal loggers will log with TRACE level. User needs to provide the location of the log4cplus configuration for mal-opcua using mal property opc.log4cplus.filename (see table 3).
4.4. Java¶
4.4.1. DDS¶
For mapping specific properties refer to Table 1 C++ DDS MAL mapping specific properties.
4.4.2. ZPB¶
For mapping specific properties refer to Table 2 C++ ZPB MAL mapping specific properties.
4.4.3. OPC UA¶
The following table enumerates mapping specific properties:
Name |
Type |
Description |
Used by |
Default |
|---|---|---|---|---|
opc.schedul edExecutorT hreads |
integer |
Number of thread pool threads to handle internal timer based tasks (e.g. QoS deadline timeouts). |
MAL |
3 |
opc.ps.poll ingPeriodMs |
integer |
Multi-node subscriber polling period in millisecond s. |
Subscriber, MrvSubscrib er |
1000 |
opc.ps.reqP ubRateMs |
integer |
OPC UA stack subscriptio n requested publishing interval in millisecond s. |
MAL |
1000 |
opc.ps.queu eSize |
integer |
OPC UA stack subscriptio n queue size. |
MAL |
3 |
Table 4 Java OPC UA MAL mapping specific properties
4.5. Python¶
Python MAL API builds on MAL C++ API foundation. There is no native Python MAL mapping implementation, everything is provided via language mapping to C++.
Python applications use Python MAL API only and are not aware of the actual MAL implementation details.
Refer to Python Bindings Design [3] and MAL API User Manual [4] documents for detailed information.