meshx_gpio_kv.h File Reference

MeshX GPIO KV Engine Serialization Format. More...

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdio.h>
#include "interface/utils/meshx_fal_interface.h"
#include "meshx_gpio_types.h"

Go to the source code of this file.

Data Structures
struct	meshx_gpio_config_header_kv_t
	Header for serialized GPIO configuration stored in KV Engine. More...
struct	meshx_gpio_pin_config_kv_t
	Serialized GPIO pin configuration for KV Engine storage. More...
struct	meshx_gpio_pwm_config_kv_t
	Serialized PWM configuration for KV Engine storage. More...
struct	meshx_gpio_intr_config_kv_t
	Serialized interrupt configuration for KV Engine storage. More...
struct	meshx_gpio_pin_state_kv_t
	Serialized GPIO pin state for KV Engine storage. More...

Macros
#define	MESHX_GPIO_CONFIG_VERSION_CURRENT   1
	Current GPIO configuration serialization format version.
#define	MESHX_GPIO_CONFIG_VERSION_MIN   1
	Minimum supported version (for backward compatibility).
#define	MESHX_GPIO_CONFIG_VERSION_MAX   1
	Maximum supported version (for forward compatibility).
#define	MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN   16
	Maximum length for product name in key prefix.
#define	MESHX_GPIO_KV_KEY_MAX_LEN   32
	Maximum total key length (KV Engine limit is 32).
#define	MESHX_GPIO_KV_KEY_CONFIG   "config"
	Key suffix for main GPIO configuration.
#define	MESHX_GPIO_KV_KEY_STATE   "state"
	Key suffix for GPIO pin state.
#define	MESHX_GPIO_KV_KEY_PWM   "pwm"
	Key suffix for PWM configuration.
#define	MESHX_GPIO_KV_KEY_INTR   "intr"
	Key suffix for interrupt configuration.
#define	MESHX_GPIO_CONFIG_HEADER_SIZE   sizeof(meshx_gpio_config_header_kv_t)
	Size of configuration header.
#define	MESHX_GPIO_PIN_CONFIG_SIZE   sizeof(meshx_gpio_pin_config_kv_t)
	Size of basic pin configuration.
#define	MESHX_GPIO_PWM_CONFIG_SIZE   sizeof(meshx_gpio_pwm_config_kv_t)
	Size of PWM configuration extension.
#define	MESHX_GPIO_INTR_CONFIG_SIZE   sizeof(meshx_gpio_intr_config_kv_t)
	Size of interrupt configuration extension.
#define	MESHX_GPIO_PIN_STATE_SIZE   sizeof(meshx_gpio_pin_state_kv_t)
	Size of pin state record.
#define	MESHX_GPIO_PIN_MAX_SIZE
	Maximum size per pin (including extensions).
#define	MESHX_GPIO_CONFIG_TOTAL_SIZE(pin_count)
	Calculate total config size for given pin count.
#define	MESHX_GPIO_CONFIG_FLAG_HAS_PWM   (1 << 0)
	Flag: Configuration has PWM extensions.
#define	MESHX_GPIO_CONFIG_FLAG_HAS_INTR   (1 << 1)
	Flag: Configuration has interrupt extensions.
#define	MESHX_GPIO_CONFIG_FLAG_MIGRATED   (1 << 2)
	Flag: Configuration is migrated from older version.
#define	MESHX_GPIO_CONFIG_FLAG_READ_ONLY   (1 << 3)
	Flag: Configuration is in read-only mode.
#define	MESHX_GPIO_CONFIG_TYPE_NONE   0
	No extended configuration.
#define	MESHX_GPIO_CONFIG_TYPE_PWM   1
	PWM configuration follows.
#define	MESHX_GPIO_CONFIG_TYPE_INTR   2
	Interrupt configuration follows.

Functions
static uint8_t	meshx_gpio_kv_make_config_key (const char *product_name, char *buf, uint8_t buf_len)
	Construct KV Engine key for GPIO configuration.
static uint8_t	meshx_gpio_kv_make_state_key (const char *product_name, uint8_t logical_pin, char *buf, uint8_t buf_len)
	Construct KV Engine key for GPIO pin state.
static uint8_t	meshx_gpio_kv_make_pwm_key (const char *product_name, uint8_t logical_pin, char *buf, uint8_t buf_len)
	Construct KV Engine key for PWM configuration.
static uint8_t	meshx_gpio_kv_make_intr_key (const char *product_name, uint8_t logical_pin, char *buf, uint8_t buf_len)
	Construct KV Engine key for interrupt configuration.
static uint16_t	meshx_gpio_kv_calc_crc16 (const uint8_t *data, uint32_t len)
	Calculate CRC16 compatible with KV Engine.
