meshx_serial.h File Reference

MeshX Serial Protocol (MXSP) Definitions. More...

#include "meshx_common.h"
#include "meshx_api.h"

Go to the source code of this file.

Data Structures
struct	mxsp_gpio_cmd_payload_t
	GPIO Command Payload (Host -> Engine). More...
struct	mxsp_gpio_rsp_payload_t
	GPIO Response Payload (Engine -> Host). More...
struct	mxsp_gpio_evt_payload_t
	GPIO Event Payload (Engine -> Host, async). More...
struct	mxsp_frame_t
	MXSP Frame structure. More...

Macros
#define	MXSP_SOF   0xFE
#define	MXSP_EOF   0xEF
#define	MXSP_PAYLOAD_MAX_SIZE   255

Enumerations
enum	mxsp_msg_type_t {   MXSP_MSG_TYPE_SYS_EVT_NOTIFY = 0xB1 ,   MXSP_MSG_TYPE_DATA_EVT_NOTIFY = 0xB2 ,   MXSP_MSG_TYPE_EL_CMD_SEND = 0xC1 ,   MXSP_MSG_TYPE_SYS_CMD_SEND = 0xC2 ,   MXSP_MSG_TYPE_HOSTED_MODE = 0x03 ,   MXSP_MSG_TYPE_GPIO_CMD = 0xD1 ,   MXSP_MSG_TYPE_GPIO_RSP = 0xD2 ,   MXSP_MSG_TYPE_GPIO_EVT = 0xD3 }
enum	mxsp_gpio_cmd_t {   MXSP_GPIO_CMD_SET_LEVEL = 0x01 ,   MXSP_GPIO_CMD_GET_LEVEL = 0x02 ,   MXSP_GPIO_CMD_TOGGLE = 0x03 ,   MXSP_GPIO_CMD_SET_PWM_DUTY = 0x04 ,   MXSP_GPIO_CMD_SET_PWM_FREQ = 0x05 ,   MXSP_GPIO_CMD_INTR_ENABLE = 0x06 ,   MXSP_GPIO_CMD_INTR_DISABLE = 0x07 ,   MXSP_GPIO_CMD_GET_CONFIG = 0x08 ,   MXSP_GPIO_CMD_GET_STATE = 0x09 }
	GPIO Command Types (Host -> Engine). More...
enum	mxsp_gpio_evt_t {   MXSP_GPIO_EVT_LEVEL_CHANGE = 0x01 ,   MXSP_GPIO_EVT_INTERRUPT = 0x02 ,   MXSP_GPIO_EVT_MODE_CHANGE = 0x03 ,   MXSP_GPIO_EVT_ERROR = 0xFF }
	GPIO Event Types (Engine -> Host, async). More...

Functions
void	meshx_serial_set_hosted_mode (bool enabled)
	Set the hosted mode state.
bool	meshx_serial_is_hosted_mode_enabled (void)
	Check if hosted mode is enabled.
meshx_err_t	meshx_serial_init (void)
	Initialize the MeshX Serial Protocol handler.
void	meshx_serial_parse_byte (uint8_t data)
	Parse incoming byte stream for MXSP frames.
meshx_err_t	mxsp_send_ctrl_event (const meshx_ctrl_msg_header_t *evt_header, const meshx_ctrl_payload_t *payload)
	Send a control event via MXSP.
meshx_err_t	mxsp_send_data_event (const meshx_app_element_msg_header_t *msg_hdr, const meshx_data_payload_t *payload)
	Send data event via MXSP.
meshx_err_t	mxsp_send_gpio_rsp (uint8_t cmd, uint8_t logical_pin, uint8_t status, const uint8_t *response, uint8_t response_len)
	Send GPIO response via MXSP.
meshx_err_t	mxsp_send_gpio_evt (uint8_t event_type, uint8_t logical_pin, uint8_t value)
	Send GPIO async event via MXSP.

Detailed Description

MeshX Serial Protocol (MXSP) Definitions.

This file defines the frame structure and APIs for the MeshX Serial Protocol, used for communication between the Mesh engine and an external Host MCU.

