Collaboration diagram for ApiBlocks:

API Blocks

Description

The API block group contains elementary blocks used to establish a connection between your client application and a target system. This has to be done before any other mlpi4Simulink block can be called.

mlpi4Simulink is session oriented. This means, that you need to connect to a target before you can use any other mlpi4Simulink blocks. There are just a few blocks like m4SApiGetClientCoreVersion that do not need an online communication to the target.

After successfully connecting to the target using m4SApiConnect you will get a connection identifier which identifies your connection and which can be used for any further mlpi4Simulink blocks. Please have a look at the documentation and examples of the block m4SApiConnect for more information.

More Information

For further information, refer to the mlpiCore documentation: ApiLib

Copyright

m4SApiConnect

API Blocks: Connect to target and get a connection identifier.

Description

This block connects a Simulink model to a MLPI target and generates a connection identifier at the output connection. This identifier can be connected to other mlpi4Simulink blocks to link them to the selected target.

Block Inputs

no inputs

Block Outputs

connection contains the connection identifier that can be linked to the input connection of other mlpi4Simulink blocks. The output is a scalar uint32 value. The default value of this output is 0.

result contains the return value of the block. The output is a scalar int32 value. If the output is negative other outputs are invalid. The default value of this output is 0. For details refer to the section Error Identification and Handling in Fundamentals of MLPI Programming.

Parameters and Dialog Box

ipAddress specifies a string with the internet protocol (IP) address of the MLPI target. The parameter must be a 1xN char array. In addition to the mandatory IP address in dot format the char array may include additional options to configure the connection individually. The maximum number of characters N is M4M_CONST.MEX_IP_ADDRESS_LENGTH_MAX.

Options for parameter IP address

Options for the connection can be entered as a tag-value-list for the parameter IP address. The syntax for this parameter without options is: '192.169.128.10'.

The syntax for the parameter IP address with options is: '192.169.128.10 -guest=anonymous -password=anonymous'

The following options can be used:

suppressThrow=value: Set error reaction of MLPI functions. See Fundamentals of MLPI Programming for more information about the error handling (default: true). value internally is set to true for this block and can not be changed. Using the option -suppressThrow=false will be ignored.

user=value: Login name of user. See Fundamentals of MLPI Programming for more information about user and permission system. value must be a string.

password=value: Password of user. See Fundamentals of MLPI Programming for more information about user and permission system. value must be a string.

address=value: IP or URL path of connection. value must be a string.

timeout_connect=value: Timeout used for connecting in milliseconds. value must be a string of a positive integer number.

timeout_send=value: Timeout of MLPI client used for sending data to server (target) in milliseconds (default: 0). value must be a string of a positive integer number.

timeout_receive=value: Timeout of MLPI client used for receiving data from server (target) in milliseconds (default: 0). value must be a string of a positive integer number.

auto_reconnect=value: If set to 1 or true, then the MLPI will try to reconnect with each new call of any MLPI function after connection was lost. For connecting, the same timeout settings are used as given for the first connect (default: false). value must be true or false.

keepalive_mode_server=value: If set to 1 (default, if not set), then the MLPI server will send a MLPI keepalive telegram after keepalive timeout, if the client does not send any request before. If set to 0, then MLPI server will not send any MLPI keepalive telegrams. value must be 0 or 1.

keepalive_timeout_server=value: Timeout used for sending MLPI keepalive telegram in milliseconds (default: 30000). value must be a string of a positive integer number.

keepalive_probes_server=value: Number of probes for sending MLPI keepalive telegram (default: 10). value must be a string of a positive integer number.

timeout_send_server=value: Timeout of MLPI server used for sending data to client in milliseconds (default: 60000). value must be a string of a positive integer number.

require_hash=value: If true, then only logins to servers which support hashed password logins are allowed. Server version has to be greater than 1.1.1.0 (default: false). Note: It's highly recommended to use this option if your control firmware is equal or newer then 13V06. value must be true or false.

