File pisound-micro.c#

#include "include/pisound-micro.h"
#include "include/pisound-micro/api_internal.h"
#include <ctype.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
#include <unistd.h>
#include <sys/file.h>
#include <sys/ioctl.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <linux/input.h>
#include <dirent.h>
#include <stdarg.h>
#include <time.h>
#include <threads.h>
#include <stdatomic.h>
#include "utils.h"

Classes#

Type	Name
struct	upisnd_ctx_t
struct	upisnd_elements_list_node_t

Public Types#

Type	Name
enum	upisnd_path_type_t
enum	upisnd_element_attr_e

Public Static Attributes#

Type	Name
const uint32_t	UPISND_TIMEOUT_MS = `2000ul`
const char *const	UPISND_TEXT_SEPARATORS = `" \n\t"`
const char const	UPISND_PIN_NAMES = `/* multi line expression */`
const char	UPISND_SYSFS_DEFAULT_BASE_PATH = `"/sys/pisound-micro"`
const char	UPISND_PATH_SETUP_FMT = `"%s/setup"`
const char	UPISND_PATH_UNSETUP_FMT = `"%s/unsetup"`
const char	UPISND_ELEMENT_PATH_ATTR_FMT = `"%s/elements/%s/%s"`
struct upisnd_ctx_t *	upisnd_active_ctx
struct upisnd_ctx_t *	upisnd_ctx_list

Public Functions#

Type	Name
UPISND_API int	upisnd_validate_element_name (const char * name) Verifies that the provided element name is valid.
UPISND_API int	upisnd_generate_random_element_name (char * dst, size_t n, const char * prefix) A helper for generating a random element name with the provided prefix.
UPISND_API int	upisnd_unsetup (const char * name) Force-unsetup an Element by name. This is normally not necessary.
UPISND_API upisnd_element_ref_t	upisnd_element_get (const char * name) Get a reference to an Element by name that was set up during the current runtime session.
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 int	upisnd_element_open_value_fd (upisnd_element_ref_t el, int flags) Opens the Element's value file descriptor.
UPISND_API int	upisnd_value_read (int fd) Reads the Element's value.
UPISND_API int	upisnd_value_write (int fd, int value) Writes the Element's value.
UPISND_API bool	upisnd_is_pin_valid (upisnd_pin_t pin) Checks validity of the provided pin number.
UPISND_API const char *	upisnd_pin_to_str (upisnd_pin_t pin) Converts the provided pin to its string representation.
UPISND_API upisnd_pin_t	upisnd_str_to_pin (const char * str) Parses the provided string and returns the corresponding pin number.
UPISND_API const char *	upisnd_pin_pull_to_str (upisnd_pin_pull_e pull) Converts the provided pin pull to its string representation.
	UPISND_DEFINE_STR_TO_ENUM (pin_pull, UPISND_PIN_PULL_COUNT)
UPISND_API const char *	upisnd_activity_to_str (upisnd_activity_e activity) Converts the provided activity type to its string representation.
	UPISND_DEFINE_STR_TO_ENUM (activity, UPISND_ACTIVITY_COUNT)
UPISND_API const char *	upisnd_element_type_to_str (upisnd_element_type_e type) Converts the provided element type to its string representation.
	UPISND_DEFINE_STR_TO_ENUM (element_type, UPISND_ELEMENT_TYPE_COUNT)
UPISND_API const char *	upisnd_pin_direction_to_str (upisnd_pin_direction_e dir) Converts the provided pin direction to its string representation.
	UPISND_DEFINE_STR_TO_ENUM (pin_direction, UPISND_PIN_DIR_COUNT)
UPISND_API const char *	upisnd_value_mode_to_str (upisnd_value_mode_e mode) Converts the provided value mode to its string representation.
	UPISND_DEFINE_STR_TO_ENUM (value_mode, UPISND_VALUE_MODE_COUNT)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (0, 3, upisnd_element_type_e, element_type)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (3, 8, upisnd_pin_t, pin_id)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (11, 2, upisnd_pin_pull_e, gpio_pull)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (13, 1, upisnd_pin_direction_e, gpio_dir)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (12, 1, bool, gpio_output)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (13, 8, upisnd_pin_t, encoder_pin_b_id)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (21, 2, upisnd_pin_pull_e, encoder_pin_b_pull)
	UPISND_DEFINE_INTERNAL_SETUP_FIELD (11, 2, upisnd_activity_e, activity_type)