Macro Definition Documentation

MXSP_EOF

#define MXSP_EOF   0xEF

MXSP_PAYLOAD_MAX_SIZE

#define MXSP_PAYLOAD_MAX_SIZE   255

MXSP_SOF

#define MXSP_SOF   0xFE

Enumeration Type Documentation

mxsp_gpio_cmd_t

enum mxsp_gpio_cmd_t

GPIO Command Types (Host -> Engine).

Enumerator
MXSP_GPIO_CMD_SET_LEVEL	0x01	Set GPIO pin level
MXSP_GPIO_CMD_GET_LEVEL	0x02	Get GPIO pin level
MXSP_GPIO_CMD_TOGGLE	0x03	Toggle GPIO pin
MXSP_GPIO_CMD_SET_PWM_DUTY	0x04	Set PWM duty cycle
MXSP_GPIO_CMD_SET_PWM_FREQ	0x05	Set PWM frequency
MXSP_GPIO_CMD_INTR_ENABLE	0x06	Enable/disable interrupt
MXSP_GPIO_CMD_INTR_DISABLE	0x07	Disable interrupt
MXSP_GPIO_CMD_GET_CONFIG	0x08	Get pin configuration
MXSP_GPIO_CMD_GET_STATE	0x09	Get pin state

             {
    MXSP_GPIO_CMD_SET_LEVEL       = 0x01, /**< Set GPIO pin level */
    MXSP_GPIO_CMD_GET_LEVEL       = 0x02, /**< Get GPIO pin level */
    MXSP_GPIO_CMD_TOGGLE          = 0x03, /**< Toggle GPIO pin */
    MXSP_GPIO_CMD_SET_PWM_DUTY    = 0x04, /**< Set PWM duty cycle */
    MXSP_GPIO_CMD_SET_PWM_FREQ    = 0x05, /**< Set PWM frequency */
    MXSP_GPIO_CMD_INTR_ENABLE     = 0x06, /**< Enable/disable interrupt */
    MXSP_GPIO_CMD_INTR_DISABLE    = 0x07, /**< Disable interrupt */
    MXSP_GPIO_CMD_GET_CONFIG      = 0x08, /**< Get pin configuration */
    MXSP_GPIO_CMD_GET_STATE       = 0x09, /**< Get pin state */
} mxsp_gpio_cmd_t;

mxsp_gpio_evt_t

enum mxsp_gpio_evt_t

GPIO Event Types (Engine -> Host, async).

Enumerator
MXSP_GPIO_EVT_LEVEL_CHANGE	0x01	Pin level changed
MXSP_GPIO_EVT_INTERRUPT	0x02	Interrupt triggered
MXSP_GPIO_EVT_MODE_CHANGE	0x03	Mode changed
MXSP_GPIO_EVT_ERROR	0xFF	Error event

             {
    MXSP_GPIO_EVT_LEVEL_CHANGE    = 0x01, /**< Pin level changed */
    MXSP_GPIO_EVT_INTERRUPT       = 0x02, /**< Interrupt triggered */
    MXSP_GPIO_EVT_MODE_CHANGE     = 0x03, /**< Mode changed */
    MXSP_GPIO_EVT_ERROR           = 0xFF, /**< Error event */
} mxsp_gpio_evt_t;

mxsp_msg_type_t

enum mxsp_msg_type_t

