Repository navigation
Releases
3.0
Haukcode.sACN 3.0
3.0 is a correctness release. The library was audited against ANSI E1.31-2018 and brought into line with it:
- Universe discovery didn't work with any other product.
- Received packets that E1.31 says to discard were accepted.
- Sending used no range checks.
- The documented receive pattern returned corrupted data.
A second review covered the client and the HighPerfComm transport underneath it.
Testing:
- The byte offsets of every packet type are checked by tests against E1.31's tables and against sACNView's source.
- Universe discovery was verified live against sACNView in both directions.
- The 87 unit tests now run in CI (Linux) on every build.
Releases: these notes cover 3.0.116. The earlier 3.0 builds, 3.0.113–3.0.115, contain only part of these changes.
This release has breaking changes. Most only need a type updated; the ones that change behaviour come first below.
Behaviour changes to check first
-
Received packets are reused; queue a copy (#12).
- The packet handed to
channelWriter, its DMX data included, is overwritten by the next datagram as soon as the writer returns. This has been true since 2.0.x. - The README and NuGet examples put the packet itself into a
Channel, so every queued item was the same object holding the last datagram. - Process the packet inside the writer, or queue the new
p.Clone().
- The packet handed to
-
Stream_Terminated packets are delivered (#10). They used to be dropped, so a consumer had to wait out the 2.5 s data loss timeout. Check
Options.StreamTerminatedand ignore a terminated packet's DMX data. -
terminate: truesends three packets, as E1.31 6.2.6 requires. They're always queued as important. -
Arguments are validated (#9, #14).
ArgumentOutOfRangeExceptionfor:- a universe outside 1–63999;
- a sync address that isn't 0 or 1–63999;
- priority over 200;
- more than 512 DMX slots.
This applies to
SendDmxData,SendSync, the join methods and discovery universes. -
Long source names are cut, not rejected. A source name over 63 UTF-8 bytes is cut on a character boundary and always NUL-terminated. It used to throw from inside the send path.
-
SACNPacket.Parsereturns null for datagrams that aren't E1.31, or that use a root or extended framing vector the library doesn't know. Malformed E1.31 packets throwInvalidDataException(#8). -
Sync packets carry a
SubscribeMode(#15): the subscription of their sync address. Before, they always arrived asNone. -
After
Dispose, the join methods throwObjectDisposedExceptioninstead ofArgumentNullException.
Migration
| Area | Was | Now |
|---|---|---|
| Receiving into a queue | channel.Writer.WriteAsync(p) |
channel.Writer.WriteAsync(p.Clone()) |
| Universe discovery | SendUniverseDiscovery(address, universes, page, lastPage, important) |
SendUniverseDiscovery(address, universes, important): sorts and pages for you |
SACNClient.UniverseDiscoveryMulticastAddress |
239.255.250.133 | 239.255.250.214 (new UniverseDiscoveryUniverse = 64214) |
SACNPacket.Parse |
returns SACNPacket |
returns SACNPacket? |
RootLayer.PREAMBLE_LENGTH, POSTAMBLE_LENGTH |
short |
ushort |
RootLayer.VECTOR_ROOT_*, FramingLayer.VECTOR_E131_*, FramingLayer.RootVector |
int |
uint |
DMPLayer.FIRST_PROPERTY_ADDRESS, ADDRESS_INCREMENT |
short |
ushort |
RootLayer.Length, DMPLayer.Length |
short |
ushort |
SendDmxData |
— | new optional preview and forceSynchronization parameters. Force_Synchronization still defaults to on when a sync address is set, so existing senders send the same bits. |
SACNDataPacket.Update |
— | same two new parameters |
New constants: SACNPacket.MinUniverse/MaxUniverse/MaxPriority/DefaultPriority/MAX_UNIVERSE_DISCOVERY_PACKET_SIZE, DMPLayer.MaxSlots, UniverseDiscoveryFramingLayer.VECTOR_UNIVERSE_DISCOVERY_UNIVERSE_LIST/MaxUniversesPerPage.
Universe discovery
Discovery had never been tested against another implementation, and didn't interoperate (#7).
- Packet layout: the Universe Discovery Layer header (flags/length at octet 112, vector at 114) was missing, so every page was 6 bytes short.
- Address: packets went to 239.255.250.133 instead of 239.255.250.214.
- Receive buffer: it's now sized for a full 512-universe page (1144 bytes). It was 638 bytes, and Windows silently truncated larger pages.
- Paging:
SendUniverseDiscoverysorts the list, removes duplicates, and sends pages of at most 512. - Verified with sACNView: it lists our announcements under Discovered, and the client parses sACNView's announcements.
Receiving
- Validation (#8):
- The framing and DMP layers' flags, vectors, address type, first property address and address increment are checked for real. They were only
Debug.Assert, which is compiled out of the NuGet build, so packets with any of them wrong were accepted. - Every PDU length is checked against its parent and the datagram.
- The DMP property value count must be 1–513.
- The framing and DMP layers' flags, vectors, address type, first property address and address increment are checked for real. They were only
- Robustness: 2,000,000 randomly mutated, truncated and extended packets produced only null or
InvalidDataException. - Stray traffic on the port no longer floods
OnError.
Sending
- Thread safety:
SendDmxDataandSendSynccan be called from several threads (#13). All sends shared one reused packet; with 4 threads, about 3% of packets went out with another universe's data. A lock now serializes the send path. - Preview_Data and Force_Synchronization can be set per send (#10).
Client
- Constructor: a failed constructor no longer leaks its sender threads and sockets (#14).
- Thread safety: the endpoint caches and the universe subscriptions are safe across the send, receive and caller threads (#11).
- Discovery group: joining a universe no longer interferes with the discovery group's membership.
- Packet identifier: the library uses its own copy, so changing the public
RootLayer.PACKET_IDENTIFIERarray can't break it.
Unsigned types
Wire constants and lengths that E1.31 defines as uint16/uint32 are now ushort/uint (#6). No valid value read back wrong, but a malformed DMP property value count of 0x8000 or more was read as empty data instead of being rejected.
Haukcode.HighPerfComm 1.0.52
The transport underneath has two fixes that also apply to Haukcode.ArtNet:
- Send-failure recovery (HighPerfComm#2): after 3 s of failed sends, such as a NIC flap, the client stopped sending for good. It now probes about once a second and recovers when the network returns.
- Oversize datagrams (HighPerfComm#3) are dropped. On Windows they used to stall the receiver for 100 ms each, and on Linux/macOS a truncated datagram was passed on as if it were whole.
Documentation
The README was corrected (#16):
- Removed claims: "priority-based source arbitration" (the library doesn't merge sources) and a "40 packets/second" limit (E1.31 sets none).
- Fixed: the multicast range and a helper method that doesn't exist.
- Added:
- Packet Lifetime, Universe Discovery and Upgrading from 2.x sections.
- A "What the Application Handles" section. It covers what E1.31 expects but leaves to the application: sequence checking, the 2.5 s data loss timeout, merging, preview data, synchronization, keep-alive and the 10 s discovery interval.
Issues closed in this release: #6–#16, and HighPerfComm#2–#3.