UPISND_API upisnd_element_type_e	upisnd_setup_get_element_type (upisnd_setup_t setup) Extracts the Element type from the setup container.
UPISND_API upisnd_pin_t	upisnd_setup_get_pin_id (upisnd_setup_t setup) Extracts the main pin from the setup container.
UPISND_API upisnd_pin_pull_e	upisnd_setup_get_gpio_pull (upisnd_setup_t setup) Extracts the GPIO pull from the setup container, applies to GPIO Input and the first pin of Encoder.
UPISND_API upisnd_pin_direction_e	upisnd_setup_get_gpio_dir (upisnd_setup_t setup) Extracts the GPIO direction from the setup container, applies only to GPIO Input or Output.
UPISND_API int	upisnd_setup_get_gpio_output (upisnd_setup_t setup) Extracts the GPIO output level from the setup container, applies only to GPIO Output.
UPISND_API upisnd_pin_t	upisnd_setup_get_encoder_pin_b_id (upisnd_setup_t setup) Extracts the Encoder's second pin from the setup container, applies only to Encoders.
UPISND_API upisnd_pin_pull_e	upisnd_setup_get_encoder_pin_b_pull (upisnd_setup_t setup) Extracts the Encoder's second pin pull from the setup container, applies only to Encoders.
UPISND_API upisnd_activity_e	upisnd_setup_get_activity_type (upisnd_setup_t setup) Extracts the Activity type from the setup container, applies only to Activity Elements.
UPISND_API int	upisnd_setup_set_element_type (upisnd_setup_t * setup, upisnd_element_type_e value) Sets the Element type in the setup container.
UPISND_API int	upisnd_setup_set_pin_id (upisnd_setup_t * setup, upisnd_pin_t value) Sets the main pin id in the setup container.
UPISND_API int	upisnd_setup_set_gpio_dir (upisnd_setup_t * setup, upisnd_pin_direction_e value) Sets the GPIO direction in the setup container, applies only to GPIO Elements.
UPISND_API int	upisnd_setup_set_gpio_pull (upisnd_setup_t * setup, upisnd_pin_pull_e value) Sets the GPIO pull in the setup container, applies only to GPIO Input.
UPISND_API int	upisnd_setup_set_gpio_output (upisnd_setup_t * setup, bool value) Sets the GPIO output level in the setup container, applies only to GPIO Output.
UPISND_API int	upisnd_setup_set_encoder_pin_b_id (upisnd_setup_t * setup, upisnd_pin_t value) Sets the Encoder's second pin id in the setup container, applies only to Encoders.
UPISND_API int	upisnd_setup_set_encoder_pin_b_pull (upisnd_setup_t * setup, upisnd_pin_pull_e value) Sets the Encoder's second pin pull in the setup container, applies only to Encoders.
UPISND_API int	upisnd_setup_set_activity_type (upisnd_setup_t * setup, upisnd_activity_e value) Sets the Activity type in the setup container, applies only to Activity Elements.
UPISND_API upisnd_element_ref_t	upisnd_setup (const char * name, upisnd_setup_t setup) Set up an Element with the provided name and setup options container.
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) Set up an Encoder Element with the provided name and setup options.
UPISND_API upisnd_element_ref_t	upisnd_setup_analog_input (const char * name, upisnd_pin_t pin) Set up an Analog Input Element with the provided name and setup options.
UPISND_API upisnd_element_ref_t	upisnd_setup_gpio_input (const char * name, upisnd_pin_t pin, upisnd_pin_pull_e pull) Set up a GPIO Input Element with the provided name and setup options.
UPISND_API upisnd_element_ref_t	upisnd_setup_gpio_output (const char * name, upisnd_pin_t pin, bool high) Set up a GPIO Output Element with the provided name and setup options.
UPISND_API upisnd_element_ref_t	upisnd_setup_activity (const char * name, upisnd_pin_t pin, upisnd_activity_e activity) Set up an Activity Element with the provided name and setup options.
UPISND_API upisnd_pin_direction_e	upisnd_element_gpio_get_direction (upisnd_element_ref_t el) Get the GPIO Element's direction.
UPISND_API upisnd_pin_pull_e	upisnd_element_gpio_get_pull (upisnd_element_ref_t el) Get the GPIO or Encoder Element's input pull.
UPISND_API upisnd_activity_e	upisnd_element_activity_get_type (upisnd_element_ref_t el) Get the Activity Element's activity type.
UPISND_API void	upisnd_element_encoder_init_default_opts (upisnd_encoder_opts_t * opts) Initialize the values of Encoder's options struct to the defaults.
UPISND_API int	upisnd_element_encoder_get_opts (upisnd_element_ref_t el, upisnd_encoder_opts_t * opts) Retrieve the Encoder's options.
UPISND_API int	upisnd_element_encoder_set_opts (upisnd_element_ref_t el, const upisnd_encoder_opts_t * opts) Set the Encoder's options.
UPISND_API upisnd_pin_t	upisnd_element_encoder_get_pin_b (upisnd_element_ref_t el) Get the Encoder's second pin.
UPISND_API upisnd_pin_pull_e	upisnd_element_encoder_get_pin_b_pull (upisnd_element_ref_t el) Get the Encoder's second pin pull. Use upisnd_element_gpio_get_pull to get pull of first pin.
UPISND_API void	upisnd_element_analog_input_init_default_opts (upisnd_analog_input_opts_t * opts) Initialize the values of Analog Input's options struct to the defaults.
UPISND_API int	upisnd_element_analog_input_get_opts (upisnd_element_ref_t el, upisnd_analog_input_opts_t * opts) Retrieve the Analog Input's options.
UPISND_API int	upisnd_element_analog_input_set_opts (upisnd_element_ref_t el, const upisnd_analog_input_opts_t * opts) Set the Analog Input's options.
UPISND_API const char *	upisnd_element_get_name (upisnd_element_ref_t el) Get the name of the Element.
UPISND_API upisnd_element_type_e	upisnd_element_get_type (upisnd_element_ref_t el) Get the type of the Element.
UPISND_API upisnd_pin_t	upisnd_element_get_pin (upisnd_element_ref_t el) Get the pin number of the Element.
UPISND_API int	upisnd_init (void) libpisoundmicro initialization function. Must be called once before using any other API.
UPISND_API void	upisnd_uninit (void) libpisoundmicro uninitialization function.