Enumerator
MXSP_MSG_TYPE_SYS_EVT_NOTIFY	0xB1
MXSP_MSG_TYPE_DATA_EVT_NOTIFY	0xB2
MXSP_MSG_TYPE_EL_CMD_SEND	0xC1
MXSP_MSG_TYPE_SYS_CMD_SEND	0xC2
MXSP_MSG_TYPE_HOSTED_MODE	0x03
MXSP_MSG_TYPE_GPIO_CMD	0xD1
MXSP_MSG_TYPE_GPIO_RSP	0xD2
MXSP_MSG_TYPE_GPIO_EVT	0xD3

             {
    MXSP_MSG_TYPE_SYS_EVT_NOTIFY  = 0xB1, // Engine -> Host (Control Path)
    MXSP_MSG_TYPE_DATA_EVT_NOTIFY = 0xB2, // Engine -> Host (Data Path)
    MXSP_MSG_TYPE_EL_CMD_SEND     = 0xC1, // Host -> Engine (Command Path)
    MXSP_MSG_TYPE_SYS_CMD_SEND    = 0xC2, // Host -> Engine (System Command)
    MXSP_MSG_TYPE_HOSTED_MODE     = 0x03, // Internal/Setup
    /* GPIO Hosted Mode Message Types */
    MXSP_MSG_TYPE_GPIO_CMD        = 0xD1, // Host -> Engine (GPIO Command)
    MXSP_MSG_TYPE_GPIO_RSP        = 0xD2, // Engine -> Host (GPIO Response)
    MXSP_MSG_TYPE_GPIO_EVT        = 0xD3, // Engine -> Host (GPIO Event - async)
} mxsp_msg_type_t;

Function Documentation

meshx_serial_init()

meshx_err_t meshx_serial_init

(

void

)

Initialize the MeshX Serial Protocol handler.

Returns

meshx_err_t MESHX_SUCCESS on success

Initialize the MeshX Serial Protocol handler.

Returns

MESHX_SUCCESS on success, error code otherwise

{
    memset(&mxsp_ctx, 0, sizeof(mxsp_ctx));
    mxsp_ctx.state = STATE_SOF;
    mxsp_ctx.hosted_mode_enabled = false;
 
    meshx_task_t uart_rx_task;
    uart_rx_task.task_cb        = mxsp_uart_rx_task;
    uart_rx_task.task_name      = "mxsp_uart_rx";
    uart_rx_task.stack_size     = MESHX_UART_RX_TASK_STACK_SIZE;
    uart_rx_task.priority       = MESHX_UART_RX_TASK_PRIO;
    uart_rx_task.arg            = NULL;
    /* Create UART RX Task */
    meshx_task_create(&uart_rx_task);
 
    /* Register GPIO hosted event callback */
    meshx_gpio_register_hosted_event_cb(meshx_gpio_hosted_event_handler);
 
    return MESHX_SUCCESS;
}

meshx_serial_is_hosted_mode_enabled()

bool meshx_serial_is_hosted_mode_enabled

(

void

)

Check if hosted mode is enabled.

Returns

true if enabled, false otherwise

{
    return mxsp_ctx.hosted_mode_enabled;
}

meshx_serial_parse_byte()

void meshx_serial_parse_byte

(

uint8_t

data

)

Parse incoming byte stream for MXSP frames.

Parameters

data	Byte to parse