static bool	meshx_gpio_kv_verify_crc16 (const uint8_t *data, uint32_t len)
	Verify CRC16 of serialized GPIO configuration.
static void	meshx_gpio_kv_init_header (meshx_gpio_config_header_kv_t *header, uint8_t pin_count)
	Initialize a GPIO configuration header.
static void	meshx_gpio_kv_finalize_crc16 (uint8_t *data, uint32_t len)
	Calculate and set CRC16 for serialized configuration.
static void	meshx_gpio_kv_serialize_pin (const meshx_gpio_pin_config_t *src, meshx_gpio_pin_config_kv_t *dst)
	Convert runtime pin config to serialized format.
static void	meshx_gpio_kv_deserialize_pin (const meshx_gpio_pin_config_kv_t *src, meshx_gpio_pin_config_t *dst)
	Convert serialized pin config to runtime format.
static void	meshx_gpio_kv_serialize_pwm (const meshx_gpio_pin_config_t *src, meshx_gpio_pwm_config_kv_t *dst)
	Serialize PWM configuration.
static void	meshx_gpio_kv_deserialize_pwm (const meshx_gpio_pwm_config_kv_t *src, meshx_gpio_pin_config_t *dst)
	Deserialize PWM configuration.
static void	meshx_gpio_kv_serialize_intr (const meshx_gpio_pin_config_t *src, meshx_gpio_intr_config_kv_t *dst)
	Serialize interrupt configuration.
static void	meshx_gpio_kv_deserialize_intr (const meshx_gpio_intr_config_kv_t *src, meshx_gpio_pin_config_t *dst)
	Deserialize interrupt configuration.
static bool	meshx_gpio_kv_is_version_supported (uint8_t version)
	Check if a configuration version is supported.
static bool	meshx_gpio_kv_needs_migration (uint8_t from_version, uint8_t to_version)
	Get migration requirement between versions.
meshx_err_t	meshx_gpio_kv_init (const meshx_fal_partition_t *kv_partition, const char *product_name)
	Initialize GPIO KV Engine persistence.
meshx_err_t	meshx_gpio_save_config_to_kv (const meshx_gpio_pin_config_t *configs, uint8_t pin_count)
	Save GPIO configuration to KV Engine.
meshx_err_t	meshx_gpio_load_config_from_kv (meshx_gpio_pin_config_t *configs, uint8_t max_pins, uint8_t *out_pin_count)
	Load GPIO configuration from KV Engine.
meshx_err_t	meshx_gpio_config_exists_in_kv (bool *exists)
	Check if GPIO configuration exists in KV Engine.
meshx_err_t	meshx_gpio_save_pin_state_to_kv (uint8_t logical_pin, const meshx_gpio_pin_state_t *state)
	Save current pin state to KV Engine.
meshx_err_t	meshx_gpio_load_pin_state_from_kv (uint8_t logical_pin, meshx_gpio_pin_state_t *state)
	Load pin state from KV Engine.
meshx_err_t	meshx_gpio_export_config (const meshx_gpio_pin_config_t *configs, uint8_t pin_count, uint8_t *buf, uint16_t buf_len, uint16_t *out_size)
	Export GPIO configuration to serialized format.
meshx_err_t	meshx_gpio_import_config (const uint8_t *buf, uint16_t buf_len, meshx_gpio_pin_config_t *configs, uint8_t max_pins, uint8_t *out_pin_count)
	Import GPIO configuration from serialized format.
meshx_err_t	meshx_gpio_clear_config_in_kv (void)
	Clear GPIO configuration from KV Engine.
meshx_err_t	meshx_gpio_kv_deinit (void)
	Deinitialize GPIO KV Engine persistence.
bool	meshx_gpio_kv_is_initialized (void)
	Check if GPIO KV persistence is initialized.

Detailed Description

MeshX GPIO KV Engine Serialization Format.

This file defines the binary serialization structures for GPIO configuration persistence using the MeshX KV Engine. The format is designed for:

• Compact storage with versioning support
• CRC16 checksums compatible with KV Engine's CRC algorithm
• Product-specific key prefixes for OTA update compatibility
• Forward/backward compatibility for configuration migration

Author

MeshX Team

Date

2024

Macro Definition Documentation

MESHX_GPIO_CONFIG_FLAG_HAS_INTR

#define MESHX_GPIO_CONFIG_FLAG_HAS_INTR   (1 << 1)

Flag: Configuration has interrupt extensions.

MESHX_GPIO_CONFIG_FLAG_HAS_PWM

#define MESHX_GPIO_CONFIG_FLAG_HAS_PWM   (1 << 0)

Flag: Configuration has PWM extensions.

MESHX_GPIO_CONFIG_FLAG_MIGRATED

