C/C++ - IP Connection¶

Enumerate¶

Download (example_enumerate.c)

 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
55
56
57
58
59

#include <stdio.h>

#include "ip_connection.h"

#define HOST "localhost"
#define PORT 4223

// Print incoming enumeration information
void cb_enumerate(const char *uid, const char *connected_uid,
                  char position, uint8_t hardware_version[3],
                  uint8_t firmware_version[3], uint16_t device_identifier,
                  uint8_t enumeration_type, void *user_data) {
    (void)user_data;

    printf("UID:               %s\n", uid);
    printf("Enumeration Type:  %d\n", enumeration_type);

    if(enumeration_type == IPCON_ENUMERATION_TYPE_DISCONNECTED) {
        printf("\n");
        return;
    }

    printf("Connected UID:     %s\n", connected_uid);
    printf("Position:          %c\n", position);
    printf("Hardware Version:  %d.%d.%d\n", hardware_version[0],
                                            hardware_version[1],
                                            hardware_version[2]);
    printf("Firmware Version:  %d.%d.%d\n", firmware_version[0],
                                            firmware_version[1],
                                            firmware_version[2]);
    printf("Device Identifier: %d\n", device_identifier);
    printf("\n");
}

int main(void) {
    // Create IP Connection
    IPConnection ipcon;
    ipcon_create(&ipcon);

    // Connect to brickd
    if(ipcon_connect(&ipcon, HOST, PORT) < 0) {
        fprintf(stderr, "Could not connect to brickd\n");
        return 1;
    }

    // Register enumeration callback to "cb_enumerate"
    ipcon_register_callback(&ipcon,
                            IPCON_CALLBACK_ENUMERATE,
                            (void (*)(void))cb_enumerate,
                            NULL);

    // Trigger enumerate
    ipcon_enumerate(&ipcon);

    printf("Press key to exit\n");
    getchar();
    ipcon_destroy(&ipcon); // Calls ipcon_disconnect internally
    return 0;
}

Authenticate¶

Download (example_authenticate.c)

 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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

#include <stdio.h>

#include "ip_connection.h"

#define HOST "localhost"
#define PORT 4223
#define SECRET "My Authentication Secret!"

// Authenticate each time the connection got (re-)established
void cb_connected(uint8_t connect_reason, void *user_data) {
    IPConnection *ipcon = (IPConnection *)user_data;

    switch(connect_reason) {
    case IPCON_CONNECT_REASON_REQUEST:        printf("Connected by request\n"); break;
    case IPCON_CONNECT_REASON_AUTO_RECONNECT: printf("Auto-Reconnected\n"); break;
    }

    // Authenticate first...
    if (ipcon_authenticate(ipcon, SECRET) < 0) {
        fprintf(stderr, "Could not authenticate\n");
        return;
    } else {
        printf("Authentication succeeded\n");
    }

    // ...reenable auto reconnect mechanism, as described below...
    ipcon_set_auto_reconnect(ipcon, true);

    // ...then trigger enumerate
    ipcon_enumerate(ipcon);
}

// Print incoming enumeration information
void cb_enumerate(const char *uid, const char *connected_uid,
                  char position, uint8_t hardware_version[3],
                  uint8_t firmware_version[3], uint16_t device_identifier,
                  uint8_t enumeration_type, void *user_data) {
    // avoid unused parameter warnings
    (void)user_data; (void)connected_uid; (void)position;
    (void)hardware_version; (void)firmware_version; (void)device_identifier;

    printf("UID: %s, Enumeration Type: %d\n", uid, enumeration_type);
}

int main(void) {
    // Create IP Connection
    IPConnection ipcon;
    ipcon_create(&ipcon);

    // Disable auto reconnect mechanism, in case we have the wrong secret.
    // If the authentication is successful, reenable it.
    ipcon_set_auto_reconnect(&ipcon, false);

    // Register connected callback to "cb_connected"
    ipcon_register_callback(&ipcon,
                            IPCON_CALLBACK_CONNECTED,
                            (void (*)(void))cb_connected,
                            &ipcon);

    // Register enumeration callback to "cb_enumerate"
    ipcon_register_callback(&ipcon,
                            IPCON_CALLBACK_ENUMERATE,
                            (void (*)(void))cb_enumerate,
                            NULL);

    // Connect to brickd
    if(ipcon_connect(&ipcon, HOST, PORT) < 0) {
        fprintf(stderr, "Could not connect to brickd\n");
        return 1;
    }

    printf("Press key to exit\n");
    getchar();
    ipcon_destroy(&ipcon); // Calls ipcon_disconnect internally
    return 0;
}

Basic Functions¶

void ipcon_create(IPConnection *ipcon)¶

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.

void ipcon_destroy(IPConnection *ipcon)¶

Destroys the IP Connection object. Calls ipcon_disconnect() internally. The connection to the Brick Daemon gets closed and the threads of the IP Connection are terminated.

int ipcon_connect(IPConnection *ipcon, const char *host, uint16_t 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 returns an error code if there is no Brick Daemon or WIFI/Ethernet Extension listening at the given host and port.

int ipcon_disconnect(IPConnection *ipcon)¶

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

int ipcon_authenticate(IPConnection *ipcon, const char *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.

New in version 2.1.0.

int ipcon_get_connection_state(IPConnection *ipcon)¶

Can return the following states:

• IPCON_CONNECTION_STATE_DISCONNECTED = 0: No connection is established.
• IPCON_CONNECTION_STATE_CONNECTED = 1: A connection to the Brick Daemon or the WIFI/Ethernet Extension is established.
• IPCON_CONNECTION_STATE_PENDING = 2: IP Connection is currently trying to connect.

void ipcon_set_auto_reconnect(IPConnection *ipcon, bool auto_reconnect)¶

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 ipcon_connect() call.

Default value is true.

bool ipcon_get_auto_reconnect(IPConnection *ipcon)¶

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

void ipcon_set_timeout(IPConnection *ipcon, uint32_t timeout)¶

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

Default timeout is 2500.

uint32_t ipcon_get_timeout(IPConnection *ipcon)¶

Returns the timeout as set by ipcon_set_timeout().

int ipcon_enumerate(IPConnection *ipcon)¶

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

void ipcon_wait(IPConnection *ipcon)¶

Stops the current thread until ipcon_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.

void ipcon_unwait(IPConnection *ipcon)¶

Unwaits the thread previously stopped by ipcon_wait()

wait and unwait act in the same way as acquire and release of a semaphore.

Callback Configuration Functions¶

void ipcon_register_callback(IPConnection *ipcon, int16_t callback_id, void (*function)(void), void *user_data)¶

Registers the given function with the given callback_id. The user_data will be passed as the last parameter to the function.

The available callback IDs with corresponding function signatures are described below.

Callbacks¶

Callbacks can be registered to be notified about events. The registration is done with the ipcon_register_callback() function. The parameters consist of the IP Connection object, the callback ID, the callback function and optional user data:

void my_callback(int p, void *user_data) {
    printf("parameter: %d\n", p);
}

ipcon_register_callback(&ipcon, IPCON_CALLBACK_EXAMPLE, (void (*)(void))my_callback, NULL);

The available constants with corresponding callback function signatures are described below.

IPCON_CALLBACK_ENUMERATE¶

void callback(const char *uid, const char *connected_uid, char position, uint8_t hardware_version[3], uint8_t firmware_version[3], uint16_t device_identifier, uint8_t enumeration_type, void *user_data)

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:

• IPCON_ENUMERATION_TYPE_AVAILABLE = 0: Device is available (enumeration triggered by user: ipcon_enumerate()). This enumeration type can occur multiple times for the same device.
• IPCON_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.
• IPCON_ENUMERATION_TYPE_DISCONNECTED = 2: Device is disconnected (only possible for USB connection). In this case only uid and enumeration_type 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-type>_DEVICE_IDENTIFIER

For example: MASTER_DEVICE_IDENTIFIER or AMBIENT_LIGHT_DEVICE_IDENTIFIER.

IPCON_CALLBACK_CONNECTED¶

void callback(uint8_t connect_reason, void *user_data)

This callback is called whenever the IP Connection got connected to a Brick Daemon or to a WIFI/Ethernet Extension, possible reasons are:

• IPCON_CONNECT_REASON_REQUEST = 0: Connection established after request from user.
• IPCON_CONNECT_REASON_AUTO_RECONNECT = 1: Connection after auto-reconnect.

IPCON_CALLBACK_DISCONNECTED¶

void callback(uint8_t disconnect_reason, void *user_data)

This callback is called whenever the IP Connection got disconnected from a Brick Daemon or from a WIFI/Ethernet Extension, possible reasons are:

• IPCON_DISCONNECT_REASON_REQUEST = 0: Disconnect was requested by user.
• IPCON_DISCONNECT_REASON_ERROR = 1: Disconnect because of an unresolvable error.
• IPCON_DISCONNECT_REASON_SHUTDOWN = 2: Disconnect initiated by Brick Daemon or WIFI/Ethernet Extension.