sACN

sACN: A Streaming ACN (sACN) implementation. More...

Topics
	sACN DMX Merger
	The sACN DMX Merger API; see Using the sACN DMX Merger API.
	sACN Merge Receiver
	The sACN Merge Receiver API; see Using the sACN Merge Receiver API.
	sACN Receiver
	The sACN Receiver API; see Using the sACN Receiver API.
	sACN Source
	The sACN Source API; see Using the sACN Source API.
	sACN Source Detector
	The sACN Source Detector API.
	sACN Configuration Options
	Compile-time configuration options for sACN.

Data Structures
struct	SacnMcastInterface
struct	SacnNetintConfig

Macros
#define	SACN_SOURCE_NAME_MAX_LEN   64
	The maximum length of an sACN source name, including the null-terminator.
#define	DMX_ADDRESS_COUNT   512
#define	SACN_REMOTE_SOURCE_INVALID   ((sacn_remote_source_t)-1)
#define	SACN_STARTCODE_DMX   0x00u
#define	SACN_STARTCODE_PRIORITY   0xddu

Typedefs
typedef uint16_t	sacn_remote_source_t
typedef struct SacnMcastInterface	SacnMcastInterface
typedef struct SacnNetintConfig	SacnNetintConfig

Enumerations
enum	sacn_ip_support_t { kSacnIpV4Only , kSacnIpV6Only , kSacnIpV4AndIpV6 }

Functions
etcpal_error_t	sacn_init (const EtcPalLogParams *log_params, const SacnNetintConfig *sys_netint_config)
	Initialize the sACN library.
void	sacn_deinit (void)
	Deinitialize the sACN library.
sacn_remote_source_t	sacn_get_remote_source_handle (const EtcPalUuid *source_cid)
	Converts a remote source CID to the corresponding handle, or SACN_REMOTE_SOURCE_INVALID if not found.
etcpal_error_t	sacn_get_remote_source_cid (sacn_remote_source_t source_handle, EtcPalUuid *source_cid)
	Converts a remote source handle to the corresponding source CID.

sACN version numbers
#define	SACN_VERSION_MAJOR   2
#define	SACN_VERSION_MINOR   0
#define	SACN_VERSION_PATCH   2
#define	SACN_VERSION_BUILD   3

sACN version strings
#define	SACN_VERSION_STRING   "2.0.2.3"
#define	SACN_VERSION_DATESTR   "17.Aug.2022"
#define	SACN_VERSION_COPYRIGHT   "Copyright 2022 ETC Inc."
#define	SACN_VERSION_PRODUCTNAME   "sACN"

Detailed Description

sACN: A Streaming ACN (sACN) implementation.

Macro Definition Documentation

DMX_ADDRESS_COUNT

#define DMX_ADDRESS_COUNT   512

The number of addresses in a DMX universe.

SACN_REMOTE_SOURCE_INVALID

#define SACN_REMOTE_SOURCE_INVALID   ((sacn_remote_source_t)-1)

An invalid remote source handle value.

SACN_SOURCE_NAME_MAX_LEN

#define SACN_SOURCE_NAME_MAX_LEN   64

The maximum length of an sACN source name, including the null-terminator.

E1.31 specifies that the Source Name field must be null-terminated on the wire.

SACN_STARTCODE_DMX

#define SACN_STARTCODE_DMX   0x00u

The DMX start code.

SACN_STARTCODE_PRIORITY

#define SACN_STARTCODE_PRIORITY   0xddu

The per-address priority start code.

SACN_VERSION_BUILD

#define SACN_VERSION_BUILD   3

The build number.

SACN_VERSION_COPYRIGHT

#define SACN_VERSION_COPYRIGHT   "Copyright 2022 ETC Inc."

The version's copyright string.

SACN_VERSION_DATESTR

#define SACN_VERSION_DATESTR   "17.Aug.2022"

The date this version was released (dd.Mm.yyyy).

SACN_VERSION_MAJOR

#define SACN_VERSION_MAJOR   2

The major version.

SACN_VERSION_MINOR

#define SACN_VERSION_MINOR   0

The minor version.

SACN_VERSION_PATCH

#define SACN_VERSION_PATCH   2

The patch version.

SACN_VERSION_PRODUCTNAME

#define SACN_VERSION_PRODUCTNAME   "sACN"

The version's product name.

SACN_VERSION_STRING

#define SACN_VERSION_STRING   "2.0.2.3"

The 4-digit version string.

Typedef Documentation

sacn_remote_source_t

typedef uint16_t sacn_remote_source_t

A source discovered on an sACN network that has a CID - used by Receiver and Merge Receiver.

SacnMcastInterface

typedef struct SacnMcastInterface SacnMcastInterface

On input, this structure is used to indicate a network interface to use. On output, this structure indicates whether or not the operation was a success.

SacnNetintConfig

typedef struct SacnNetintConfig SacnNetintConfig

Network interface configuration information to give the sACN library. Multicast traffic will be restricted to the network interfaces given. The statuses are filled in for each interface.

Enumeration Type Documentation

sacn_ip_support_t

enum sacn_ip_support_t

This enum defines how the API module will use IPv4 and IPv6 networking.

Enumerator
kSacnIpV4Only	Use IPv4 only.
kSacnIpV6Only	Use IPv6 only.
kSacnIpV4AndIpV6	Use both IPv4 and IPv6.

Function Documentation

sacn_deinit()

void sacn_deinit

(

void

)

Deinitialize the sACN library.

Set the sACN library back to an uninitialized state. Calls to other sACN API functions will fail until sacn_init() is called again.

This function is not thread safe with respect to other sACN API functions. Make sure to join your threads that use the APIs before calling this.

sacn_get_remote_source_cid()

etcpal_error_t sacn_get_remote_source_cid	(	sacn_remote_source_t	source_handle,
		EtcPalUuid *	source_cid )

Converts a remote source handle to the corresponding source CID.

Parameters

[in]	source_handle	The handle of the remote source.
[out]	source_cid	The UUID of the source CID. Only written to if kEtcPalErrOk is returned.

Returns

kEtcPalErrOk: Lookup was successful.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrNotFound: The source handle does not match a source that was found by a receiver, merge receiver, or source detector.

kEtcPalErrSys: An internal library or system call error occurred.

sacn_get_remote_source_handle()

sacn_remote_source_t sacn_get_remote_source_handle

(

const EtcPalUuid *

source_cid

)

Converts a remote source CID to the corresponding handle, or SACN_REMOTE_SOURCE_INVALID if not found.

This is a simple conversion from a remote source CID to it's corresponding remote source handle. A handle will be returned only if it is a source that has been discovered by a receiver, merge receiver, or source detector.

Parameters

[in]

source_cid

The UUID of the remote source CID.

Returns

The remote source handle, or SACN_REMOTE_SOURCE_INVALID if not found.

sacn_init()

etcpal_error_t sacn_init	(	const EtcPalLogParams *	log_params,
		const SacnNetintConfig *	sys_netint_config )

Initialize the sACN library.

Do all necessary initialization before other sACN API functions can be called.

Parameters

[in]	log_params	A struct used by the library to log messages, or NULL for no logging. If SACN_LOGGING_ENABLED is 0, this parameter is ignored.
[in,out]	sys_netint_config	Optional. If non-NULL, this is the list of system interfaces the library will be limited to, and the status codes are filled in. If NULL, the library is allowed to use all available system interfaces.

Returns

kEtcPalErrOk: Initialization successful.

kEtcPalErrInvalid: Invalid parameter provided.

kEtcPalErrSys: An internal library or system call error occurred.