#define MESHX_GPIO_CONFIG_FLAG_MIGRATED   (1 << 2)

Flag: Configuration is migrated from older version.

MESHX_GPIO_CONFIG_FLAG_READ_ONLY

#define MESHX_GPIO_CONFIG_FLAG_READ_ONLY   (1 << 3)

Flag: Configuration is in read-only mode.

MESHX_GPIO_CONFIG_HEADER_SIZE

#define MESHX_GPIO_CONFIG_HEADER_SIZE   sizeof(meshx_gpio_config_header_kv_t)

Size of configuration header.

MESHX_GPIO_CONFIG_TOTAL_SIZE

#define MESHX_GPIO_CONFIG_TOTAL_SIZE

(

pin_count

)

Value:

(MESHX_GPIO_CONFIG_HEADER_SIZE + ((pin_count) * MESHX_GPIO_PIN_CONFIG_SIZE))

Calculate total config size for given pin count.

#define MESHX_GPIO_CONFIG_TOTAL_SIZE(pin_count) \
    (MESHX_GPIO_CONFIG_HEADER_SIZE + ((pin_count) * MESHX_GPIO_PIN_CONFIG_SIZE))

MESHX_GPIO_CONFIG_TYPE_INTR

#define MESHX_GPIO_CONFIG_TYPE_INTR   2

Interrupt configuration follows.

MESHX_GPIO_CONFIG_TYPE_NONE

#define MESHX_GPIO_CONFIG_TYPE_NONE   0

No extended configuration.

MESHX_GPIO_CONFIG_TYPE_PWM

#define MESHX_GPIO_CONFIG_TYPE_PWM   1

PWM configuration follows.

MESHX_GPIO_CONFIG_VERSION_CURRENT

#define MESHX_GPIO_CONFIG_VERSION_CURRENT   1

Current GPIO configuration serialization format version.

MESHX_GPIO_CONFIG_VERSION_MAX

#define MESHX_GPIO_CONFIG_VERSION_MAX   1

Maximum supported version (for forward compatibility).

MESHX_GPIO_CONFIG_VERSION_MIN

#define MESHX_GPIO_CONFIG_VERSION_MIN   1

Minimum supported version (for backward compatibility).

MESHX_GPIO_INTR_CONFIG_SIZE

#define MESHX_GPIO_INTR_CONFIG_SIZE   sizeof(meshx_gpio_intr_config_kv_t)

Size of interrupt configuration extension.

MESHX_GPIO_KV_KEY_CONFIG

#define MESHX_GPIO_KV_KEY_CONFIG   "config"

Key suffix for main GPIO configuration.

MESHX_GPIO_KV_KEY_INTR

#define MESHX_GPIO_KV_KEY_INTR   "intr"

Key suffix for interrupt configuration.

MESHX_GPIO_KV_KEY_MAX_LEN

#define MESHX_GPIO_KV_KEY_MAX_LEN   32

Maximum total key length (KV Engine limit is 32).

MESHX_GPIO_KV_KEY_PWM

#define MESHX_GPIO_KV_KEY_PWM   "pwm"

Key suffix for PWM configuration.

MESHX_GPIO_KV_KEY_STATE

#define MESHX_GPIO_KV_KEY_STATE   "state"

Key suffix for GPIO pin state.

MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN

#define MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN   16

Maximum length for product name in key prefix.

MESHX_GPIO_PIN_CONFIG_SIZE

#define MESHX_GPIO_PIN_CONFIG_SIZE   sizeof(meshx_gpio_pin_config_kv_t)

Size of basic pin configuration.

MESHX_GPIO_PIN_MAX_SIZE

#define MESHX_GPIO_PIN_MAX_SIZE

Value:

(MESHX_GPIO_PIN_CONFIG_SIZE + \
MESHX_GPIO_PWM_CONFIG_SIZE)

Maximum size per pin (including extensions).

#define MESHX_GPIO_PIN_MAX_SIZE          (MESHX_GPIO_PIN_CONFIG_SIZE + \
                                          MESHX_GPIO_PWM_CONFIG_SIZE)

MESHX_GPIO_PIN_STATE_SIZE

#define MESHX_GPIO_PIN_STATE_SIZE   sizeof(meshx_gpio_pin_state_kv_t)

Size of pin state record.

MESHX_GPIO_PWM_CONFIG_SIZE

#define MESHX_GPIO_PWM_CONFIG_SIZE   sizeof(meshx_gpio_pwm_config_kv_t)

Size of PWM configuration extension.

Function Documentation

meshx_gpio_clear_config_in_kv()

meshx_err_t meshx_gpio_clear_config_in_kv

(

void

)

Clear GPIO configuration from KV Engine.

