This is the description of the Python 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 Python API bindings is part of their general description.
The example code below is Public Domain (CC0 1.0).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38
#!/usr/bin/env python # -*- coding: utf-8 -*- HOST = "localhost" PORT = 4223 from tinkerforge.ip_connection import IPConnection # Print incoming enumeration def cb_enumerate(uid, connected_uid, position, hardware_version, firmware_version, device_identifier, enumeration_type): print("UID: " + uid) print("Enumeration Type: " + str(enumeration_type)) if enumeration_type == IPConnection.ENUMERATION_TYPE_DISCONNECTED: print("") return print("Connected UID: " + connected_uid) print("Position: " + position) print("Hardware Version: " + str(hardware_version)) print("Firmware Version: " + str(firmware_version)) print("Device Identifier: " + str(device_identifier)) print("") if __name__ == "__main__": # Create connection and connect to brickd ipcon = IPConnection() ipcon.connect(HOST, PORT) # Register Enumerate Callback ipcon.register_callback(IPConnection.CALLBACK_ENUMERATE, cb_enumerate) # Trigger Enumerate ipcon.enumerate() input("Press key to exit\n") # Use raw_input() in Python 2 ipcon.disconnect()
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54
#!/usr/bin/env python # -*- coding: utf-8 -*- HOST = "localhost" PORT = 4223 SECRET = "My Authentication Secret!" from tinkerforge.ip_connection import IPConnection # Authenticate each time the connection got (re-)established def cb_connected(connect_reason): if connect_reason == IPConnection.CONNECT_REASON_REQUEST: print("Connected by request") elif connect_reason == IPConnection.CONNECT_REASON_AUTO_RECONNECT: print("Auto-Reconnect") # Authenticate first... try: ipcon.authenticate(SECRET) print("Authentication succeeded") except: print("Could not authenticate") return # ...reenable auto reconnect mechanism, as described below... ipcon.set_auto_reconnect(True) # ...then trigger enumerate ipcon.enumerate() # Print incoming enumeration def cb_enumerate(uid, connected_uid, position, hardware_version, firmware_version, device_identifier, enumeration_type): print("UID: " + uid + ", Enumeration Type: " + str(enumeration_type)) if __name__ == "__main__": # Create IPConnection ipcon = IPConnection() # Disable auto reconnect mechanism, in case we have the wrong secret. # If the authentication is successful, reenable it. ipcon.set_auto_reconnect(False) # Register Connected Callback ipcon.register_callback(IPConnection.CALLBACK_CONNECTED, cb_connected) # Register Enumerate Callback ipcon.register_callback(IPConnection.CALLBACK_ENUMERATE, cb_enumerate) # Connect to brickd ipcon.connect(HOST, PORT) input("Press key to exit\n") # Use raw_input() in Python 2 ipcon.disconnect()
Generally, every method of the Python bindings can throw an
tinkerforge.ip_connection.Error exception that has a
value and a
value can have different values:
All methods listed below are thread-safe.
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.
Creates a TCP/IP connection to the given
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.
Disconnects the TCP/IP connection from the Brick Daemon or the WIFI/Ethernet Extension.
|Parameters:||secret -- str|
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.
New in version 2.1.0.
Can return the following states:
|Parameters:||auto_reconnect -- bool|
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 currently existing connection is lost.
Therefore, auto-reconnect only does something after a successful
Default value is True.
Returns True if auto-reconnect is enabled, False otherwise.
|Parameters:||timeout -- float|
Sets the timeout in seconds for getters and for setters for which the response expected flag is activated.
Default timeout is 2.5.
Broadcasts an enumerate request. All devices will respond with an enumerate callback.
Stops the current thread until
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.
unwait act in the same way as
release of a
Registers the given
function with the given
The available callback IDs with corresponding function signatures are described below.
Callbacks can be registered to be notified about events. The registration is
done with the
function. The first parameter is the callback ID and the second
parameter the callback function:
def my_callback(param): print(param) ipcon.register_callback(IPConnection.CALLBACK_EXAMPLE, my_callback)
The available constants with inherent number and type of parameters are described below.
The callback has seven parameters:
uid: The UID of the device.
connected_uid: UID where the device is connected to. For a Bricklet this is the UID of the Brick or Bricklet it is connected to. For a Brick it is the UID of the bottommost Brick in the stack. For the bottommost Brick in a stack it is "0". With this information it is possible to reconstruct the complete network topology.
position: For Bricks: '0' - '8' (position in stack). For Bricklets: 'a' - 'h' (position on Brick) or 'i' (position of the Raspberry Pi (Zero) HAT) or 'z' (Bricklet on Isolator Bricklet).
hardware_version: Major, minor and release number for hardware version.
firmware_version: Major, minor and release number for firmware version.
device_identifier: A number that represents the device.
enumeration_type: Type of enumeration.
Possible enumeration types are:
enumerate()). This enumeration type can occur multiple times for the same device.
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:
|Parameters:||connect_reason -- int|
This callback is called whenever the IP Connection got connected to a Brick Daemon or to a WIFI/Ethernet Extension, possible reasons are:
|Parameters:||disconnect_reason -- int|
This callback is called whenever the IP Connection got disconnected from a Brick Daemon or from a WIFI/Ethernet Extension, possible reasons are: