vslab riot api

API documentation

Application functions

A more detailed documentation can be found in the main header file elect.h. Note: Most functions return 0 on success and an error code otherwise. Use the folling API functions to:

• get the IP address of the local node: void get_node_ip_addr(ipv6_addr_t *addr). Example:

ipv6_addr_t node_ip;
get_node_ip_addr(&node_ip);

• compare two IP addresses: int ipv6_addr_cmp(const ipv6_addr_t *ip1, const ipv6_addr_t *ip2). The function returns <0 if ip1 < ip2, 0 if equal, and >0 if ip1 > ip2. Example (assuming node_ip is set as above):

ipv6_addr_t other_ip;
// fill other_ip
int cmp = ipv6_addr_cmp(&node_ip, &other_ip);

• send a broadcast with the nodes ID: int broadcast_id(const ipv6_addr_t *ip). Example (assuming node_ip is set as above):

if (broadcast_id(&node_ip) < 0) {
    printf("%s: failed\n", __func__);
}

• send a broadcast with a sensor value: int broadcast_sensor(int16_t value). Example:

int16_t mean = get_exponential_mean(); // <- this function is not part of the API
if (broadcast_sensor(mean) < 0) {
    printf("%s: failed\n", __func__);
}

• read the temperature sensor of the local node: int16_t sensor_read(void). Example:

int16_t value = sensor_read();

• send an IP address to another node using CoAP PUT: int coap_put_node(ipv6_addr_t addr, ipv6_addr_t node). In context of this exercise this is used to send the local nodes IP address to the elected leader (aka. coordinator) node. Note: this call is asynchronous, i.e., the request will not block until success and may also fail. Example (assuming node_ip is set as above):

// must be set before usage
ipv6_addr_t leader_ip;
if (coap_put_node(leader_ip, node_ip) == 0) {
    printf("Success\n");
}

• request for sensor data from another node using CoAP GET: int coap_get_sensor(ipv6_addr_t addr). In context of this exercise the leader will query all known nodes. Note: this call is asynchronous, i.e., the request will not block until success and may also fail, the answer will be passed via IPC. Example:

// must be filled before usage
ipv6_addr_t nodes[ELECT_NODES_NUM];
for (int i = 0; i < ELECT_NODES_NUM; i++) {
    coap_get_sensor(nodes[i]);
}

Additional RIOT functions

RIOT provides a very rich API. In the following you find all further functions required (or helpful) for the implementation.

• To print text to the terminal use the common printf(...) function. For debug or logging output, which can be switched on and off, use LOG_DEBUG(...). The function behaves like printf, but output is only visible when compiled with CFLAGS=-DLOG_LEVEL=LOG_ALL.

• To sleep or wait during executing, use xtimer_sleep or xtimer_usleep to either sleep for certain number of seconds or microseconds.

• Convert an IPv6 address from or to string, by using ipv6_addr_from_str and ipv6_addr_to_str. Example:

char addr_str[IPV6_ADDR_MAX_STR_LEN];
// must be set before usage, e.g. get_node_ip_addr(&ipaddr)
ipv6_addr_t ipaddr;
ipv6_addr_to_str(addr_str, &ipaddr, sizeof(addr_str));
// or backwards
ipv6_addr_from_str(&ipaddr, addr_str);

• get the process ID of the current thread: kernel_pid_t thread_getpid(). Example to get pid of main thread, call in main:

kernel_pid_t main_pid = thread_getpid();

• The event loop in main is primarily driven by events that are triggered via IPC using RIOTs internal message passing mechanism. To delay events or wait for a timeout the main thread needs to send an event to itself using IPC messages. Traditionally, one might use sleep functions for that, but they would block the main thread and thus prevent processing any other events in between. The scaffold already provides 3 events and a timer for that purpose see here. Note: the event offset must be (re)set before usage! If the timer for that event is already running you should remove the event before scheduling it again. Example (assuming main_pid is set as above):

// remove existing event
evtimer_del(&evtimer, &leader_timeout_event.event);
// reset event timer offset
leader_timeout_event.event.offset = ELECT_LEADER_TIMEOUT;
// (re)schedule event message
evtimer_add_msg(&evtimer, &leader_timeout_event, main_pid);