Skip to content

Releases

3.0

Choose a tag to compare

@HakanL HakanL released this 20 Oct 19:35

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().
  • 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.StreamTerminated and ignore a terminated packet's DMX data.

  • terminate: true sends three packets, as E1.31 6.2.6 requires. They're always queued as important.

  • Arguments are validated (#9, #14). ArgumentOutOfRangeException for:

    • 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.Parse returns 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 throw InvalidDataException (#8).

  • Sync packets carry a SubscribeMode (#15): the subscription of their sync address. Before, they always arrived as None.

  • After Dispose, the join methods throw ObjectDisposedException instead of ArgumentNullException.

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: SendUniverseDiscovery sorts 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.
  • 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: SendDmxData and SendSync can 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_IDENTIFIER array 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.