m4MApiConnect
API-Function: Connect to control and get a connection handle.
Description
This function connects MATLAB to a MLPI device and generates a MlpiConnection object which represents this connection. This object is provided to other MLPI functions and serves as a connection handle.
Note: Do not call m4MApiConnect with an invalid handle. This might cause unexpected behaviour.
Syntax
[connection] = m4MApiConnect(ipAddress)
[connection, result] = m4MApiConnect(ipAddress)
Input Arguments
ipAddress specifies a string with the internet protocol (IP) address. The argument 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.
Options for Input Argument ipAddress
Options for the connection can be entered as a tag-value-list in the char array ipAddress. The syntax for argument ipAddress without options is:
ipAddress = '192.169.128.10'
The syntax for argument ipAddress with options is:
ipAddress = '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 must be true or false.
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
m4MApiConnect('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.
Output Arguments
connection contains the connection that will be used for further MLPI function calls. The argument is an object of class MlpiConnection.
result contains the return value of the MLPI function. The argument is scalar and of type int32. Negative values indicate a failed function call. If the function call fails, other output arguments will be set to NaN. For details refer to the section Error Identification and Handling in Fundamentals of MLPI Programming.
Example Files
Here you will find instructions to use the examples.
The following example is available in the folder ./mlpi/mlpi4MATLAB/bin:
See also
Reference to mlpiCore
This function maps to the mlpiCore function: mlpiApiConnect
Copyright
Legal notice and version: © 2017 Bosch Rexroth Corporation http://www.boschrexroth.com DC-AE/EAS1 (MGo) Library version: 1.26.2.0.0