Removes the stored GPIO configuration, forcing fallback to defaults on next load.

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    /* Construct KV key */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_config_key(current_product_name, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct config key");
        return MESHX_FAIL;
    }
 
    /* Remove from KV Engine */
    meshx_err_t err = meshx_kv_engine_remove(key);
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to remove config: %d", err);
        return err;
    }
 
    /* Commit the removal */
    err = meshx_kv_engine_commit();
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to commit removal: %d", err);
        return err;
    }
 
    MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "Cleared GPIO config from KV");
    return MESHX_SUCCESS;
}

meshx_gpio_config_exists_in_kv()

meshx_err_t meshx_gpio_config_exists_in_kv

(

bool *

exists

)

Check if GPIO configuration exists in KV Engine.

Parameters

[out]

exists

true if configuration exists, false otherwise

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    if (!exists) {
        return MESHX_INVALID_ARG;
    }
 
    /* Construct KV key */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_config_key(current_product_name, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct config key");
        return MESHX_FAIL;
    }
 
    /* Try to read with zero-length buffer to check existence */
    uint8_t dummy;
    meshx_err_t err = meshx_kv_engine_read(key, &dummy, 0);
 
    *exists = (err == MESHX_SUCCESS);
 
    return MESHX_SUCCESS;
}

meshx_gpio_export_config()

meshx_err_t meshx_gpio_export_config	(	const meshx_gpio_pin_config_t *	configs,
		uint8_t	pin_count,
		uint8_t *	buf,
		uint16_t	buf_len,
		uint16_t *	out_size )

Export GPIO configuration to serialized format.

Exports the configuration in binary format for transfer to another device.

Parameters

	configs	Array of pin configurations
	pin_count	Number of pins
[out]	buf	Output buffer
	buf_len	Buffer length
[out]	out_size	Actual exported size

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!configs || !buf || !out_size) {
        return MESHX_INVALID_ARG;
    }
 
    /* Export uses the same serialization format as KV storage */
    return serialize_gpio_config(configs, pin_count, buf, buf_len, out_size);
}

meshx_gpio_import_config()

meshx_err_t meshx_gpio_import_config	(	const uint8_t *	buf,
		uint16_t	buf_len,
		meshx_gpio_pin_config_t *	configs,
		uint8_t	max_pins,
		uint8_t *	out_pin_count )

Import GPIO configuration from serialized format.

Imports configuration from binary format received from another device.

Parameters

	buf	Input buffer
	buf_len	Buffer length
[out]	configs	Array to store imported configurations
	max_pins	Maximum pins that can be stored
[out]	out_pin_count	Actual number of pins imported

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!buf || !configs || !out_pin_count) {
        return MESHX_INVALID_ARG;
    }
 
    /* Import uses the same deserialization format as KV storage */
    return deserialize_gpio_config(buf, buf_len, configs, max_pins, out_pin_count);
}

meshx_gpio_kv_calc_crc16()

uint16_t meshx_gpio_kv_calc_crc16 ( const uint8_t * data, uint32_t len )

inlinestatic

Calculate CRC16 compatible with KV Engine.

Uses the same CRC-16 algorithm as meshx_kv_engine.c (Modbus CRC-16 with polynomial 0xA001). This ensures the GPIO subsystem can independently verify data integrity.

Parameters

data	Pointer to data buffer
len	Length of data in bytes

Returns

CRC16 value

{
    uint16_t crc = 0xFFFF;
    for (uint32_t i = 0; i < len; i++) {
        crc ^= data[i];
        for (int j = 0; j < 8; j++) {
            if (crc & 1) {
                crc = (crc >> 1) ^ 0xA001;
            } else {
                crc >>= 1;
            }
        }
    }
    return crc;
}

meshx_gpio_kv_deinit()

meshx_err_t meshx_gpio_kv_deinit

(

void

)

Deinitialize GPIO KV Engine persistence.

Cleans up KV persistence resources. Does not affect the underlying KV Engine partition.

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_persistence_initialized) {
        return MESHX_SUCCESS;
    }
 
    gpio_kv_partition = NULL;
    memset(current_product_name, 0, sizeof(current_product_name));
    kv_persistence_initialized = false;
 
    MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "GPIO KV persistence deinitialized");
    return MESHX_SUCCESS;
}

meshx_gpio_kv_deserialize_intr()

void meshx_gpio_kv_deserialize_intr ( const meshx_gpio_intr_config_kv_t * src, meshx_gpio_pin_config_t * dst )

inlinestatic

Deserialize interrupt configuration.

Parameters

src	Source serialized configuration
dst	Destination runtime configuration

{
    if (!src || !dst) return;
 
    dst->mode_config.interrupt.trigger = src->trigger_type;
    dst->mode_config.interrupt.task_priority = src->task_priority;
    dst->mode_config.interrupt.task_stack_size = src->task_stack_size;
}

meshx_gpio_kv_deserialize_pin()

void meshx_gpio_kv_deserialize_pin ( const meshx_gpio_pin_config_kv_t * src, meshx_gpio_pin_config_t * dst )

inlinestatic

Convert serialized pin config to runtime format.

Parameters

src	Source serialized configuration
dst	Destination runtime configuration

{
    if (!src || !dst) return;
 
    dst->logical_pin = src->logical_pin;
    dst->physical_pin = src->physical_pin;
    dst->mode = src->mode;
    dst->pull = src->pull;
    dst->drive_strength = src->drive_strength;
    dst->initial_level = src->initial_level;
    dst->signal_inversion = src->signal_inversion ? true : false;
}

meshx_gpio_kv_deserialize_pwm()

void meshx_gpio_kv_deserialize_pwm ( const meshx_gpio_pwm_config_kv_t * src, meshx_gpio_pin_config_t * dst )

inlinestatic

Deserialize PWM configuration.

Parameters

src	Source serialized configuration
dst	Destination runtime configuration

{
    if (!src || !dst) return;
 
    dst->mode_config.pwm.frequency = src->frequency;
    dst->mode_config.pwm.duty_cycle = src->duty_cycle;
    dst->mode_config.pwm.resolution = src->resolution;
    dst->mode_config.pwm.channel = src->channel;
}

meshx_gpio_kv_finalize_crc16()

void meshx_gpio_kv_finalize_crc16 ( uint8_t * data, uint32_t len )

inlinestatic

Calculate and set CRC16 for serialized configuration.

Parameters

data	Pointer to serialized data buffer (including header)
len	Total length of data

{
    if (!data || len < MESHX_GPIO_CONFIG_HEADER_SIZE) return;
 
    meshx_gpio_config_header_kv_t *header = (meshx_gpio_config_header_kv_t *)data;
 
    /* CRC covers everything after the crc16 field */
    const uint8_t *crc_data = data + offsetof(meshx_gpio_config_header_kv_t, total_size);
    uint32_t crc_len = len - offsetof(meshx_gpio_config_header_kv_t, total_size);
 
    header->crc16 = meshx_gpio_kv_calc_crc16(crc_data, crc_len);
}

meshx_gpio_kv_init()

meshx_err_t meshx_gpio_kv_init	(	const meshx_fal_partition_t *	kv_partition,
		const char *	product_name )

Initialize GPIO KV Engine persistence.

This function initializes the KV Engine for GPIO configuration storage. It must be called before any other GPIO KV functions.

Parameters

kv_partition	Pointer to the flash partition to use for KV storage
product_name	Product name for key prefix (max 16 chars)

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_partition || !product_name) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Invalid arguments for KV init");
        return MESHX_INVALID_ARG;
    }
 
    /* Initialize KV Engine */
    meshx_err_t err = meshx_kv_engine_init(kv_partition);
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to initialize KV Engine: %d", err);
        return err;
    }
 
    /* Store partition reference */
    gpio_kv_partition = kv_partition;
 
    /* Store product name for key prefix */
    strncpy(current_product_name, product_name, MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN);
    current_product_name[MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN] = '\0';
 
    kv_persistence_initialized = true;
 
    MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "GPIO KV persistence initialized for product: %s",
               current_product_name);
    return MESHX_SUCCESS;
}

meshx_gpio_kv_init_header()

void meshx_gpio_kv_init_header ( meshx_gpio_config_header_kv_t * header, uint8_t pin_count )

inlinestatic

Initialize a GPIO configuration header.

Parameters

header	Pointer to header to initialize
pin_count	Number of pins in configuration

{
    if (!header) return;
 
    header->version = MESHX_GPIO_CONFIG_VERSION_CURRENT;
    header->pin_count = pin_count;
    header->crc16 = 0;
    header->total_size = (uint16_t)MESHX_GPIO_CONFIG_TOTAL_SIZE(pin_count);
    header->flags = 0;
    header->reserved[0] = 0;
    header->reserved[1] = 0;
    header->reserved[2] = 0;
}

meshx_gpio_kv_is_initialized()

bool meshx_gpio_kv_is_initialized

(

void

)

Check if GPIO KV persistence is initialized.

Returns

true if initialized, false otherwise

{
    return kv_persistence_initialized;
}

meshx_gpio_kv_is_version_supported()

bool meshx_gpio_kv_is_version_supported ( uint8_t version )

inlinestatic

Check if a configuration version is supported.

Parameters

version

Version number to check

Returns

true if version is supported, false otherwise

{
    return (version >= MESHX_GPIO_CONFIG_VERSION_MIN &&
            version <= MESHX_GPIO_CONFIG_VERSION_MAX);
}