Public Static Functions#

Type	Name
struct upisnd_ctx_t *	upisnd_ctx_alloc (const char * sysfs_base)
void	upisnd_ctx_free (struct upisnd_ctx_t * ctx)
void	upisnd_contexts_prepend (struct upisnd_ctx_t * ctx)
int	upisnd_contexts_remove (struct upisnd_ctx_t * ctx)
struct upisnd_elements_list_node_t *	upisnd_element_alloc (const char * name, struct upisnd_ctx_t * ctx)
void	upisnd_elements_free (upisnd_element_ref_t el)
void	upisnd_elements_prepend (struct upisnd_elements_list_node_t * node)
int	upisnd_elements_remove (upisnd_element_ref_t el)
uint32_t	upisnd_get_ms (void)
struct upisnd_ctx_t *	upisnd_set_active_ctx (struct upisnd_ctx_t * ctx)
struct upisnd_ctx_t *	upisnd_init_internal (const char * sysfs_base)
int	upisnd_path (char * path, upisnd_path_type_t type, const char * sysfs_base)
int	upisnd_open_fd (upisnd_path_type_t type, int flags, const char * sysfs_base)
int	upisnd_element_path (char * path, const char * sysfs_base, const char * name, upisnd_element_attr_e attr)
int	upisnd_element_attr_open (upisnd_element_attr_e attr, int flags, upisnd_element_ref_t el)
int	upisnd_element_attr_read_int (upisnd_element_attr_e attr, upisnd_element_ref_t el)
int	upisnd_element_attr_write_int (upisnd_element_attr_e attr, upisnd_element_ref_t el, int i)
int	upisnd_element_attr_read_str (char * dst, size_t n, upisnd_element_attr_e attr, upisnd_element_ref_t el)
int	upisnd_element_attr_write_str (upisnd_element_attr_e attr, upisnd_element_ref_t el, const char * str)
int	upisnd_unsetup_do (const char * sysfs_base, const char * name)
bool	upisnd_element_exists_in_sysfs (const char * sysfs_base, const char * name)
upisnd_element_ref_t	upisnd_setup_do (struct upisnd_ctx_t * ctx, const char * name, const char * request_fmt, ...)
upisnd_pin_pull_e	upisnd_element_get_pull (upisnd_element_ref_t el, upisnd_element_attr_e attr)
int	upisnd_unsetup_all_elements (struct upisnd_ctx_t * ctx)

Macros#

Type	Name
define	UPISND_DEFINE_STR_TO_ENUM (middle_part, count) `/* multi line expression */`
define	UPISND_DEFINE_INTERNAL_SETUP_FIELD (shift, bits, type, name) `/* multi line expression */`

upisnd_path_type_t#

enum upisnd_path_type_t {
    UPISND_PATH_SETUP,
    UPISND_PATH_UNSETUP
};

upisnd_element_attr_e#

