Overview

Parse or pack a PDU or PDU block as defined in ANSI E1.17 (ACN).

#include "etcpal/acn_pdu.h"

This module handles building and parsing the ACN PDU format as defined in ANSI E1.17, ACN Architecture document, § 2. EtcPal supports a few different ACN protocol family libraries, including sACN and RDMnet, so it's convenient to have this logic here.

Data Structures
struct	AcnPdu
	Holds state data used when parsing multiple PDUs in a PDU block. More...

struct	AcnPduConstraints
	Contains specific PDU info used by the generic helper acn_parse_pdu(). More...

Macros
#define	ACN_PDU_LENGTH(pdu_buf)
	Get the length from the Length field of an ACN PDU. More...

#define	ACN_PDU_PACK_NORMAL_LEN(pdu_buf, length)
	Fill in the Length field of an ACN PDU which has a length less than 4096. More...

#define	ACN_PDU_PACK_EXT_LEN(pdu_buf, length)
	Fill in the Length field of an ACN PDU which has a length 4096 or greater. More...

#define	ACN_PDU_INIT
	Default AcnPdu initializer values; must be used to intialize an AcnPdu when parsing the first PDU in a block. More...

#define	ACN_INIT_PDU(pduptr)
	An alternative to ACN_PDU_INIT which can be used on an existing AcnPdu to re-initialize its values. More...

Typedefs
typedef struct AcnPdu	AcnPdu
	Holds state data used when parsing multiple PDUs in a PDU block.

typedef struct AcnPduConstraints	AcnPduConstraints
	Contains specific PDU info used by the generic helper acn_parse_pdu().

Functions
bool	acn_parse_pdu (const uint8_t buf, size_t buflen, const AcnPduConstraints constraints, AcnPdu *pdu)
	Parse a generic ACN PDU. More...

Get the inheritance and length bits in an ACN PDU Flags & Length segment.
The first byte of each PDU contains a flags field which indicates the inheritance properties of that PDU. For more information, see ANSI E1.17, ACN Architecture, § 2.4.
#define	ACN_PDU_L_FLAG_SET(flags_byte) ((bool)((flags_byte)&0x80u))
	Determine whether the L flag is set in an ACN PDU flags field. More...

#define	ACN_PDU_V_FLAG_SET(flags_byte) ((bool)((flags_byte)&0x40u))
	Determine whether the V flag is set in an ACN PDU flags field. More...

#define	ACN_PDU_H_FLAG_SET(flags_byte) ((bool)((flags_byte)&0x20u))
	Determine whether the H flag is set in an ACN PDU flags field. More...

#define	ACN_PDU_D_FLAG_SET(flags_byte) ((bool)((flags_byte)&0x10u))
	Determine whether the D flag is set in an ACN PDU flags field. More...

Set the inheritance and length bits in a PDU Flags & Length segment.
The first byte of each PDU contains a flags field which indicates the inheritance properties of that PDU. For more information, see ANSI E1.17, ACN Architecture, § 2.4.
#define	ACN_PDU_SET_L_FLAG(flags_byte) (flags_byte \|= 0x80u)
	Set the L flag in an ACN PDU flags field. More...

#define	ACN_PDU_SET_V_FLAG(flags_byte) (flags_byte \|= 0x40u)
	Set the V flag in an ACN PDU flags field. More...

#define	ACN_PDU_SET_H_FLAG(flags_byte) (flags_byte \|= 0x20u)
	Set the H flag in an ACN PDU flags field. More...

#define	ACN_PDU_SET_D_FLAG(flags_byte) (flags_byte \|= 0x10u)
	Set the D flag in an ACN PDU flags field. More...

Macro Definition Documentation

◆ ACN_INIT_PDU

#define ACN_INIT_PDU ( pduptr )

Value:

  do                           \
  {                            \
    (pduptr)->pvector  = NULL; \
    (pduptr)->pheader  = NULL; \
    (pduptr)->pdata    = NULL; \
    (pduptr)->data_len = 0;    \
    (pduptr)->pnextpdu = NULL; \
  } while (0)

An alternative to ACN_PDU_INIT which can be used on an existing AcnPdu to re-initialize its values.

Parameters

pduptr Pointer to AcnPdu to initialize.

◆ ACN_PDU_D_FLAG_SET

#define ACN_PDU_D_FLAG_SET ( flags_byte ) ((bool)((flags_byte)&0x10u))

Determine whether the D flag is set in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

Returns: true (the D flag is set) or false (the D flag is not set).

◆ ACN_PDU_H_FLAG_SET

#define ACN_PDU_H_FLAG_SET ( flags_byte ) ((bool)((flags_byte)&0x20u))

Determine whether the H flag is set in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

Returns: true (the H flag is set) or false (the H flag is not set).

◆ ACN_PDU_INIT

#define ACN_PDU_INIT

Value:

  {                           \
    NULL, NULL, NULL, 0, NULL \
  }

Default AcnPdu initializer values; must be used to intialize an AcnPdu when parsing the first PDU in a block.

◆ ACN_PDU_L_FLAG_SET

#define ACN_PDU_L_FLAG_SET ( flags_byte ) ((bool)((flags_byte)&0x80u))