meshx_gpio_kv_make_config_key()

uint8_t meshx_gpio_kv_make_config_key ( const char * product_name, char * buf, uint8_t buf_len )

inlinestatic

Construct KV Engine key for GPIO configuration.

Parameters

product_name	Product name (max 16 chars)
buf	Buffer to store the key
buf_len	Buffer length

Returns

Key length, or 0 on error

{
    if (!product_name || !buf || buf_len < MESHX_GPIO_KV_KEY_MAX_LEN) {
        return 0;
    }
    return (uint8_t)snprintf(buf, buf_len, "gpio_%.*s_%s",
                             MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN,
                             product_name,
                             MESHX_GPIO_KV_KEY_CONFIG);
}

meshx_gpio_kv_make_intr_key()

uint8_t meshx_gpio_kv_make_intr_key ( const char * product_name, uint8_t logical_pin, char * buf, uint8_t buf_len )

inlinestatic

Construct KV Engine key for interrupt configuration.

Parameters

product_name	Product name (max 16 chars)
logical_pin	Logical pin number
buf	Buffer to store the key
buf_len	Buffer length

Returns

Key length, or 0 on error

{
    if (!product_name || !buf || buf_len < MESHX_GPIO_KV_KEY_MAX_LEN) {
        return 0;
    }
    return (uint8_t)snprintf(buf, buf_len, "gpio_%.*s_%s_%u",
                             MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN,
                             product_name,
                             MESHX_GPIO_KV_KEY_INTR,
                             logical_pin);
}

meshx_gpio_kv_make_pwm_key()

uint8_t meshx_gpio_kv_make_pwm_key ( const char * product_name, uint8_t logical_pin, char * buf, uint8_t buf_len )

inlinestatic

Construct KV Engine key for PWM configuration.

Parameters

product_name	Product name (max 16 chars)
logical_pin	Logical pin number
buf	Buffer to store the key
buf_len	Buffer length

Returns

Key length, or 0 on error

{
    if (!product_name || !buf || buf_len < MESHX_GPIO_KV_KEY_MAX_LEN) {
        return 0;
    }
    return (uint8_t)snprintf(buf, buf_len, "gpio_%.*s_%s_%u",
                             MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN,
                             product_name,
                             MESHX_GPIO_KV_KEY_PWM,
                             logical_pin);
}

meshx_gpio_kv_make_state_key()

uint8_t meshx_gpio_kv_make_state_key ( const char * product_name, uint8_t logical_pin, char * buf, uint8_t buf_len )

inlinestatic

Construct KV Engine key for GPIO pin state.

Parameters

product_name	Product name (max 16 chars)
logical_pin	Logical pin number
buf	Buffer to store the key
buf_len	Buffer length

Returns

Key length, or 0 on error

{
    if (!product_name || !buf || buf_len < MESHX_GPIO_KV_KEY_MAX_LEN) {
        return 0;
    }
    return (uint8_t)snprintf(buf, buf_len, "gpio_%.*s_%s_%u",
                             MESHX_GPIO_KV_PRODUCT_NAME_MAX_LEN,
                             product_name,
                             MESHX_GPIO_KV_KEY_STATE,
                             logical_pin);
}

meshx_gpio_kv_needs_migration()

bool meshx_gpio_kv_needs_migration ( uint8_t from_version, uint8_t to_version )

inlinestatic

Get migration requirement between versions.

Parameters

from_version	Source version
to_version	Target version

Returns

true if migration is needed, false if direct loading is possible

{
    return (from_version != to_version);
}

meshx_gpio_kv_serialize_intr()

void meshx_gpio_kv_serialize_intr ( const meshx_gpio_pin_config_t * src, meshx_gpio_intr_config_kv_t * dst )

inlinestatic

Serialize interrupt configuration.

Parameters

src	Source runtime interrupt configuration
dst	Destination serialized configuration

{
    if (!src || !dst) return;
 
    dst->trigger_type = src->mode_config.interrupt.trigger;
    dst->task_priority = src->mode_config.interrupt.task_priority;
    dst->task_stack_size = src->mode_config.interrupt.task_stack_size;
    dst->flags = 0;
    dst->reserved[0] = 0;
    dst->reserved[1] = 0;
    dst->reserved[2] = 0;
}

meshx_gpio_kv_serialize_pin()

void meshx_gpio_kv_serialize_pin ( const meshx_gpio_pin_config_t * src, meshx_gpio_pin_config_kv_t * dst )

inlinestatic

Convert runtime pin config to serialized format.

Parameters

src	Source runtime configuration
dst	Destination serialized configuration

