LabVIEW - IP Connection
This is the description of the LabVIEW API bindings for the IP Connection.
The IP Connection manages the communication between the API bindings and the
Brick Daemon or a WIFI/Ethernet Extension. Before Bricks and
Bricklets can be controlled using their API an
IP Connection has to be created and its TCP/IP connection has to be established.
An installation guide for the LabVIEW API bindings is part of their
general description.
API
The namespace for the IPConnection is Tinkerforge.*.
Basic Functions
-
IPConnection() → ipcon
Output: |
- ipcon -- .NET Refnum (IPConnection)
|
Creates an IP Connection object that can be used to enumerate the available
devices. It is also required for the constructor of Bricks and Bricklets.
-
IPConnection.Connect(host, port)
Input: |
- host -- String
- port -- Int32
|
Creates a TCP/IP connection to the given host and port. The host and port
can refer to a Brick Daemon or to a WIFI/Ethernet Extension.
Devices can only be controlled when the connection was established
successfully.
Blocks until the connection is established and throws an exception if there
is no Brick Daemon or WIFI/Ethernet Extension listening at the given host
and port.
-
IPConnection.Disconnect()
Disconnects the TCP/IP connection from the Brick Daemon or the WIFI/Ethernet
Extension.
-
IPConnection.Authenticate(secret)
-
Performs an authentication handshake with the connected Brick Daemon or
WIFI/Ethernet Extension.
If the handshake succeeds the connection switches from non-authenticated to
authenticated state and communication can continue as normal. If the handshake
fails then the connection gets closed. Authentication can fail if the wrong
secret was used or if authentication is not enabled at all on the Brick Daemon
or the WIFI/Ethernet Extension.
See the authentication tutorial for more
information.
-
IPConnection.GetConnectionState() → connectionState
-
Can return the following states:
- IPConnection.CONNECTION_STATE_DISCONNECTED (0): No connection is established.
- IPConnection.CONNECTION_STATE_CONNECTED (1): A connection to the Brick
Daemon or the WIFI/Ethernet Extension is established.
- IPConnection.CONNECTION_STATE_PENDING (2): IP Connection is currently
trying to connect.
-
IPConnection.SetAutoReconnect(autoReconnect)
-
Enables or disables auto-reconnect. If auto-reconnect is enabled,
the IP Connection will try to reconnect to the previously given
host and port, if the connection is lost.
Default value is true.
-
IPConnection.GetAutoReconnect() → autoReconnect
-
Returns true if auto-reconnect is enabled, false otherwise.
-
IPConnection.SetTimeout(timeout)
-
Sets the timeout in milliseconds for getters and for setters for which the
response expected flag is activated.
Default timeout is 2500.
-
IPConnection.GetTimeout() → timeout
-
Returns the timeout as set by SetTimeout().
-
IPConnection.Enumerate()
Broadcasts an enumerate request. All devices will respond with an enumerate
callback.
-
IPConnection.Wait()
Stops the current thread until Unwait()
is called.
This is useful if you rely solely on callbacks for events, if you want to
wait for a specific callback or if the IP Connection was created in a thread.
Wait and Unwait act in the same way as Acquire and Release of a
semaphore.
-
IPConnection.Unwait()
Unwaits the thread previously stopped by Wait()
Wait and Unwait act in the same way as Acquire and Release of a
semaphore.
Callbacks
Callbacks can be registered to be notified about events. The registration is
done by appending your callback handler to the corresponding event.
The available events are described below.
-
event IPConnection.EnumerateCallback(sender, uid, connectedUid, position, hardwareVersion, firmwareVersion, deviceIdentifier, enumerationType)
Input: |
- sender -- .NET Refnum (IPConnection)
- uid -- String
- connectedUid -- String
- position -- Char
- hardwareVersion -- Byte[3]
- firmwareVersion -- Byte[3]
- deviceIdentifier -- Int32
- enumerationType -- Int16
|
The event receives seven parameters:
- uid: The UID of the device.
- connectedUid: UID where the device is connected to. For a Bricklet this
will be a UID of the Brick where it is connected to. For a Brick it will be
the UID of the bottom Master Brick in the stack. For the bottom Master Brick
in a stack this will be "0". With this information it is possible to
reconstruct the complete network topology.
- position: For Bricks: '0' - '8' (position in stack). For Bricklets:
'a' - 'd' (position on Brick).
- hardwareVersion: Major, minor and release number for hardware version.
- firmwareVersion: Major, minor and release number for firmware version.
- deviceIdentifier: A number that represents the device.
- enumerationType: Type of enumeration.
Possible enumeration types are:
- IPConnection.ENUMERATION_TYPE_AVAILABLE (0): Device is available
(enumeration triggered by user).
- IPConnection.ENUMERATION_TYPE_CONNECTED (1): Device is newly connected
(automatically send by Brick after establishing a communication connection).
This indicates that the device has potentially lost its previous
configuration and needs to be reconfigured.
- IPConnection.ENUMERATION_TYPE_DISCONNECTED (2): Device is disconnected
(only possible for USB connection). In this case only uid and
enumerationType are valid.
It should be possible to implement plug-and-play functionality with this
(as is done in Brick Viewer).
The device identifier numbers can be found here.
There are also constants for these numbers named following this pattern:
<device-class>.DEVICE_IDENTIFIER
For example: BrickMaster.DEVICE_IDENTIFIER
or BrickletAmbientLight.DEVICE_IDENTIFIER.
-
event IPConnection.Connected(sender, connectReason)
Input: |
- sender -- .NET Refnum (IPConnection)
- connectReason -- Int16
|
This event is triggered whenever the IP Connection got connected to a
Brick Daemon or to a WIFI/Ethernet Extension, possible reasons are:
- IPConnection.CONNECT_REASON_REQUEST (0): Connection established after
request from user.
- IPConnection.CONNECT_REASON_AUTO_RECONNECT (1): Connection after
auto-reconnect.
-
event IPConnection.Disconnected(sender, disconnectReason)
Input: |
- sender -- .NET Refnum (IPConnection)
- disconnectReason -- Int16
|
This event is triggered whenever the IP Connection got disconnected from a
Brick Daemon or to a WIFI/Ethernet Extension, possible reasons are:
- IPConnection.DISCONNECT_REASON_REQUEST (0): Disconnect was requested by user.
- IPConnection.DISCONNECT_REASON_ERROR (1): Disconnect because of an
unresolvable error.
- IPConnection.DISCONNECT_REASON_SHUTDOWN (2): Disconnect initiated by Brick
Daemon or WIFI/Ethernet Extension.