enum upisnd_element_attr_e {
    UPISND_ELEMENT_ATTR_ROOT,
    UPISND_ELEMENT_ATTR_TYPE,
    UPISND_ELEMENT_ATTR_DIRECTION,
    UPISND_ELEMENT_ATTR_PIN,
    UPISND_ELEMENT_ATTR_PIN_NAME,
    UPISND_ELEMENT_ATTR_PIN_PULL,
    UPISND_ELEMENT_ATTR_PIN_B,
    UPISND_ELEMENT_ATTR_PIN_B_NAME,
    UPISND_ELEMENT_ATTR_PIN_B_PULL,
    UPISND_ELEMENT_ATTR_GPIO_EXPORT,
    UPISND_ELEMENT_ATTR_GPIO_UNEXPORT,
    UPISND_ELEMENT_ATTR_INPUT_MIN,
    UPISND_ELEMENT_ATTR_INPUT_MAX,
    UPISND_ELEMENT_ATTR_VALUE_LOW,
    UPISND_ELEMENT_ATTR_VALUE_HIGH,
    UPISND_ELEMENT_ATTR_VALUE_MODE,
    UPISND_ELEMENT_ATTR_VALUE,
    UPISND_ELEMENT_ATTR_ACTIVITY_TYPE
};

UPISND_TIMEOUT_MS#

const uint32_t UPISND_TIMEOUT_MS;

UPISND_TEXT_SEPARATORS#

const char* const UPISND_TEXT_SEPARATORS;

UPISND_PIN_NAMES#

const char const UPISND_PIN_NAMES[UPISND_PIN_COUNT][4];

UPISND_SYSFS_DEFAULT_BASE_PATH#

const char UPISND_SYSFS_DEFAULT_BASE_PATH[];

UPISND_PATH_SETUP_FMT#

const char UPISND_PATH_SETUP_FMT[];

UPISND_PATH_UNSETUP_FMT#

const char UPISND_PATH_UNSETUP_FMT[];

UPISND_ELEMENT_PATH_ATTR_FMT#

const char UPISND_ELEMENT_PATH_ATTR_FMT[];

upisnd_active_ctx#

struct upisnd_ctx_t* upisnd_active_ctx;

upisnd_ctx_list#

struct upisnd_ctx_t* upisnd_ctx_list;

upisnd_validate_element_name#

Verifies that the provided element name is valid.

UPISND_API int upisnd_validate_element_name (
    const char * name
)

Returns:

The length of name on success, -errno on error.

Valid Element names are null terminated strings of characters, 1-63 long, and may not contain '/'.

upisnd_generate_random_element_name#

A helper for generating a random element name with the provided prefix.

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

Parameters:

dst The buffer to write the generated name to.
n The size of the buffer, at most UPISND_MAX_ELEMENT_NAME_LENGTH.
prefix The prefix to use for the generated name, can be NULL if not needed. The prefix can be up to UPISND_MAX_ELEMENT_NAME_LENGTH - 23 long.

It is not strictly necessary to use this function, you may use any fixed valid name for your Element.

Returns:

The return value is directly forwarded from the snprintf call. A negative value indicates an error, a value >= n means the dst buffer was not long enough, and a value < n indicates success. Check out snprintf documentation for more details.

upisnd_unsetup#

Force-unsetup an Element by name. This is normally not necessary.

UPISND_API int upisnd_unsetup (
    const char * name
)

Unrefing the element will automatically unsetup it once last reference is released. This function is only useful if recovering from crash, avoid if possible.

Returns:

0 on success, -1 on error, inspect errno for details.

upisnd_element_get#

Get a reference to an Element by name that was set up during the current runtime session.

UPISND_API upisnd_element_ref_t upisnd_element_get (
    const char * name
)

If the Element exists in /sys/pisound-micro/elements/, but it was not created by the current program, it won't get returned. In this case, you can try setting up an Element with the exact same setup options, if they match, you'll get a reference, otherwise, use upisnd_unsetup to remove the Element first, and set it up fresh.

Returns:

A valid Element reference on success, NULL on error.

upisnd_element_add_ref#

UPISND_API upisnd_element_ref_t upisnd_element_add_ref (
    upisnd_element_ref_t ref
)

Increment the reference count of the Element.

Returns:

The same reference that was passed in.

upisnd_element_unref#

UPISND_API void upisnd_element_unref (
    upisnd_element_ref_t * ref
)

Decrement the reference count of the Element.

Parameters:

ref The pointer to reference to unref, will be automatically NULL-ed out.

If the reference count reaches 0, the Element will be unsetup and released.

upisnd_element_open_value_fd#

Opens the Element's value file descriptor.

UPISND_API int upisnd_element_open_value_fd (
    upisnd_element_ref_t el,
    int flags
)

Parameters:

el The Element reference.
flags The flags to pass to the open system call.