{
    if (!src || !dst) return;
 
    dst->logical_pin = src->logical_pin;
    dst->physical_pin = src->physical_pin;
    dst->mode = src->mode;
    dst->pull = src->pull;
    dst->drive_strength = src->drive_strength;
    dst->initial_level = src->initial_level;
    dst->signal_inversion = src->signal_inversion ? 1 : 0;
 
    /* Determine config type based on mode */
    if (src->mode == 5) { /* MESHX_GPIO_MODE_PWM_OUTPUT */
        dst->config_type = MESHX_GPIO_CONFIG_TYPE_PWM;
    } else if (src->mode == 0 && src->mode_config.interrupt.trigger != 0) {
        /* Input mode with interrupt */
        dst->config_type = MESHX_GPIO_CONFIG_TYPE_INTR;
    } else {
        dst->config_type = MESHX_GPIO_CONFIG_TYPE_NONE;
    }
}

meshx_gpio_kv_serialize_pwm()

void meshx_gpio_kv_serialize_pwm ( const meshx_gpio_pin_config_t * src, meshx_gpio_pwm_config_kv_t * dst )

inlinestatic

Serialize PWM configuration.

Parameters

src	Source runtime PWM configuration
dst	Destination serialized configuration

{
    if (!src || !dst) return;
 
    dst->frequency = src->mode_config.pwm.frequency;
    dst->duty_cycle = src->mode_config.pwm.duty_cycle;
    dst->resolution = src->mode_config.pwm.resolution;
    dst->channel = src->mode_config.pwm.channel;
    dst->reserved = 0;
}

meshx_gpio_kv_verify_crc16()

bool meshx_gpio_kv_verify_crc16 ( const uint8_t * data, uint32_t len )

inlinestatic

Verify CRC16 of serialized GPIO configuration.

Parameters

data	Pointer to serialized data (including header)
len	Total length of data

Returns

true if CRC is valid, false otherwise

{
    if (!data || len < MESHX_GPIO_CONFIG_HEADER_SIZE) {
        return false;
    }
 
    const meshx_gpio_config_header_kv_t *header =
        (const meshx_gpio_config_header_kv_t *)data;
 
    /* CRC covers everything after the crc16 field in the header */
    const uint8_t *crc_data = data + offsetof(meshx_gpio_config_header_kv_t, total_size);
    uint32_t crc_len = len - offsetof(meshx_gpio_config_header_kv_t, total_size);
 
    uint16_t calculated = meshx_gpio_kv_calc_crc16(crc_data, crc_len);
    return (calculated == header->crc16);
}

meshx_gpio_load_config_from_kv()

meshx_err_t meshx_gpio_load_config_from_kv	(	meshx_gpio_pin_config_t *	configs,
		uint8_t	max_pins,
		uint8_t *	out_pin_count )

Load GPIO configuration from KV Engine.

This function loads and deserializes GPIO configuration from KV Engine. If the configuration is not found or corrupted, returns MESHX_NOT_FOUND to allow fallback to compiled defaults.

Parameters

	configs	Array to store loaded pin configurations
	max_pins	Maximum pins that can be stored
[out]	out_pin_count	Actual number of pins loaded

Returns

meshx_err_t MESHX_SUCCESS on success, MESHX_NOT_FOUND if not found, error code on other failures

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    if (!configs || !out_pin_count) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Invalid arguments for load");
        return MESHX_INVALID_ARG;
    }
 
    /* Construct KV key */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_config_key(current_product_name, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct config key");
        return MESHX_FAIL;
    }
 
    /* Read from KV Engine */
    uint8_t buffer[MESHX_GPIO_KV_MAX_CONFIG_SIZE];
    uint16_t read_size = sizeof(buffer);
 
    meshx_err_t err = meshx_kv_engine_read(key, buffer, read_size);
    if (err != MESHX_SUCCESS) {
        if (err == MESHX_NOT_FOUND) {
            MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "No GPIO config found in KV, using defaults");
        } else {
            MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to read KV: %d", err);
        }
        return err;
    }
 
    /* Deserialize configuration */
    err = deserialize_gpio_config(buffer, read_size, configs, max_pins, out_pin_count);
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to deserialize config (corrupted?): %d", err);
        /* Return NOT_FOUND to trigger fallback to defaults */
        return MESHX_NOT_FOUND;
    }
 
    MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "Loaded GPIO config: %d pins", *out_pin_count);
    return MESHX_SUCCESS;
}

meshx_gpio_load_pin_state_from_kv()

meshx_err_t meshx_gpio_load_pin_state_from_kv	(	uint8_t	logical_pin,
		meshx_gpio_pin_state_t *	state )

Load pin state from KV Engine.

Loads previously persisted runtime state of a GPIO pin.

Parameters

	logical_pin	Logical pin number
