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 Configuration Options
	Compile-time configuration options for sACN.

	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

Classes
struct	SacnMcastInterface
	On input, this structure is used to indicate a network interface to use. More...

struct	SacnSendSocketConfig
	Configuration for send sockets (e.g. More...

struct	SacnNetintConfig
	Network interface configuration information to give the sACN library. More...

struct	SacnSocketErrorInfo
	Information about a socket error that occurred. More...

struct	SacnCommonCallbacks
	A set of callback functions that the library uses to notify the application about sACN events. More...

Macros
#define	SACN_SEND_SOCKET_CONFIG_DEFAULT_VALUES 0, 0, kSacnIpV4AndIpV6
	Default values for initializing a SacnSendSocketConfig.

#define	SACN_SEND_SOCKET_CONFIG_DEFAULT_INIT {SACN_SEND_SOCKET_CONFIG_DEFAULT_VALUES}
	Initializes the members of a SacnSendSocketConfig to defaults.

#define	SACN_NETINT_CONFIG_DEFAULT_INIT {NULL, 0, false, SACN_SEND_SOCKET_CONFIG_DEFAULT_INIT}
	Initializes the members of a SacnNetintConfig to defaults.

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

typedef struct SacnMcastInterface	SacnMcastInterface
	On input, this structure is used to indicate a network interface to use.

typedef struct SacnSendSocketConfig	SacnSendSocketConfig
	Configuration for send sockets (e.g.

typedef struct SacnNetintConfig	SacnNetintConfig
	Network interface configuration information to give the sACN library.

typedef struct SacnSocketErrorInfo	SacnSocketErrorInfo
	Information about a socket error that occurred.

typedef void(*	SacnUnicastSendErrorCallback) (const SacnSocketErrorInfo err_info, void context)
	Notify that an error just occurred sending unicast on a socket.

typedef void(*	SacnMulticastSendErrorCallback) (const SacnSocketErrorInfo err_info, void context)
	Notify that an error just occurred sending multicast on a socket.

typedef struct SacnCommonCallbacks	SacnCommonCallbacks
	A set of callback functions that the library uses to notify the application about sACN events.

typedef uint32_t	sacn_features_t
	A mask of desired sACN features.

Enumerations
enum	{ kSacnSourceNameMaxLen = 64 , kSacnDmxAddressCount = 512 , kSacnStartcodeDmx = 0x00u , kSacnStartcodePriority = 0xddu , kSacnMinimumUniverse = 1 , kSacnMaximumUniverse = 63999 }

enum	sacn_ip_support_t { kSacnIpV4Only , kSacnIpV6Only , kSacnIpV4AndIpV6 }
	This enum defines how the API module will use IPv4 and IPv6 networking. More...

Functions
etcpal_error_t	sacn_init (const EtcPalLogParams log_params, const SacnNetintConfig sys_netint_config)
	Initialize all features of the sACN library.

etcpal_error_t	sacn_init_with_cb (const EtcPalLogParams log_params, const SacnNetintConfig sys_netint_config, const SacnCommonCallbacks *callbacks)
	Initialize all features of the sACN library.

etcpal_error_t	sacn_init_features (const EtcPalLogParams log_params, const SacnNetintConfig sys_netint_config, sacn_features_t features)
	Initialize specific features of the sACN library.

etcpal_error_t	sacn_init_features_with_cb (const EtcPalLogParams log_params, const SacnNetintConfig sys_netint_config, sacn_features_t features, const SacnCommonCallbacks *callbacks)
	Initialize specific features of the sACN library.

void	sacn_deinit (void)
	Deinitialize all features of the sACN library.

void	sacn_deinit_features (sacn_features_t features)
	Deinitialize specific features of 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 kSacnRemoteSourceInvalid 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.

Variables
static const sacn_remote_source_t	kSacnRemoteSourceInvalid = 0xFFFF
	An invalid remote source handle value.

sACN feature masks
Pass one or more of these to sacn_init_features() to initialize the relevant sACN feature. Multiple features can be requested using logical OR. Currently the DMX merger is the only feature that can be initialized individually. All other APIs can later be initialized with SACN_FEATURES_ALL, which represents all APIs regardless if they have an individual feature defined for them. Redundant initialization will ensure the same feature isn't initialized twice.
#define	SACN_FEATURE_DMX_MERGER ((sacn_features_t)(1u << 0))
	Use the sacn/dmx_merger module.

#define	SACN_FEATURES_ALL 0xffffffffu
	Use every available module.

sACN version numbers
#define	SACN_VERSION_MAJOR 4
	The major version.

#define	SACN_VERSION_MINOR 0
	The minor version.

#define	SACN_VERSION_PATCH 0
	The patch version.

#define	SACN_VERSION_BUILD 6
	The build number.

sACN version strings
#define	SACN_VERSION_STRING "4.0.0.6"
	The 4-digit version string.

#define	SACN_VERSION_DATESTR "15.Jun.2026"
	The date this version was released (dd.Mm.yyyy).

#define	SACN_VERSION_COPYRIGHT "Copyright 2026 ETC Inc."
	The version's copyright string.

#define	SACN_VERSION_PRODUCTNAME "sACN"
	The version's product name.

Detailed Description

sACN: A Streaming ACN (sACN) implementation.

Typedef Documentation

◆ sacn_features_t

typedef uint32_t sacn_features_t

A mask of desired sACN features.

See "sACN feature masks".

◆ 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.

◆ SacnMulticastSendErrorCallback

typedef void(* SacnMulticastSendErrorCallback) (const SacnSocketErrorInfo *err_info, void *context)

Notify that an error just occurred sending multicast on a socket.

The lock is taken when this callback is invoked, so don't call back into the library, and don't take too long.

Parameters

[in]	err_info	Information about the error that occurred.
[in]	context	Context pointer that was given to sacn_init().

◆ 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.

◆ SacnSendSocketConfig

typedef struct SacnSendSocketConfig SacnSendSocketConfig

Configuration for send sockets (e.g.

configurable sockopts).

◆ SacnUnicastSendErrorCallback

typedef void(* SacnUnicastSendErrorCallback) (const SacnSocketErrorInfo *err_info, void *context)

Notify that an error just occurred sending unicast on a socket.

The lock is taken when this callback is invoked, so don't call back into the library, and don't take too long.

Parameters

[in]	err_info	Information about the error that occurred.
[in]	context	Context pointer that was given to sacn_init().

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumerator
kSacnSourceNameMaxLen	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.
kSacnDmxAddressCount	The number of addresses in a DMX universe.
kSacnStartcodeDmx	The DMX start code.
kSacnStartcodePriority	The per-address priority start code.
kSacnMinimumUniverse	The lowest sACN universe number supported.
kSacnMaximumUniverse	The highest sACN universe number supported.

◆ 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 all features of the sACN library.

Set all sACN library features back to an uninitialized state if deinit is called as many times as init for a given feature. Calls to deinitialized sACN API functions will fail until sacn_init() is called again for their feature(s).

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_deinit_features()

void sacn_deinit_features ( sacn_features_t features )

Deinitialize specific features of the sACN library.

Set specific sACN library feature(s) back to an uninitialized state if deinit is called as many times as init for a given feature. Calls to deinitialized sACN API functions will fail until sacn_init() is called again for their feature(s).

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.

Parameters

[in] features Mask of sACN features to deinitialize.

◆ 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 kSacnRemoteSourceInvalid 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 kSacnRemoteSourceInvalid if not found.

◆ sacn_init()

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

Initialize all features of the sACN library.

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

Redundant initialization is permitted - the library tracks counters for each feature and expects deinit to be called the same number of times as init for each feature.

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 (with the added option of not allowing any interfaces to be used), 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.

◆ sacn_init_features()

etcpal_error_t sacn_init_features	(	const EtcPalLogParams *	log_params,
		const SacnNetintConfig *	sys_netint_config,
		sacn_features_t	features )

Initialize specific features of the sACN library.

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

Redundant initialization of features is permitted - the library tracks counters for each feature and expects deinit to be called the same number of times as init for each feature.

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 (with the added option of not allowing any interfaces to be used), and the status codes are filled in. If NULL, the library is allowed to use all available system interfaces.
[in]	features	Mask of sACN features to initialize.

Returns: kEtcPalErrOk: Initialization successful.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_init_features_with_cb()

etcpal_error_t sacn_init_features_with_cb	(	const EtcPalLogParams *	log_params,
		const SacnNetintConfig *	sys_netint_config,
		sacn_features_t	features,
		const SacnCommonCallbacks *	callbacks )

Initialize specific features of the sACN library.

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

Redundant initialization of features is permitted - the library tracks counters for each feature and expects deinit to be called the same number of times as init for each feature.

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 (with the added option of not allowing any interfaces to be used), and the status codes are filled in. If NULL, the library is allowed to use all available system interfaces.
[in]	features	Mask of sACN features to initialize.
[in]	callbacks	Optional. A struct of callback functions for the library to use to notify the application of events.

Returns: kEtcPalErrOk: Initialization successful.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrSys: An internal library or system call error occurred.

◆ sacn_init_with_cb()

etcpal_error_t sacn_init_with_cb	(	const EtcPalLogParams *	log_params,
		const SacnNetintConfig *	sys_netint_config,
		const SacnCommonCallbacks *	callbacks )

Initialize all features of the sACN library.

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

Redundant initialization is permitted - the library tracks counters for each feature and expects deinit to be called the same number of times as init for each feature.

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 (with the added option of not allowing any interfaces to be used), and the status codes are filled in. If NULL, the library is allowed to use all available system interfaces.
[in]	callbacks	Optional. A struct of callback functions for the library to use to notify the application of events.

Returns: kEtcPalErrOk: Initialization successful.; kEtcPalErrInvalid: Invalid parameter provided.; kEtcPalErrSys: An internal library or system call error occurred.

Topics

Classes

Macros

Typedefs

Enumerations

Functions

Variables

sACN feature masks

sACN version numbers

sACN version strings

Detailed Description

Typedef Documentation

◆ sacn_features_t

◆ SacnMcastInterface

◆ SacnMulticastSendErrorCallback

◆ SacnNetintConfig

◆ SacnSendSocketConfig

◆ SacnUnicastSendErrorCallback

Enumeration Type Documentation

◆ anonymous enum

◆ sacn_ip_support_t

Function Documentation

◆ sacn_deinit()

◆ sacn_deinit_features()

◆ sacn_get_remote_source_cid()

◆ sacn_get_remote_source_handle()

◆ sacn_init()

◆ sacn_init_features()

◆ sacn_init_features_with_cb()

◆ sacn_init_with_cb()