Determine whether the L flag is set in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

Returns: true (the L flag is set) or false (the L flags is not set).

◆ ACN_PDU_LENGTH

#define ACN_PDU_LENGTH ( pdu_buf )

Value:

  ((uint32_t)(ACN_PDU_L_FLAG_SET(pdu_buf[0])                                                                      \
                  ? ((uint32_t)((pdu_buf[0] & 0x0fu) << 16) | (uint32_t)(pdu_buf[1] << 8) | (uint32_t)pdu_buf[2]) \
                  : ((uint32_t)((pdu_buf[0] & 0x0fu) << 8) | (uint32_t)pdu_buf[1])))

Get the length from the Length field of an ACN PDU.

Parameters

pdu_buf Pointer to the start of the PDU buffer.

Returns: The length of the PDU.

◆ ACN_PDU_PACK_EXT_LEN

#define ACN_PDU_PACK_EXT_LEN	(	pdu_buf,
		length
	)

Value:

  do                                                                              \
  {                                                                               \
    (pdu_buf)[0] = (uint8_t)(((pdu_buf)[0] & 0xf0) | (((length) >> 16) & 0x0fu)); \
    (pdu_buf)[1] = (uint8_t)(((length) >> 8) & 0xffu);                            \
    (pdu_buf)[2] = (uint8_t)(length)&0xffu;                                       \
  } while (0)

Fill in the Length field of an ACN PDU which has a length 4096 or greater.

The L flag of this PDU must be set to 1.

Parameters

pdu_buf	Pointer to the start of the PDU buffer.
length	Length of this PDU.

◆ ACN_PDU_PACK_NORMAL_LEN

#define ACN_PDU_PACK_NORMAL_LEN	(	pdu_buf,
		length
	)

Value:

  do                                                                             \
  {                                                                              \
    (pdu_buf)[0] = (uint8_t)(((pdu_buf)[0] & 0xf0) | (((length) >> 8) & 0x0fu)); \
    (pdu_buf)[1] = (uint8_t)(length)&0xffu;                                      \
  } while (0)

Fill in the Length field of an ACN PDU which has a length less than 4096.

The L flag of this PDU must be set to 0.

Parameters

pdu_buf	Pointer to the start of the PDU buffer.
length	Length of this PDU.

◆ ACN_PDU_SET_D_FLAG

#define ACN_PDU_SET_D_FLAG ( flags_byte ) (flags_byte |= 0x10u)

Set the D flag in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

◆ ACN_PDU_SET_H_FLAG

#define ACN_PDU_SET_H_FLAG ( flags_byte ) (flags_byte |= 0x20u)

Set the H flag in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

◆ ACN_PDU_SET_L_FLAG

#define ACN_PDU_SET_L_FLAG ( flags_byte ) (flags_byte |= 0x80u)

Set the L flag in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

◆ ACN_PDU_SET_V_FLAG

#define ACN_PDU_SET_V_FLAG ( flags_byte ) (flags_byte |= 0x40u)

Set the V flag in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

◆ ACN_PDU_V_FLAG_SET

#define ACN_PDU_V_FLAG_SET ( flags_byte ) ((bool)((flags_byte)&0x40u))

Determine whether the V flag is set in an ACN PDU flags field.

Parameters

flags_byte The first byte of the PDU.

Returns: true (the V flag is set) or false (the V flag is not set).

Function Documentation

◆ acn_parse_pdu()

bool acn_parse_pdu	(	const uint8_t *	buf,
		size_t	buflen,
		const AcnPduConstraints *	constraints,
		AcnPdu *	pdu
	)

Parse a generic ACN PDU.

A function to parse a generic ACN PDU. The specific PDU info needed for parsing is contained in a struct AcnPduConstraints. Uses AcnPdu to maintain state across multiple PDUs in a block.

Parameters

[in]	buf	Byte buffer containing a PDU.
[in]	buflen	Size in bytes of buf.
[in]	constraints	Specific information about the PDU being parsed
[in,out]	pdu	PDU data from the last PDU in the block. The data is used and then replaced with data from this PDU.

Returns: true (PDU was parsed successfully) or false (parse error or no more PDUs in the block).

Overview

Data Structures

Macros

Typedefs

Functions

Get the inheritance and length bits in an ACN PDU Flags & Length segment.

Set the inheritance and length bits in a PDU Flags & Length segment.

Macro Definition Documentation

◆ ACN_INIT_PDU

◆ ACN_PDU_D_FLAG_SET

◆ ACN_PDU_H_FLAG_SET

◆ ACN_PDU_INIT

◆ ACN_PDU_L_FLAG_SET

◆ ACN_PDU_LENGTH

◆ ACN_PDU_PACK_EXT_LEN

◆ ACN_PDU_PACK_NORMAL_LEN

◆ ACN_PDU_SET_D_FLAG

◆ ACN_PDU_SET_H_FLAG

◆ ACN_PDU_SET_L_FLAG

◆ ACN_PDU_SET_V_FLAG

◆ ACN_PDU_V_FLAG_SET

Function Documentation

◆ acn_parse_pdu()