{
    switch (mxsp_ctx.state) {
        case STATE_SOF:
            if (data == MXSP_SOF) {
                mxsp_ctx.state = STATE_LEN;
                mxsp_ctx.rx_ptr = 0;
            }
            break;
        case STATE_LEN:
            mxsp_ctx.rx_frame.len = data;
            mxsp_ctx.state = STATE_TYPE;
            break;
        case STATE_TYPE:
            mxsp_ctx.rx_frame.type = data;
            if (mxsp_ctx.rx_frame.len == 0) {
                mxsp_ctx.state = STATE_CHECKSUM;
            } else {
                mxsp_ctx.state = STATE_PAYLOAD;
            }
            break;
        case STATE_PAYLOAD:
            mxsp_ctx.rx_frame.payload[mxsp_ctx.rx_ptr++] = data;
            if (mxsp_ctx.rx_ptr >= mxsp_ctx.rx_frame.len) {
                mxsp_ctx.state = STATE_CHECKSUM;
            }
            break;
        case STATE_CHECKSUM:
            mxsp_ctx.rx_frame.checksum = data;
            mxsp_ctx.state = STATE_EOF;
            break;
        case STATE_EOF:
            if (data == MXSP_EOF) {
                if (calculate_checksum(mxsp_ctx.rx_frame.len, mxsp_ctx.rx_frame.type, mxsp_ctx.rx_frame.payload) == mxsp_ctx.rx_frame.checksum) {
                    if (mxsp_ctx.rx_frame.type == MXSP_MSG_TYPE_EL_CMD_SEND) {
                        meshx_app_element_msg_header_t hdr;
                        if (mxsp_ctx.rx_frame.len >= sizeof(hdr)) {
                            memcpy(&hdr, mxsp_ctx.rx_frame.payload, sizeof(hdr));
                            meshx_send_msg_to_element(hdr.element_id, hdr.element_type, hdr.func_id,
                                                    mxsp_ctx.rx_frame.len - sizeof(hdr),
                                                    &mxsp_ctx.rx_frame.payload[sizeof(hdr)]);
                        }
                    } else if (mxsp_ctx.rx_frame.type == MXSP_MSG_TYPE_SYS_CMD_SEND) {
                        meshx_ctrl_msg_header_t hdr;
                        if (mxsp_ctx.rx_frame.len >= sizeof(hdr)) {
                            memcpy(&hdr, mxsp_ctx.rx_frame.payload, sizeof(hdr));
                            if (hdr.evt_id == MESHX_CTRL_EVT_NODE_RESET) {
                                meshx_platform_reset();
                            }
                        }
                    } else if (mxsp_ctx.rx_frame.type == MXSP_MSG_TYPE_HOSTED_MODE) {
                        if (mxsp_ctx.rx_frame.len == 1) {
                            bool enabled = (mxsp_ctx.rx_frame.payload[0] != 0);
                            mxsp_ctx.hosted_mode_enabled = enabled;
 
                            /* Notify GPIO subsystem about hosted mode change */
                            meshx_gpio_hosted_mode_t gpio_mode = enabled ?
                                MESHX_GPIO_MODE_HOSTED : MESHX_GPIO_MODE_NON_HOSTED;
                            meshx_err_t err = meshx_gpio_set_hosted_mode(gpio_mode);
                            if (err != MESHX_SUCCESS) {
                                MESHX_LOGE(MODULE_ID_COMMON, "Failed to set GPIO hosted mode: %d", err);
                            }
 
                            MESHX_LOGI(MODULE_ID_COMMON, "Hosted mode %s via API TLV command",
                                      enabled ? "enabled" : "disabled");
                        }
                    } else if (mxsp_ctx.rx_frame.type == MXSP_MSG_TYPE_GPIO_CMD) {
                        /* Handle GPIO command from host */
                        mxsp_handle_gpio_cmd(mxsp_ctx.rx_frame.payload, mxsp_ctx.rx_frame.len);
                    } else if (mxsp_ctx.rx_frame.type == MXSP_MSG_TYPE_GPIO_EVT) {
                        /* Handle GPIO event from host (interrupt notification) */
                        mxsp_handle_gpio_evt_from_host(mxsp_ctx.rx_frame.payload, mxsp_ctx.rx_frame.len);
                    }
                } else {
                    MESHX_LOGE(MODULE_ID_COMMON, "Invalid MXSP frame checksum");
                }
            }
            mxsp_ctx.state = STATE_SOF;
            break;
    }
}

meshx_serial_set_hosted_mode()

void meshx_serial_set_hosted_mode

(

bool

enabled

)

Set the hosted mode state.

Parameters

enabled

True to enable, false to disable

{
    mxsp_ctx.hosted_mode_enabled = enabled;
 
    /* Also update GPIO subsystem hosted mode */
    meshx_gpio_hosted_mode_t gpio_mode = enabled ?
        MESHX_GPIO_MODE_HOSTED : MESHX_GPIO_MODE_NON_HOSTED;
    meshx_gpio_set_hosted_mode(gpio_mode);
}

mxsp_send_ctrl_event()

meshx_err_t mxsp_send_ctrl_event	(	const meshx_ctrl_msg_header_t *	evt_header,
		const meshx_ctrl_payload_t *	payload )

Send a control event via MXSP.

Parameters

evt_header	Control message header
payload	Control message payload

Returns