protection=value: Select your protection level using values of MlpiApiProtection to protect your connection against closing by an other connection with the assistance of call of m4MApiCloseConnectionByUid, m4MApiCloseConnectionsByUser or m4MApiCloseConnectionsByUri.

Note: This option can be also used as an attribute of an account of the user management. See Fundamentals of MLPI Programming for more information about user and permission system. value can be:

value = 0: The connection is not protected and can be closed by an other connection (default).
value = 1: The connection is protected against closing by an other connection if the connection watchdog is active (enabled and not fired).
value = 2: The connection is protected against closing by an other connection completely.

A timeout value of 0 means that the timeout value is to be chosen automatically by the operating system. If no timeout is specified here, the global default value as set by the function m4MApiSetDefaultTimeout is used. This means that any option given here will override the value as set by m4MApiSetDefaultTimeout. In most cases it is not recommended to override the timeout values. Especially the send and receive timeouts should stay at their default values of 0.

If no request telegram of the MLPI client will be received by the MLPI server, by default the MLPI server will send on each keepalive_timeout_server milliseconds timeout an empty MLPI keepalive telegram. This is done to check if the client machine is still reachable or if the connection can be closed and freed again. The server will repeat this keepalive telegram for keepalive_probes_server times. After this time (keepalive_timeout_server * keepalive_probes_server) the MLPI server waits timeout_send_server milliseconds until the connection is closed finally.

Overall timeout until close of connection: t(close) = ( t(keepalive_timeout_server) * n(keepalive_probes_server) ) + t(timeout_send_server)

Note: The server cannot detect whether the client application is still running. It can only be checked if the telegrams reached the client machine and the socket is still available. For setup a right connection it can also be helpful to implement the function m4MApiNotifyAlive.

Example: '192.168.0.42:5300 -timeout_connect=2000 -timeout_send=5000 -timeout_receive=5000 -user=guest -password=guest -auto_reconnect=true'

If the user enters an invalid option or an option with a spelling error the function will not return an error.

Characteristics

Direct Feedthrough	Yes
Sample Time	Fixed Step

Example Model

Here you will find instructions to use the examples.

The following example is available in the folder ./mlpi/mlpi4Simulink/blocks:

m4SApiConnect_Sample.mdl

m4SApiDelay

API Block: Set communication delay on the server side.

Description

This block applies a delay of communication on the server side for the specified number of of milliseconds. It can be used during development or debugging of your application to simulate high traffic on the network. This way you can test the behaviour of your client application when MLPI communication slows down. The delay has no impact on the performance of the device.

Block Inputs

connection defines the connection that will be used. The input must be a scalar uint32 value provided by m4SApiConnect.

result defines if the block will be executed. The input must be a scalar int32 value. The block will not be executed if this value is negative. For negative values the input result is directly fed through to the output result.

delay defines the delay in milliseconds. The input must be a scalar uint32 value.

Block Outputs

connection contains the connection identifier. The input port connection is fed through to this output. The default value of this port is 0.

result contains the return value of the block. The output is a scalar int32 value. If the output is negative other outputs are invalid. The default value of this output is 0. For details refer to the section Error Identification and Handling in Fundamentals of MLPI Programming.

Parameters and Dialog Box

Sample time (-1 for inherited) specifies the time interval between samples. To inherit the sample time, set this parameter to -1. This block supports discrete sample time, but not continuous sample time.

Characteristics

Direct Feedthrough	Yes
Sample Time	Fixed Step

Example Model

Here you will find instructions to use the examples.

The following example is available in the folder ./mlpi/mlpi4Simulink/blocks:

m4SApiDelay_Sample.mdl

m4SApiIsConnected

API Block: Returns current state of MLPI connection.

Description

This block return the state of the connection. If false is returned, the connection is either not yet established or closed because of a communication error. In all cases a reconnect using m4SApiConnect has to be made to call further MLPI functions. If a connection is lost for unknown reasons, try increasing the connection timeout using m4SApiSetDefaultTimeout. The block m4SApiConnect allows also to set an auto-reconnect option.