You must set the access flags, such as O_RDONLY, O_WRONLY or O_RDWR, defined in the system's fcntl.h header. We recommend setting O_CLOEXEC as well. (combine the flags using logic OR |).

Use upisnd_value_read and upisnd_value_write to read and write the value.

You may also poll for changes (use POLLPRI). Look into the documentation for poll, ppoll and select system APIs for more details.

Once you're done with the fd, close it using the close system call.

Returns:

The file descriptor on success, -1 on error, inspect errno for details.

upisnd_value_read#

Reads the Element's value.

UPISND_API int upisnd_value_read (
    int fd
)

Parameters:

fd The file descriptor of the Element's value file.

Returns:

The value read from the Element's value file. On successful read, errno will be 0.

upisnd_value_write#

Writes the Element's value.

UPISND_API int upisnd_value_write (
    int fd,
    int value
)

Parameters:

fd The file descriptor of the Element's value file.
value The value to write to the Element's value file.

Returns:

Number of characters written on success, -1 on error, inspect errno for details.

upisnd_is_pin_valid#

Checks validity of the provided pin number.

UPISND_API bool upisnd_is_pin_valid (
    upisnd_pin_t pin
)

upisnd_pin_to_str#

Converts the provided pin to its string representation.

UPISND_API const char * upisnd_pin_to_str (
    upisnd_pin_t pin
)

upisnd_str_to_pin#

Parses the provided string and returns the corresponding pin number.

UPISND_API upisnd_pin_t upisnd_str_to_pin (
    const char * str
)

Returns:

The pin number, or UPISND_PIN_INVALID if the string is not a valid pin number.

upisnd_pin_pull_to_str#

Converts the provided pin pull to its string representation.

UPISND_API const char * upisnd_pin_pull_to_str (
    upisnd_pin_pull_e pull
)

UPISND_DEFINE_STR_TO_ENUM#

UPISND_DEFINE_STR_TO_ENUM (
    pin_pull,
    UPISND_PIN_PULL_COUNT
)

upisnd_activity_to_str#

Converts the provided activity type to its string representation.

UPISND_API const char * upisnd_activity_to_str (
    upisnd_activity_e activity
)

UPISND_DEFINE_STR_TO_ENUM#

UPISND_DEFINE_STR_TO_ENUM (
    activity,
    UPISND_ACTIVITY_COUNT
)

upisnd_element_type_to_str#

Converts the provided element type to its string representation.

UPISND_API const char * upisnd_element_type_to_str (
    upisnd_element_type_e type
)

UPISND_DEFINE_STR_TO_ENUM#

UPISND_DEFINE_STR_TO_ENUM (
    element_type,
    UPISND_ELEMENT_TYPE_COUNT
)

upisnd_pin_direction_to_str#

Converts the provided pin direction to its string representation.

UPISND_API const char * upisnd_pin_direction_to_str (
    upisnd_pin_direction_e dir
)

UPISND_DEFINE_STR_TO_ENUM#

UPISND_DEFINE_STR_TO_ENUM (
    pin_direction,
    UPISND_PIN_DIR_COUNT
)

upisnd_value_mode_to_str#

Converts the provided value mode to its string representation.

UPISND_API const char * upisnd_value_mode_to_str (
    upisnd_value_mode_e mode
)

UPISND_DEFINE_STR_TO_ENUM#

UPISND_DEFINE_STR_TO_ENUM (
    value_mode,
    UPISND_VALUE_MODE_COUNT
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    0,
    3,
    upisnd_element_type_e,
    element_type
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    3,
    8,
    upisnd_pin_t,
    pin_id
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    11,
    2,
    upisnd_pin_pull_e,
    gpio_pull
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    13,
    1,
    upisnd_pin_direction_e,
    gpio_dir
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    12,
    1,
    bool,
    gpio_output
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    13,
    8,
    upisnd_pin_t,
    encoder_pin_b_id
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    21,
    2,
    upisnd_pin_pull_e,
    encoder_pin_b_pull
)

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    11,
    2,
    upisnd_activity_e,
    activity_type
)

upisnd_setup_get_element_type#

Extracts the Element type from the setup container.

UPISND_API upisnd_element_type_e upisnd_setup_get_element_type (
    upisnd_setup_t setup
)

upisnd_setup_get_pin_id#

Extracts the main pin from the setup container.

UPISND_API upisnd_pin_t upisnd_setup_get_pin_id (
    upisnd_setup_t setup
)

upisnd_setup_get_gpio_pull#

Extracts the GPIO pull from the setup container, applies to GPIO Input and the first pin of Encoder.

UPISND_API upisnd_pin_pull_e upisnd_setup_get_gpio_pull (
    upisnd_setup_t setup
)

