FibStack C API Reference

Introduction

This page describes the FibStack C Application Programming Interface (API).

Enumerations

enum fibstack_value_type

The literals of this enumeration specify the device value type.

Constant	Description
UNKNOWN_TYPE	The device value type is unknown.
BOOLEAN_TYPE	Boolean value type.
INTEGER_TYPE	Integer value type.

Structures

struct fibstack_context

This structure contains the information of all connected FibStack boards.

struct fibstack_board

This structure contains information about the board and its devices.

Functions

Context Functions

struct fibstack_context *fibstack_context_new()
Allocates and initializes a fibstack_context structure and returns a pointer to it.

Returns:
a pointer to the allocated fibstack_context structure.

void fibstack_context_free(struct fibstack_context *context)
Deallocates the memory of the provided fibstack_context structure.

Parameters:
context : The fibstack_context structure.

int fibstack_context_get_board_number(struct fibstack_context *context)
Returns the total number of PiSwitcher Plus boards connected to the current computer board. The function returns a negative value if the pointer to the context structure is invalid.

Parameters:
context : The fibstack_context structure.

Returns:
a total number of attached PiSwitcher Plus boards. A negative number if the input is invalid.

int fibstack_context_update(struct fibstack_context *context)
Queries the I2C port for PiSwitcher Plus boards and populates the context structure with the data.

Parameters:
context : The fibstack_context structure.

struct fibstack_board *fibstack_context_get_board_by_index(struct fibstack_context *context, int board_index)
The function returns a pointer to the fibstack_board structure specified by the board_index parameter. If the context or board_index is invalid, the function will return NULL.

Parameters:
context : The fibstack_context structure.
board_index : the index of the board the user wants to get. A valid board index is a number between 0 (inclusive) and the value returned by the fibstack_context_get_board_nubmer() function (exclusive).

Returns:
a pointer to the fibstack_board structure, NULL if input parameters are invalid.

struct fibstack_board *fibstack_context_get_board_by_address(struct fibstack_context *context, int board_address)
The function returns a pointer to the fibstack_board structure specified by the board_address parameter. If the context or board_address is invalid, or no PiSwitcher Plus board is found on the specified I2C address, the function will return NULL.

Parameters:
context : The fibstack_context structure.
board_address : the I2C address of the board.

Returns:
a pointer to the fibstack_board structure, NULL if input parameters are invalid or no board found.

Board Specific functions

int fibstack_board_update(struct fibstack_board *board)
Queries the board and updates all the device data. Returns a negative number if the pointer to the board is invalid or could not update the data.

Parameters:
board: The fibstack_board structure.

Returns:
a positive number if data have been updated, negative if could not update.

char *fibstack_board_get_description(struct fibstack_board *board)
The function returns a short description of the board.

Parameters:
board: the pointer to the fibstack_board structure.

Returns:
the board description.

int fibstack_board_get_address(struct fibstack_board *board)
The function returns the I2C address of the specified board. If the pointer to the board structure is invalid, the function returns a negative number.

Parameters:
board: A pointer to the fibstack_board structure.

Returns:
the I2C address of the board, negative number if the input is invalid.

int fibstack_board_set_address(struct fibstack_board *board, int new_address)
The function changes the board’s I2C address. If the I2C address was changed successfully, the function returns the new address. If one of the input parameters is invalid or could not change the address, the function returns a negative value.

Parameters:
board: The pointer to the fibstack_board structure.
new_address: The new I2C address.

Returns:
the board’s new I2C address, a negative value if the I2C address has not changed.

int fibstack_board_get_device_number(struct fibstack_board *board)
This function returns the total device number on the specified board. If the board structure pointer is invalid, the function will return a negative number.

Parameters:
board: the pointer to the fibstack_board structure.

Returns:
the total device number, or a negative value if the input is invalid.

char *fibstack_board_get_device_description(struct fibstack_board *board, int device_id)
The function returns a short device description.

Parameters:
board: The pointer to the fibstack_board structure.
device_id : the device ID. The value of the device ID is between 0 (inclusive) and the number returned by fibstack_bard_get_device_number() function (exclusive).

Returns:
the device description.

bool fibstack_board_is_device_read_only(struct fibstack_board *board, int device_id)
Returns true if the specified device value is read-only. Otherwise, it returns false.

Returns:
true - if the device is read-only, false otherwise.

enum fibstack_value_type fibstack_board_get_device_value_type(struct fibstack_board *board, int device_id)
Returns the type of value which the device stores.

Parameters:
board: the pointer to the fibstack_board structure.
device_id : the device ID. The value of the device ID is between 0 (inclusive) and the number returned by fibstack_bard_get_device_number() function (exclusive).

Returns:
the type of value which the device stores.

bool fibstack_board_get_boolean(struct fibstack_board *board, int device_index)
Returns the boolean value for the specified device.

Returns:
device’s boolean value.

int fibstack_board_set_boolean(struct fibstack_board *board, int device_index, bool new_value)
The function sets a boolean value for the specified device.

Returns:
a positive value if the device was set, negative otherwise.

int fibstack_board_get_integer(struct fibstack_board *board, int device_id)
Returns the integer value for the specified device.

Returns:
device’s integer value.