File api.h#

File List > include > pisound-micro > api.h
// SPDX-License-Identifier: LGPL-2.1-only
//
// libpisoundmicro - a utility library for Pisound Micro I/O expander capabilities.
// Copyright (c) 2017-2025 Vilniaus Blokas UAB, https://blokas.io/
//
// This file is part of libpisoundmicro.
//
// libpisoundmicro is free software: you can redistribute it and/or modify it under the terms of the
// GNU Lesser General Public License as published by the Free Software Foundation, version 2.1 of the License.
//
// libpisoundmicro is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
// the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
// for more details.
//
// You should have received a copy of the GNU Lesser General Public License along with libpisoundmicro. If not, see <https://www.gnu.org/licenses/>.

#ifndef PISOUND_MICRO_API_H
#define PISOUND_MICRO_API_H

#ifndef PISOUND_MICRO_H
#   error Please #include <pisound-micro.h>!
#endif

#ifdef __cplusplus
extern "C" {
#endif

UPISND_API int upisnd_init(void);

UPISND_API void upisnd_uninit(void);

UPISND_API bool upisnd_is_pin_valid(upisnd_pin_t pin);

UPISND_API const char *upisnd_pin_to_str(upisnd_pin_t pin);

UPISND_API upisnd_pin_t upisnd_str_to_pin(const char *str);

UPISND_API const char *upisnd_pin_pull_to_str(upisnd_pin_pull_e pull);
UPISND_API upisnd_pin_pull_e upisnd_str_to_pin_pull(const char *str);

UPISND_API const char *upisnd_activity_to_str(upisnd_activity_e activity);
UPISND_API upisnd_activity_e upisnd_str_to_activity(const char *str);

UPISND_API const char *upisnd_element_type_to_str(upisnd_element_type_e type);
UPISND_API upisnd_element_type_e upisnd_str_to_element_type(const char *str);

UPISND_API const char *upisnd_pin_direction_to_str(upisnd_pin_direction_e dir);
UPISND_API upisnd_pin_direction_e upisnd_str_to_pin_direction(const char *str);

UPISND_API const char *upisnd_value_mode_to_str(upisnd_value_mode_e mode);
UPISND_API upisnd_value_mode_e upisnd_str_to_value_mode(const char *str);

UPISND_API int upisnd_setup_for_encoder(upisnd_setup_t *setup, upisnd_pin_t pin_a, upisnd_pin_pull_e pull_a, upisnd_pin_t pin_b, upisnd_pin_pull_e pull_b);
UPISND_API int upisnd_setup_for_analog_input(upisnd_setup_t *setup, upisnd_pin_t pin);
UPISND_API int upisnd_setup_for_gpio_input(upisnd_setup_t *setup, upisnd_pin_t pin, upisnd_pin_pull_e pull);
UPISND_API int upisnd_setup_for_gpio_output(upisnd_setup_t *setup, upisnd_pin_t pin, bool high);
UPISND_API int upisnd_setup_for_activity(upisnd_setup_t *setup, upisnd_pin_t pin, upisnd_activity_e activity);

UPISND_API upisnd_element_type_e  upisnd_setup_get_element_type      (upisnd_setup_t setup);
UPISND_API upisnd_pin_t           upisnd_setup_get_pin_id            (upisnd_setup_t setup);
UPISND_API upisnd_pin_pull_e      upisnd_setup_get_gpio_pull         (upisnd_setup_t setup);
UPISND_API upisnd_pin_direction_e upisnd_setup_get_gpio_dir          (upisnd_setup_t setup);
UPISND_API int                    upisnd_setup_get_gpio_output       (upisnd_setup_t setup);
UPISND_API upisnd_pin_t           upisnd_setup_get_encoder_pin_b_id  (upisnd_setup_t setup);
UPISND_API upisnd_pin_pull_e      upisnd_setup_get_encoder_pin_b_pull(upisnd_setup_t setup);
UPISND_API upisnd_activity_e      upisnd_setup_get_activity_type     (upisnd_setup_t setup);

UPISND_API int upisnd_setup_set_element_type(upisnd_setup_t *setup, upisnd_element_type_e value);

UPISND_API int upisnd_setup_set_pin_id(upisnd_setup_t *setup, upisnd_pin_t value);

UPISND_API int upisnd_setup_set_gpio_dir(upisnd_setup_t *setup, upisnd_pin_direction_e value);

UPISND_API int upisnd_setup_set_gpio_pull(upisnd_setup_t *setup, upisnd_pin_pull_e value);

UPISND_API int upisnd_setup_set_gpio_output(upisnd_setup_t *setup, bool value);

UPISND_API int upisnd_setup_set_encoder_pin_b_id(upisnd_setup_t *setup, upisnd_pin_t value);

UPISND_API int upisnd_setup_set_encoder_pin_b_pull(upisnd_setup_t *setup, upisnd_pin_pull_e value);

UPISND_API int upisnd_setup_set_activity_type(upisnd_setup_t *setup, upisnd_activity_e value);

UPISND_API int upisnd_validate_element_name(const char *name);

UPISND_API int upisnd_generate_random_element_name(char *dst, size_t n, const char *prefix);

UPISND_API int upisnd_unsetup(const char *name);


UPISND_API upisnd_element_ref_t upisnd_element_get(const char *name);

UPISND_API upisnd_element_ref_t upisnd_element_add_ref(upisnd_element_ref_t ref);

UPISND_API void upisnd_element_unref(upisnd_element_ref_t *ref);

UPISND_API const char *upisnd_element_get_name(upisnd_element_ref_t el);

UPISND_API upisnd_element_type_e upisnd_element_get_type(upisnd_element_ref_t el);

UPISND_API upisnd_pin_t upisnd_element_get_pin(upisnd_element_ref_t el);

UPISND_API int upisnd_element_open_value_fd(upisnd_element_ref_t el, int flags);

UPISND_API int upisnd_value_read(int fd);

UPISND_API int upisnd_value_write(int fd, int value);

// Setup functions create and setup an element, using the arguments provided for its configuration.
// In case an element already exists with the same name, and the requested configuration is the same,
// the existing element will get returned and its refcount will get incremented. Otherwise, NULL
// will be returned, and `errno` set appropriately.
//

UPISND_API upisnd_element_ref_t upisnd_setup(const char *name, upisnd_setup_t setup);

UPISND_API upisnd_element_ref_t upisnd_setup_encoder(const char *name, upisnd_pin_t pin_a, upisnd_pin_pull_e pull_a, upisnd_pin_t pin_b, upisnd_pin_pull_e pull_b);
UPISND_API upisnd_element_ref_t upisnd_setup_analog_input(const char *name, upisnd_pin_t pin);
UPISND_API upisnd_element_ref_t upisnd_setup_gpio_input(const char *name, upisnd_pin_t pin, upisnd_pin_pull_e pull);
UPISND_API upisnd_element_ref_t upisnd_setup_gpio_output(const char *name, upisnd_pin_t pin, bool high);
UPISND_API upisnd_element_ref_t upisnd_setup_activity(const char *name, upisnd_pin_t pin, upisnd_activity_e activity);

UPISND_API upisnd_pin_direction_e upisnd_element_gpio_get_direction(upisnd_element_ref_t el);
UPISND_API upisnd_pin_pull_e upisnd_element_gpio_get_pull(upisnd_element_ref_t el);

UPISND_API upisnd_activity_e upisnd_element_activity_get_type(upisnd_element_ref_t el);

UPISND_API void upisnd_element_encoder_init_default_opts(upisnd_encoder_opts_t *opts);
UPISND_API int  upisnd_element_encoder_get_opts(upisnd_element_ref_t el, upisnd_encoder_opts_t *opts);  
UPISND_API int  upisnd_element_encoder_set_opts(upisnd_element_ref_t el, const upisnd_encoder_opts_t *opts);
UPISND_API upisnd_pin_t upisnd_element_encoder_get_pin_b(upisnd_element_ref_t el);
UPISND_API upisnd_pin_pull_e upisnd_element_encoder_get_pin_b_pull(upisnd_element_ref_t el);

UPISND_API void upisnd_element_analog_input_init_default_opts(upisnd_analog_input_opts_t *opts);
UPISND_API int  upisnd_element_analog_input_get_opts(upisnd_element_ref_t el, upisnd_analog_input_opts_t *opts);
UPISND_API int  upisnd_element_analog_input_set_opts(upisnd_element_ref_t el, const upisnd_analog_input_opts_t *opts);

#ifdef __cplusplus
} // extern "C"
#endif

#endif // PISOUND_MICRO_API_H