serial.h File Reference

Utility functions used by the UART and shell mcumgr transports. More...

#include <zephyr/types.h>

Go to the source code of this file.

Data Structures
struct	mcumgr_serial_rx_ctxt
	Maintains state for an incoming mcumgr request packet. More...

Macros
#define	MCUMGR_SERIAL_HDR_PKT   0x0609
#define	MCUMGR_SERIAL_HDR_FRAG   0x0414
#define	MCUMGR_SERIAL_MAX_FRAME   128
#define	MCUMGR_SERIAL_HDR_PKT_1   (MCUMGR_SERIAL_HDR_PKT >> 8)
#define	MCUMGR_SERIAL_HDR_PKT_2   (MCUMGR_SERIAL_HDR_PKT & 0xff)
#define	MCUMGR_SERIAL_HDR_FRAG_1   (MCUMGR_SERIAL_HDR_FRAG >> 8)
#define	MCUMGR_SERIAL_HDR_FRAG_2   (MCUMGR_SERIAL_HDR_FRAG & 0xff)

Typedefs
typedef int(*	mcumgr_serial_tx_cb) (const void *data, int len, void *arg)
	Transmits a chunk of raw response data. More...

Functions
struct net_buf *	mcumgr_serial_process_frag (struct mcumgr_serial_rx_ctxt *rx_ctxt, const uint8_t *frag, int frag_len)
	Processes an mcumgr request fragment received over a serial transport. More...
int	mcumgr_serial_tx_pkt (const uint8_t *data, int len, mcumgr_serial_tx_cb cb, void *arg)
	Encodes and transmits an mcumgr packet over serial. More...

Detailed Description

Utility functions used by the UART and shell mcumgr transports.

Mcumgr packets sent over serial are fragmented into frames of 128 bytes or fewer.

The initial frame in a packet has the following format: offset 0: 0x06 0x09 === Begin base64 encoding === offset 2: {16-bit packet-length} offset ?: {body} offset ?: {crc16} (if final frame) === End base64 encoding === offset ?: 0x0a (newline)

All subsequent frames have the following format: offset 0: 0x04 0x14 === Begin base64 encoding === offset 2: {body} offset ?: {crc16} (if final frame) === End base64 encoding === offset ?: 0x0a (newline)

All integers are represented in big-endian. The packet fields are described below:

Field	Description
0x06 0x09	Byte pair indicating the start of a packet.
0x04 0x14	Byte pair indicating the start of a continuation frame.
Packet length	The combined total length of the unencoded body plus
	the final CRC (2 bytes). Length is in Big-Endian format.
Body	The actual SMP data (i.e., 8-byte header and CBOR
	key-value map).
CRC16	A CRC16 of the unencoded body of the entire packet.
	This field is only present in the final frame of a
	packet.
Newline	A 0x0a byte; terminates a frame.

The packet is fully received when {packet-length} bytes of body has been received.

CRC details

The CRC16 should be calculated with the following parameters:

Field	Value
Polynomial	0x1021
Initial Value	0

Macro Definition Documentation

MCUMGR_SERIAL_HDR_FRAG

#define MCUMGR_SERIAL_HDR_FRAG   0x0414

MCUMGR_SERIAL_HDR_FRAG_1

#define MCUMGR_SERIAL_HDR_FRAG_1   (MCUMGR_SERIAL_HDR_FRAG >> 8)

MCUMGR_SERIAL_HDR_FRAG_2

#define MCUMGR_SERIAL_HDR_FRAG_2   (MCUMGR_SERIAL_HDR_FRAG & 0xff)

MCUMGR_SERIAL_HDR_PKT

#define MCUMGR_SERIAL_HDR_PKT   0x0609

MCUMGR_SERIAL_HDR_PKT_1

#define MCUMGR_SERIAL_HDR_PKT_1   (MCUMGR_SERIAL_HDR_PKT >> 8)

MCUMGR_SERIAL_HDR_PKT_2

#define MCUMGR_SERIAL_HDR_PKT_2   (MCUMGR_SERIAL_HDR_PKT & 0xff)

MCUMGR_SERIAL_MAX_FRAME

#define MCUMGR_SERIAL_MAX_FRAME   128

Typedef Documentation

mcumgr_serial_tx_cb

mcumgr_serial_tx_cb

Transmits a chunk of raw response data.

Parameters

data	The data to transmit.
len	The number of bytes to transmit.
arg	An optional argument.

Returns

0 on success; negative error code on failure.

Function Documentation

mcumgr_serial_process_frag()

struct net_buf * mcumgr_serial_process_frag	(	struct mcumgr_serial_rx_ctxt *	rx_ctxt,
		const uint8_t *	frag,
		int	frag_len
	)

Processes an mcumgr request fragment received over a serial transport.

Processes an mcumgr request fragment received over a serial transport. If the fragment is the end of a valid mcumgr request, this function returns a net_buf containing the decoded request. It is the caller's responsibility to free the net_buf after it has been processed.

Parameters

rx_ctxt	The receive context associated with the serial transport being used.
frag	The incoming fragment to process.
frag_len	The length of the fragment, in bytes.

Returns

A net_buf containing the decoded request if a complete and valid request has been received. NULL if the packet is incomplete or invalid.

mcumgr_serial_tx_pkt()

int mcumgr_serial_tx_pkt	(	const uint8_t *	data,
		int	len,
		mcumgr_serial_tx_cb	cb,
		void *	arg
	)

Encodes and transmits an mcumgr packet over serial.

Parameters

data	The mcumgr packet data to send.
len	The length of the unencoded mcumgr packet.
cb	A callback used to transmit raw bytes.
arg	An optional argument to pass to the callback.

Returns

0 on success; negative error code on failure.