API

API

Callback functions

callback_id_t callback_register(String name, callback_fptr_t cb, void *arg = nullptr, enable_condition_t cond = nullptr)

Registers a callback function cb with name name to the system. Callback functions can be mapped to GAs with the web UI or via callback_assign.

Arguments:

• name The name of the callback. Will be shown in the web UI.
• cb Pointer to the callback function. See callback_fptr_t.
• arg Optional. Is passed to the callback function as the second argument.
• cond Optional. See enable_condition_t.

Returns: On failure -1. On success, a callback_id_t unique to the callback, numeric value >= 0. Can fail, if no space is left to add more callbacks, see header config.

void          callback_assign(callback_id_t id, address_t val);

Assigns a group address to a registered callback function.

Arguments:

• id The if of the callback which should be mapped to a group address.
• val The address the callback should be mapped to.

Returns: Nothing. Can fail, if id is not valid identifier for a registered callback.

Physical address functions

Normally, the physical address is set in the web UI. However, it can be read and set by code:

void          physical_address_set(address_t const &addr);
address_t     physical_address_get();

Set or get the physical address of the device. See address_t.

Configuration functions

Configuration options are shown in the web UI, their values can be changed by the user and read by the code.

Registering config options

The following types of configuration options can be registered:

• String
• Integer (int32_t)
• Boolean (bool)
• Named options
• KNX group address (address_t)

The registration functions are:

config_id_t   config_register_string(String name, uint8_t len, String _default, enable_condition_t cond = nullptr);
config_id_t   config_register_int(String name, int32_t _default, enable_condition_t cond = nullptr);
config_id_t   config_register_bool(String name, bool _default, enable_condition_t cond = nullptr);
config_id_t   config_register_options(String name, option_entry_t *options, uint8_t _default, enable_condition_t cond = nullptr);
config_id_t   config_register_ga(String name, enable_condition_t cond = nullptr);

Arguments:

• name The name of the config option. Will be shown in the web UI.
• _default The default value for this option, used when no user defined value is available.
• cond Optional. See enable_condition_t.
• len Only for config_register_string. The maximum length of the string the user should be able to set. Not the length of the default value although the default value must not exceed the length specified here.
• options Only for config_register_options. See option_entry_t

Returns: On success, all registration functions return a config_id_t unique to the config option, numeric value >= 0. On failure, -1 is returned.

Reading config options

String        config_get_string(config_id_t id);
int32_t       config_get_int(config_id_t id);
bool          config_get_bool(config_id_t id);
uint8_t       config_get_options(config_id_t id);
address_t     config_get_ga(config_id_t id);

Arguments:

• id The id of the config option to read.

Returns: The value stored for the config option specified by id. If the type of the given id does not match the type of the function, no error is returned. In this case a default value is returned, e.g., 0 for config_get_int if id refers to any config option that is not int.

Setting config options

Config options are normally set by the user from the web UI but can be set from code, e.g., to reconfigure the device via KNX.

void          config_set_string(config_id_t id, String val);
void          config_set_int(config_id_t id, int32_t val);
void          config_set_bool(config_id_t, bool val);
void          config_set_options(config_id_t id, uint8_t val);
void          config_set_ga(config_id_t id, address_t val);

Arguments:

• id The id of the config option to set.
• val The new value of the config option.

Returns: Nothing. If the type of the given id does not match the type of the function, no error is returned.

Feedback functions

Feedback functions are a way to display values on the web UI, e.g., sensor readings.

Support types are:

• Integer (int32_t)
• Floating-point numbers (float)
• Boolean (bool)
• Action (A button is shown that triggers execution of the given function)

feedback_id_t feedback_register_int(String name, int32_t *value, enable_condition_t cond = nullptr);
feedback_id_t feedback_register_float(String name, float *value, uint8_t precision = 2, enable_condition_t cond = nullptr);
feedback_id_t feedback_register_bool(String name, bool *value, enable_condition_t cond = nullptr);
feedback_id_t feedback_register_action(String name, feedback_action_fptr_t value, void *arg = nullptr, enable_condition_t = nullptr);

Arguments:

• name The name of the value. Will be shown in the web UI next to the value.
• value A pointer to the value. This pointer is dereferenced and read out when the web UI is rendered and the value is shown.
• cond See option_entry_t
• precision Only for feedback_register_float. Optional. Sets how many decimal points are shown, default are two.
• arg Only for feedback_register_action. Optional. This pointer is passed to the registered action function. See feedback_action_fptr_t

Returns: On failure -1. On success, a feedback_id_t unique to the feedback, numeric value >= 0. Currently not consumed by other functions but reserved for later use. Can fail, if no space is left to add more feedbacks, see header config.