Java - IP Connection

This is the API description for the Java bindings of the IP Connection. The IP Connection is established between the Brick Daemon and the corresponding programming language API bindings. You need to create an IP Connection to brickd and add devices, before you can use them.

An overview of products that are controllable over an IP Connection can be found here.

Example

The example code below is public domain.

Download

import com.tinkerforge.IPConnection;

public class Example {
    private static final String host = "localhost";
    private static final int port = 4223;

    // Note: To make the example code cleaner we do not handle exceptions. Exceptions you
    //       might normally want to catch are described in the documentation
    public static void main(String args[]) throws Exception {
        // Create connection and connect to brickd
        IPConnection ipcon = new IPConnection();
        ipcon.connect(host, port);

        // Register enumerate listener and print incoming information
        ipcon.addEnumerateListener(new IPConnection.EnumerateListener() {
            public void enumerate(String uid, String connectedUid, char position,
                                  short[] hardwareVersion, short[] firmwareVersion,
                                  int deviceIdentifier, short enumerationType) {
                System.out.println("UID:               " + uid);
                System.out.println("Enumeration Type:  " + enumerationType);

                if(enumerationType == IPConnection.ENUMERATION_TYPE_DISCONNECTED) {
                    System.out.println("");
                    return;
                }

                System.out.println("Connected UID:     " + connectedUid);
                System.out.println("Position:          " + position);
                System.out.println("Hardware Version:  " + hardwareVersion[0] + "." +
                                                           hardwareVersion[1] + "." +
                                                           hardwareVersion[2]);
                System.out.println("Firmware Version:  " + firmwareVersion[0] + "." +
                                                           firmwareVersion[1] + "." +
                                                           firmwareVersion[2]);
                System.out.println("Device Identifier: " + deviceIdentifier);
                System.out.println("");
            }
        });

        ipcon.enumerate();

        System.console().readLine("Press key to exit\n");
        ipcon.disconnect();
    }
}

API

Basic Functions

public class 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.

public void connect(String host, int port)

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.

public void disconnect()

Disconnects the TCP/IP connection from the Brick Daemon or the WIFI/Ethernet Extension.

public byte getConnectionState()

Can return the following states:

• IPConnection.CONNECTION_STATE_DISCONNECTED (0): No connection is established.
• IPConnection.CONNECTION_STATE_CONNETED (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.

public void setAutoReconnect(boolean 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.

public boolean getAutoReconnect()

Returns true if auto-reconnect is enabled, false otherwise.

public void setTimeout(int timeout)

Sets the timeout in milliseconds for getters and for setters for which the response expected flag is activated.

Default timeout is 2500.

public int getTimeout()

Returns the timeout as set by setTimeout().

public void enumerate()

Broadcasts an enumerate request. All devices will respond with an enumerate callback.

Listener Configuration Functions

public void addListener(Object object)

Registers a listener object.

The available listener classes with inherent methods to be overwritten are described below.

Listeners

Listeners can be registered to be notified about events. The registration is done with “addListener” functions of the IPConnection object.

The parameter is a listener class object, for example:

ipcon.addExampleListener(new IPConnection.ExampleListener() {
    public void property(int value) {
        System.out.println("Value: " + value);
    }
});

The available listener classes with inherent methods to be overwritten are described below. It is possible to add several listeners and to remove them with the corresponding “removeListener” function.

public class IPConnection.EnumerateListener()

This listener can be added with the addEnumerateListener() function. An added listener can be removed with the removeEnumerateListener() function.

public void enumerate(String uid, String connectedUid, char position, short[] hardwareVersion, short[] firmwareVersion, int deviceIdentifier, short enumerationType)

The listener 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 “1”. 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, instead of the name of the device (easier to parse).
• 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 identifiers can be found here.

public class IPConnection.ConnectedListener()

This listener can be added with the addConnectedListener() function. An added listener can be removed with the removeConnectedListener() function.

public void connected(short connectReason)

This listener is called 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.

public class IPConnection.DisconnectedListener()

This listener can be added with the addDisconnectedListener() function. An added listener can be removed with the removeDisconnectedListener() function.

public void disconnected(short disconnectReason)

This listener is called whenever the IP Connection got disconnected from a Brick Daemon or from 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.