[out]	state	Pointer to store loaded pin state

Returns

meshx_err_t MESHX_SUCCESS on success, MESHX_NOT_FOUND if not found, error code on other failures

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    if (!state) {
        return MESHX_INVALID_ARG;
    }
 
    /* Construct KV key for state */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_state_key(current_product_name, logical_pin, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct state key");
        return MESHX_FAIL;
    }
 
    /* Read from KV Engine */
    meshx_gpio_pin_state_kv_t state_kv;
    uint16_t read_size = sizeof(state_kv);
 
    meshx_err_t err = meshx_kv_engine_read(key, &state_kv, read_size);
    if (err != MESHX_SUCCESS) {
        if (err == MESHX_NOT_FOUND) {
            MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_GPIO, "No state found for pin %u", logical_pin);
        } else {
            MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to read pin state: %d", err);
        }
        return err;
    }
 
    /* Apply loaded state */
    state->current_level = state_kv.current_level;
    state->mode_state.pwm.started = state_kv.pwm_started;
    state->mode_state.pwm.duty_cycle = state_kv.current_duty;
 
    MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_GPIO, "Loaded state for pin %u: level=%u",
               logical_pin, state->current_level);
    return MESHX_SUCCESS;
}

meshx_gpio_save_config_to_kv()

meshx_err_t meshx_gpio_save_config_to_kv	(	const meshx_gpio_pin_config_t *	configs,
		uint8_t	pin_count )

Save GPIO configuration to KV Engine.

This function serializes and saves the GPIO configuration to KV Engine with versioning and CRC validation.

Parameters

configs	Array of pin configurations to save
pin_count	Number of pins in configuration

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    if (!configs || pin_count == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Invalid arguments for save");
        return MESHX_INVALID_ARG;
    }
 
    /* Construct KV key */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_config_key(current_product_name, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct config key");
        return MESHX_FAIL;
    }
 
    /* Serialize configuration */
    uint8_t buffer[MESHX_GPIO_KV_MAX_CONFIG_SIZE];
    uint16_t config_size = 0;
 
    meshx_err_t err = serialize_gpio_config(configs, pin_count, buffer, sizeof(buffer), &config_size);
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to serialize config: %d", err);
        return err;
    }
 
    /* Save to KV Engine (buffered in RAM) */
    err = meshx_kv_engine_set(key, buffer, config_size);
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to set KV value: %d", err);
        return err;
    }
 
    /* Commit to flash */
    err = meshx_kv_engine_commit();
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to commit KV: %d", err);
        return err;
    }
 
    MESHX_LOGI(MODULE_ID_COMPONENT_MESHX_GPIO, "Saved GPIO config: %d pins, %d bytes",
               pin_count, config_size);
    return MESHX_SUCCESS;
}

meshx_gpio_save_pin_state_to_kv()

meshx_err_t meshx_gpio_save_pin_state_to_kv	(	uint8_t	logical_pin,
		const meshx_gpio_pin_state_t *	state )

Save current pin state to KV Engine.

Persists the runtime state of a GPIO pin across reboots.

Parameters

logical_pin	Logical pin number
state	Pointer to pin state to save

Returns

meshx_err_t MESHX_SUCCESS on success, error code on failure

{
    if (!kv_persistence_initialized) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "KV persistence not initialized");
        return MESHX_ERR_GPIO_NOT_INITIALIZED;
    }
 
    if (!state) {
        return MESHX_INVALID_ARG;
    }
 
    /* Construct KV key for state */
    char key[MESHX_GPIO_KV_KEY_MAX_LEN];
    if (meshx_gpio_kv_make_state_key(current_product_name, logical_pin, key, sizeof(key)) == 0) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to construct state key");
        return MESHX_FAIL;
    }
 
    /* Serialize pin state */
    meshx_gpio_pin_state_kv_t state_kv = {
        .logical_pin = logical_pin,
        .current_level = state->current_level,
        .pwm_started = state->mode_state.pwm.started,
        .current_duty = state->mode_state.pwm.duty_cycle,
        .reserved = 0
    };
 
    /* Save to KV Engine */
    meshx_err_t err = meshx_kv_engine_set(key, &state_kv, sizeof(state_kv));
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to save pin state: %d", err);
        return err;
    }
 
    /* Commit to flash */
    err = meshx_kv_engine_commit();
    if (err != MESHX_SUCCESS) {
        MESHX_LOGE(MODULE_ID_COMPONENT_MESHX_GPIO, "Failed to commit pin state: %d", err);
        return err;
    }
 
    MESHX_LOGD(MODULE_ID_COMPONENT_MESHX_GPIO, "Saved state for pin %u: level=%u",
               logical_pin, state->current_level);
    return MESHX_SUCCESS;
}