upisnd_setup_get_gpio_dir#

Extracts the GPIO direction from the setup container, applies only to GPIO Input or Output.

UPISND_API upisnd_pin_direction_e upisnd_setup_get_gpio_dir (
    upisnd_setup_t setup
)

upisnd_setup_get_gpio_output#

Extracts the GPIO output level from the setup container, applies only to GPIO Output.

UPISND_API int upisnd_setup_get_gpio_output (
    upisnd_setup_t setup
)

upisnd_setup_get_encoder_pin_b_id#

Extracts the Encoder's second pin from the setup container, applies only to Encoders.

UPISND_API upisnd_pin_t upisnd_setup_get_encoder_pin_b_id (
    upisnd_setup_t setup
)

upisnd_setup_get_encoder_pin_b_pull#

Extracts the Encoder's second pin pull from the setup container, applies only to Encoders.

UPISND_API upisnd_pin_pull_e upisnd_setup_get_encoder_pin_b_pull (
    upisnd_setup_t setup
)

upisnd_setup_get_activity_type#

Extracts the Activity type from the setup container, applies only to Activity Elements.

UPISND_API upisnd_activity_e upisnd_setup_get_activity_type (
    upisnd_setup_t setup
)

upisnd_setup_set_element_type#

Sets the Element type in the setup container.

UPISND_API int upisnd_setup_set_element_type (
    upisnd_setup_t * setup,
    upisnd_element_type_e value
)

Always set the Element Type before setting any other property of setup, as the type is double-checked to know if the set operation is valid for this type.

Returns:

0 on success, -errno on error.

upisnd_setup_set_pin_id#

Sets the main pin id in the setup container.

UPISND_API int upisnd_setup_set_pin_id (
    upisnd_setup_t * setup,
    upisnd_pin_t value
)

Returns:

0 on success, -errno on error.

upisnd_setup_set_gpio_dir#

Sets the GPIO direction in the setup container, applies only to GPIO Elements.

UPISND_API int upisnd_setup_set_gpio_dir (
    upisnd_setup_t * setup,
    upisnd_pin_direction_e value
)

Always set the GPIO dir before setting the pull and output, as the direction is double-checked to know whether pull (only input) or output level (only output) properties are valid.

Returns:

0 on success, -errno on error.

upisnd_setup_set_gpio_pull#

Sets the GPIO pull in the setup container, applies only to GPIO Input.

UPISND_API int upisnd_setup_set_gpio_pull (
    upisnd_setup_t * setup,
    upisnd_pin_pull_e value
)

Make sure to first set the GPIO dir to #UPISND_PIN_DIR_INPUT.

Returns:

0 on success, -errno on error.

upisnd_setup_set_gpio_output#

Sets the GPIO output level in the setup container, applies only to GPIO Output.

UPISND_API int upisnd_setup_set_gpio_output (
    upisnd_setup_t * setup,
    bool value
)

Make sure to first set the GPIO dir to #UPISND_PIN_DIR_OUTPUT.

Returns:

0 on success, -errno on error.

upisnd_setup_set_encoder_pin_b_id#

Sets the Encoder's second pin id in the setup container, applies only to Encoders.

UPISND_API int upisnd_setup_set_encoder_pin_b_id (
    upisnd_setup_t * setup,
    upisnd_pin_t value
)

Returns:

0 on success, `-errno on error.

upisnd_setup_set_encoder_pin_b_pull#

Sets the Encoder's second pin pull in the setup container, applies only to Encoders.

UPISND_API int upisnd_setup_set_encoder_pin_b_pull (
    upisnd_setup_t * setup,
    upisnd_pin_pull_e value
)

Returns:

0 on success, -errno on error.

upisnd_setup_set_activity_type#

Sets the Activity type in the setup container, applies only to Activity Elements.

UPISND_API int upisnd_setup_set_activity_type (
    upisnd_setup_t * setup,
    upisnd_activity_e value
)

Returns:

0 on success, -errno on error.

upisnd_setup#

Set up an Element with the provided name and setup options container.

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

Parameters:

name The name of the Element to set up.
setup The setup options container for the Element.

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.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_setup_encoder#

Set up an Encoder Element with the provided name and setup options.

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
)

Parameters:

name The name of the Element to set up.
pin_a The pin number of the first pin of the Encoder.
pull_a The pull of the first pin of the Encoder.
pin_b The pin number of the second pin of the Encoder.
pull_b The pull of the second pin of the Encoder.

See also: upisnd_setup for more details.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_setup_analog_input#

Set up an Analog Input Element with the provided name and setup options.

UPISND_API upisnd_element_ref_t upisnd_setup_analog_input (
    const char * name,
    upisnd_pin_t pin
)

Parameters:

name The name of the Element to set up.
pin The pin number of the Analog Input.
mode The value mode of the Analog Input.

See also: upisnd_setup for more details.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_setup_gpio_input#

Set up a GPIO Input Element with the provided name and setup options.

UPISND_API upisnd_element_ref_t upisnd_setup_gpio_input (
    const char * name,
    upisnd_pin_t pin,
    upisnd_pin_pull_e pull
)

Parameters:

name The name of the Element to set up.
pin The pin number of the GPIO Input.
pull The pull of the GPIO Input.

See also: upisnd_setup for more details.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_setup_gpio_output#

Set up a GPIO Output Element with the provided name and setup options.

UPISND_API upisnd_element_ref_t upisnd_setup_gpio_output (
    const char * name,
    upisnd_pin_t pin,
    bool high
)

Parameters:

name The name of the Element to set up.
pin The pin number of the GPIO Output.
high Whether the GPIO Output should be high or low.

See also: upisnd_setup for more details.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_setup_activity#

Set up an Activity Element with the provided name and setup options.

UPISND_API upisnd_element_ref_t upisnd_setup_activity (
    const char * name,
    upisnd_pin_t pin,
    upisnd_activity_e activity
)

Parameters:

name The name of the Element to set up.
pin The pin number to indicate the Activity on.
activity The activity type of the Activity Element.

See also: upisnd_setup for more details.

Returns:

A valid Element reference on success, NULL on error, inspect errno for details.

upisnd_element_gpio_get_direction#

Get the GPIO Element's direction.

UPISND_API upisnd_pin_direction_e upisnd_element_gpio_get_direction (
    upisnd_element_ref_t el
)

upisnd_element_gpio_get_pull#

Get the GPIO or Encoder Element's input pull.

UPISND_API upisnd_pin_pull_e upisnd_element_gpio_get_pull (
    upisnd_element_ref_t el
)

upisnd_element_activity_get_type#

Get the Activity Element's activity type.

UPISND_API upisnd_activity_e upisnd_element_activity_get_type (
    upisnd_element_ref_t el
)

upisnd_element_encoder_init_default_opts#

Initialize the values of Encoder's options struct to the defaults.

UPISND_API void upisnd_element_encoder_init_default_opts (
    upisnd_encoder_opts_t * opts
)

upisnd_element_encoder_get_opts#

Retrieve the Encoder's options.

UPISND_API int upisnd_element_encoder_get_opts (
    upisnd_element_ref_t el,
    upisnd_encoder_opts_t * opts
)

upisnd_element_encoder_set_opts#

Set the Encoder's options.

UPISND_API int upisnd_element_encoder_set_opts (
    upisnd_element_ref_t el,
    const upisnd_encoder_opts_t * opts
)

upisnd_element_encoder_get_pin_b#

Get the Encoder's second pin.

UPISND_API upisnd_pin_t upisnd_element_encoder_get_pin_b (
    upisnd_element_ref_t el
)

upisnd_element_encoder_get_pin_b_pull#

Get the Encoder's second pin pull. Use upisnd_element_gpio_get_pull to get pull of first pin.

UPISND_API upisnd_pin_pull_e upisnd_element_encoder_get_pin_b_pull (
    upisnd_element_ref_t el
)

upisnd_element_analog_input_init_default_opts#

Initialize the values of Analog Input's options struct to the defaults.

UPISND_API void upisnd_element_analog_input_init_default_opts (
    upisnd_analog_input_opts_t * opts
)

upisnd_element_analog_input_get_opts#

Retrieve the Analog Input's options.

UPISND_API int upisnd_element_analog_input_get_opts (
    upisnd_element_ref_t el,
    upisnd_analog_input_opts_t * opts
)

upisnd_element_analog_input_set_opts#

Set the Analog Input's options.

UPISND_API int upisnd_element_analog_input_set_opts (
    upisnd_element_ref_t el,
    const upisnd_analog_input_opts_t * opts
)

upisnd_element_get_name#

Get the name of the Element.

UPISND_API const char * upisnd_element_get_name (
    upisnd_element_ref_t el
)

The result is valid, as long as the element reference is valid.

Returns:

The name of the Element, or NULL if the reference is invalid.

upisnd_element_get_type#

Get the type of the Element.

UPISND_API upisnd_element_type_e upisnd_element_get_type (
    upisnd_element_ref_t el
)

Returns:

The type of the Element. If #UPISND_ELEMENT_TYPE_INVALID, check the errno.

upisnd_element_get_pin#

Get the pin number of the Element.

UPISND_API upisnd_pin_t upisnd_element_get_pin (
    upisnd_element_ref_t el
)

Returns:

The pin number of the Element. If UPISND_PIN_INVALID, check the errno.

upisnd_init#

libpisoundmicro initialization function. Must be called once before using any other API.

UPISND_API int upisnd_init (
    void
)

It is reference counted, so you may call it multiple times, you must call upisnd_uninit a matching number of times.

Not thread-safe.

Returns:

0 on success, -1 on error, inspect errno for details.

upisnd_uninit#

libpisoundmicro uninitialization function.

UPISND_API void upisnd_uninit (
    void
)

Takes care of releasing any remaining Elements.

Not thread-safe.

Must be called upon process cleanup, including when handling signals, the same number of times as upisnd_init was called.

upisnd_ctx_alloc#

static struct upisnd_ctx_t * upisnd_ctx_alloc (
    const char * sysfs_base
)

upisnd_ctx_free#

static void upisnd_ctx_free (
    struct upisnd_ctx_t * ctx
)

upisnd_contexts_prepend#

static void upisnd_contexts_prepend (
    struct upisnd_ctx_t * ctx
)

upisnd_contexts_remove#

static int upisnd_contexts_remove (
    struct upisnd_ctx_t * ctx
)

upisnd_element_alloc#

static struct upisnd_elements_list_node_t * upisnd_element_alloc (
    const char * name,
    struct upisnd_ctx_t * ctx
)

upisnd_elements_free#

static void upisnd_elements_free (
    upisnd_element_ref_t el
)

upisnd_elements_prepend#

static void upisnd_elements_prepend (
    struct upisnd_elements_list_node_t * node
)

upisnd_elements_remove#

static int upisnd_elements_remove (
    upisnd_element_ref_t el
)

upisnd_get_ms#

static uint32_t upisnd_get_ms (
    void
)

upisnd_set_active_ctx#

static struct upisnd_ctx_t * upisnd_set_active_ctx (
    struct upisnd_ctx_t * ctx
)

upisnd_init_internal#

static struct upisnd_ctx_t * upisnd_init_internal (
    const char * sysfs_base
)

upisnd_path#

static int upisnd_path (
    char * path,
    upisnd_path_type_t type,
    const char * sysfs_base
)

upisnd_open_fd#

static int upisnd_open_fd (
    upisnd_path_type_t type,
    int flags,
    const char * sysfs_base
)

upisnd_element_path#

static int upisnd_element_path (
    char * path,
    const char * sysfs_base,
    const char * name,
    upisnd_element_attr_e attr
)

upisnd_element_attr_open#

static int upisnd_element_attr_open (
    upisnd_element_attr_e attr,
    int flags,
    upisnd_element_ref_t el
)

upisnd_element_attr_read_int#

static int upisnd_element_attr_read_int (
    upisnd_element_attr_e attr,
    upisnd_element_ref_t el
)

upisnd_element_attr_write_int#

static int upisnd_element_attr_write_int (
    upisnd_element_attr_e attr,
    upisnd_element_ref_t el,
    int i
)

upisnd_element_attr_read_str#

static int upisnd_element_attr_read_str (
    char * dst,
    size_t n,
    upisnd_element_attr_e attr,
    upisnd_element_ref_t el
)

upisnd_element_attr_write_str#

static int upisnd_element_attr_write_str (
    upisnd_element_attr_e attr,
    upisnd_element_ref_t el,
    const char * str
)

upisnd_unsetup_do#

static int upisnd_unsetup_do (
    const char * sysfs_base,
    const char * name
)

upisnd_element_exists_in_sysfs#

static bool upisnd_element_exists_in_sysfs (
    const char * sysfs_base,
    const char * name
)

upisnd_setup_do#

static upisnd_element_ref_t upisnd_setup_do (
    struct upisnd_ctx_t * ctx,
    const char * name,
    const char * request_fmt,
    ...
)

upisnd_element_get_pull#

static upisnd_pin_pull_e upisnd_element_get_pull (
    upisnd_element_ref_t el,
    upisnd_element_attr_e attr
)

upisnd_unsetup_all_elements#

static int upisnd_unsetup_all_elements (
    struct upisnd_ctx_t * ctx
)

Macro Definition Documentation#

UPISND_DEFINE_STR_TO_ENUM#

#define UPISND_DEFINE_STR_TO_ENUM (
    middle_part,
    count
) `/* multi line expression */`

UPISND_DEFINE_INTERNAL_SETUP_FIELD#

#define UPISND_DEFINE_INTERNAL_SETUP_FIELD (
    shift,
    bits,
    type,
    name
) `/* multi line expression */`