meshx_err_t MESHX_SUCCESS on success

{
    if (!mxsp_ctx.hosted_mode_enabled) {
        return MESHX_SUCCESS;
    }
    uint8_t buff[sizeof(meshx_ctrl_msg_header_t) + sizeof(meshx_ctrl_payload_t)];
    uint8_t len = 0;
 
    memcpy(&buff[len], evt_header, sizeof(meshx_ctrl_msg_header_t));
    len += sizeof(meshx_ctrl_msg_header_t);
 
    // For simplicity, we send the whole payload union. In optimization, we could send only active part.
    memcpy(&buff[len], payload, sizeof(meshx_ctrl_payload_t));
    len += sizeof(meshx_ctrl_payload_t);
 
    return mxsp_send_frame(MXSP_MSG_TYPE_SYS_EVT_NOTIFY, buff, len);
}

mxsp_send_data_event()

meshx_err_t mxsp_send_data_event	(	const meshx_app_element_msg_header_t *	msg_hdr,
		const meshx_data_payload_t *	payload )

Send data event via MXSP.

Parameters

msg_hdr	Data message header
payload	Data message payload

Returns

meshx_err_t MESHX_SUCCESS on success

{
    if (!mxsp_ctx.hosted_mode_enabled) {
        return MESHX_SUCCESS;
    }
    uint8_t buff[sizeof(meshx_app_element_msg_header_t) + sizeof(meshx_data_payload_t)];
    uint8_t len = 0;
 
    memcpy(&buff[len], msg_hdr, sizeof(meshx_app_element_msg_header_t));
    len += sizeof(meshx_app_element_msg_header_t);
 
    memcpy(&buff[len], payload, sizeof(meshx_data_payload_t));
    len += sizeof(meshx_data_payload_t);
 
    return mxsp_send_frame(MXSP_MSG_TYPE_DATA_EVT_NOTIFY, buff, len);
}

mxsp_send_gpio_evt()

meshx_err_t mxsp_send_gpio_evt	(	uint8_t	event_type,
		uint8_t	logical_pin,
		uint8_t	value )

Send GPIO async event via MXSP.

Parameters

event_type	Event type (mxsp_gpio_evt_t)
logical_pin	Logical pin number
value	Event value

Returns

meshx_err_t MESHX_SUCCESS on success

{
    if (!mxsp_ctx.hosted_mode_enabled) {
        return MESHX_SUCCESS;
    }
 
    mxsp_gpio_evt_payload_t evt;
    memset(&evt, 0, sizeof(evt));
 
    evt.event_type = event_type;
    evt.logical_pin = logical_pin;
    evt.value = value;
    evt.reserved = 0;
    evt.timestamp = meshx_get_sys_time_ms();
 
    return mxsp_send_frame(MXSP_MSG_TYPE_GPIO_EVT, (const uint8_t*)&evt, sizeof(evt));
}

mxsp_send_gpio_rsp()

meshx_err_t mxsp_send_gpio_rsp	(	uint8_t	cmd,
		uint8_t	logical_pin,
		uint8_t	status,
		const uint8_t *	response,
		uint8_t	response_len )

Send GPIO response via MXSP.

Parameters

cmd	Original command type
logical_pin	Logical pin number
status	Status code (0 = success)
response	Response data
response_len	Response data length

Returns

meshx_err_t MESHX_SUCCESS on success

{
    if (!mxsp_ctx.hosted_mode_enabled) {
        return MESHX_SUCCESS;
    }
 
    mxsp_gpio_rsp_payload_t rsp;
    memset(&rsp, 0, sizeof(rsp));
 
    rsp.cmd = cmd;
    rsp.logical_pin = logical_pin;
    rsp.status = status;
    rsp.response_len = (response_len > 8) ? 8 : response_len;
    if (response != NULL && rsp.response_len > 0) {
        memcpy(rsp.response, response, rsp.response_len);
    }
 
    return mxsp_send_frame(MXSP_MSG_TYPE_GPIO_RSP, (const uint8_t*)&rsp, sizeof(rsp));
}