Block Inputs

connection defines the connection that will be used. The input must be a scalar uint32 value provided by m4SApiConnect.

result defines if the block will be executed. The input must be a scalar int32 value. The block will not be executed if this value is negative. For negative values the input result is directly fed through to the output result.

Block Outputs

connection contains the connection identifier. The input port connection is fed through to this output. The default value of this port is 0.

result contains the return value of the block. The output is a scalar int32 value. If the output is negative other outputs are invalid. The default value of this output is 0. For details refer to the section Error Identification and Handling in Fundamentals of MLPI Programming.

isConnected contains the connection status. The output is a scalar boolean value. The default value of this port is false.

Parameters and Dialog Box

Sample time (-1 for inherited) specifies the time interval between samples. To inherit the sample time, set this parameter to -1. This block supports discrete sample time, but not continuous sample time.

Characteristics

Direct Feedthrough	Yes
Sample Time	Fixed Step

Example Model

Here you will find instructions to use the examples.

The following example is available in the folder ./mlpi/mlpi4Simulink/blocks:

m4SApiIsConnected_Sample.mdl

m4SApiTestConnection

API Block: Performs benchmark on MLPI communication mechanism.

Description

Use this block to measure the duration of a MLPI function call with the given payload in bytes. The resulting timing values are the durations which are necessary to marshal the payload, send the payload to the MLPI server, unmarshal it on the MLPI server, perform the remote procedure call, marshal the results, send them back to the MLPI client unmarshal them again and return them to the client thread program. This is the basic cost needed for nearly every MLPI call.

Block Inputs

connection defines the connection that will be used. The input must be a scalar uint32 value provided by m4SApiConnect.

result defines if the block will be executed. The input must be a scalar int32 value. The block will not be executed if this value is negative. For negative values the input result is directly fed through to the output result.

Block Outputs

connection contains the connection identifier. The input port connection is fed through to this output. The default value of this port is 0.

result contains the return value of the block. The output is a scalar int32 value. If the output is negative other outputs are invalid. The default value of this output is 0. For details refer to the section Error Identification and Handling in Fundamentals of MLPI Programming.

minimum contains the minimum time duration of all measurements in microseconds. The output is a scalar double value. The default value of this port is 0.

maximum contains the maximum time duration of all measurements in microseconds. The output is a scalar double value. The default value of this port is 0.

average contains the average time duration of all measurements in microseconds. The output is a scalar double value. The default value of this port is 0.

variance contains the variance of all measurements in square microseconds. The output is a scalar double value. The default value of this port is 0.

standardDeviation contains the standard deviation of all measurements in microseconds. The output is a scalar double value. The default value of this port is 0.

Parameters and Dialog Box

Sample time (-1 for inherited) specifies the time interval between samples. To inherit the sample time, set this parameter to -1. This block supports discrete sample time, but not continuous sample time.

Characteristics

Direct Feedthrough	Yes
Sample Time	Fixed Step

Example Model

Here you will find instructions to use the examples.

The following example is available in the folder ./mlpi/mlpi4Simulink/blocks:

m4SApiTestConnection_Sample.mdl

API Blocks

Description

More Information

m4SApiConnect

m4SApiConnect

Description

Block Inputs

Block Outputs

Parameters and Dialog Box

Characteristics

Example Model

See also

m4SApiDelay

m4SApiDelay

Description

Block Inputs

Block Outputs

Parameters and Dialog Box

Characteristics

Example Model

See also

m4SApiIsConnected

m4SApiIsConnected

Description

Block Inputs

Block Outputs

Parameters and Dialog Box

Characteristics

Example Model

See also

m4SApiTestConnection

m4SApiTestConnection

Description

Block Inputs

Block Outputs

Parameters and Dialog Box

Characteristics

Example Model

See also