Group dxl2_link¶

Transport-independent link that owns a parser and dispatches packets. More...

Classes¶

Type	Name
struct	dxl2_link Link state.
struct	dxl2_link_config Link configuration passed to dxl2_link_init .

Public Types¶

Type	Name
typedef void(*	dxl2_packet_handler_t Handle one valid packet received by the link.
typedef int(*	dxl2_write_fn Write a complete wire packet to the transport.

Public Functions¶

Type	Name
int	dxl2_link_init (struct dxl2_link * link, const struct dxl2_link_config * config) Initialize a link and reset its parser and counters.
uint32_t	dxl2_link_invalid_packets (const struct dxl2_link * link) Number of malformed or CRC-invalid packets rejected since dxl2_link_init .
void	dxl2_link_receive (struct dxl2_link * link, const uint8_t * data, size_t length) Feed received bytes; calls the handler for each complete valid packet.
uint32_t	dxl2_link_rx_packets (const struct dxl2_link * link) Number of valid packets received since dxl2_link_init .
int	dxl2_link_send (struct dxl2_link * link, uint8_t id, uint8_t instruction, const uint8_t * parameters, uint16_t parameter_length) Encode one packet (stuffing and CRC added) and write it.
int	dxl2_link_send_status (struct dxl2_link * link, uint8_t id, uint8_t error, const uint8_t * data, uint16_t data_length) Send a Status Packet: error byte followed by `data` .

Detailed Description¶

The link owns a parser, dispatches every valid packet to a handler, and encodes outgoing packets into a caller-supplied write function. It has no RTOS or driver dependency: the integrator moves received bytes from the UART/USB/socket into dxl2_link_receive and provides the byte writer.

A link is not thread-safe. Call dxl2_link_receive from one context only (for example an RX thread, not an interrupt handler), and serialize dxl2_link_send calls from several contexts with a mutex.

** **

Lifecycle: dxl2_link_init.
Message flow: dxl2_link_receive, dxl2_link_send, dxl2_link_send_status.
Diagnostics: dxl2_link_rx_packets, dxl2_link_invalid_packets.

Public Types Documentation¶

typedef dxl2_packet_handler_t¶

Handle one valid packet received by the link.

typedef void(* dxl2_packet_handler_t) (const struct dxl2_packet *packet, void *context);

The packet pointer is valid only for the duration of the callback. Copy any data that must be retained after the callback returns. The handler may call dxl2_link_send on the same link to answer.

Parameters:

packet Decoded packet with byte stuffing removed.
context Value of dxl2_link_config::handler_context.

typedef dxl2_write_fn¶

Write a complete wire packet to the transport.

typedef int(* dxl2_write_fn) (void *context, const uint8_t *data, size_t length);

Parameters:

context Value of dxl2_link_config::write_context.
data Encoded packet, including header and CRC.
length Number of bytes in data.

Returns:

0 on success, a negative value on failure (returned by the send call).

Public Functions Documentation¶

function dxl2_link_init¶

Initialize a link and reset its parser and counters.

int dxl2_link_init (
    struct dxl2_link * link,
    const struct dxl2_link_config * config
)

Parameters:

link Link state to initialize.
config Configuration copied into the link.

Return value:

0 Link ready.
DXL2_PARSE_ERROR link or config is NULL.

function dxl2_link_invalid_packets¶

Number of malformed or CRC-invalid packets rejected since dxl2_link_init .

uint32_t dxl2_link_invalid_packets (
    const struct dxl2_link * link
)

function dxl2_link_receive¶

Feed received bytes; calls the handler for each complete valid packet.

void dxl2_link_receive (
    struct dxl2_link * link,
    const uint8_t * data,
    size_t length
)

Bytes may arrive in any chunking. Malformed or CRC-invalid packets are dropped and counted, and the parser resynchronizes on the next header.

Parameters:

link Link state.
data Received bytes; may be NULL only when length is zero.
length Number of bytes in data.

function dxl2_link_rx_packets¶

Number of valid packets received since dxl2_link_init .

uint32_t dxl2_link_rx_packets (
    const struct dxl2_link * link
)

function dxl2_link_send¶

Encode one packet (stuffing and CRC added) and write it.

int dxl2_link_send (
    struct dxl2_link * link,
    uint8_t id,
    uint8_t instruction,
    const uint8_t * parameters,
    uint16_t parameter_length
)

Parameters:

link Link state.
id Destination ID.
instruction Instruction byte.
parameters Unstuffed parameters, or NULL when parameter_length is zero.
parameter_length Number of parameter bytes.

Return value:

0 Packet written.
DXL2_PARSE_ERROR Invalid arguments, packet too large, or no writer.
Other negative value Error returned by the write function.

function dxl2_link_send_status¶

Send a Status Packet: error byte followed by data .

int dxl2_link_send_status (
    struct dxl2_link * link,
    uint8_t id,
    uint8_t error,
    const uint8_t * data,
    uint16_t data_length
)

Parameters:

link Link state.
id ID of the answering device.
error Status error byte (DXL2_ERR_*, optionally with DXL2_ERR_ALERT_BIT).
data Status data, or NULL when data_length is zero.
data_length Number of data bytes (at most DXL2_MAX_PARAMETER_SIZE - 1).

Returns:

Same as dxl2_link_send.