Repository navigation
The 4.0 release modernises the build, packaging and dependencies of the library. See MIGRATION.md for upgrade guidance.
Breaking
- Logging: replaced the unmaintained
Common.LoggingwithMicrosoft.Extensions.Logging. The publicLogproperty is nowILogger; configure a factory viaBacnetLogging.Factory. An optionalBACnet.Logging.CommonLoggingbridge preserves existing sinks. - Native transports moved out of the core into optional packages: the pcap-based Ethernet transport →
BACnet.Ethernet, the physical serial port →BACnet.Serial. The MS/TP and PTP protocols remain in the core; wire a serial port withSerialTransport.Mstp(...)/.Ptp(...). - Scheduling types replaced with spec-shaped ones (see MIGRATION.md):
BACnetCalendarEntry(aList<object>bag) →BacnetCalendarEntry(a real CHOICE, one entry per value),BacnetweekNDay→BacnetWeekNDay(month/week-of-month/day-of-week enums, week-of-month actually evaluated),BacnetDate.toDateTime()→ToDateTime(). DecodedDate_List,Weekly_ScheduleandException_Schedulevalues now carry dedicated application tags and typed objects instead of the opaqueCONTEXT_SPECIFIC_DECODEDshapes. BacnetReliabilityrenumbered to match the standard's enumeration (see MIGRATION.md):RELIABILITY_MEMBER_FAULTmoves 11 → 13 andRELIABILITY_TRIPPED13 → 15 (11 is reserved by ASHRAE 135 and is nowRELIABILITY_RESERVED_11), and the values the enum was missing, 14 and 16-25, are added. 3.x sent and interpreted the two wrong numbers on the wire; code that persisted or compared the numeric values keeps compiling and silently changes meaning.BacnetLogRecord.statusFlagsis now aBacnetStatusFlagsinstead of aBacnetBitString, and theBacnetLogRecord(type, value, stamp, status)constructor takes the same enum in place of a rawuint. Trend-log records encode and decode it as the fixed 4-bit BACnetStatusFlags string.BacnetRejectReason.RECOGNIZED_SERVICE→UNRECOGNIZED_SERVICE: reject reason 9 means the service is not recognized (ASHRAE 135 §18.8) - the member had always been spelled without the negation. The value (9) is unchanged, so only a rename is needed at call sites.BacnetDeviceObjectPropertyReference: the misspelled public fielddeviceIndentifieris nowdeviceIdentifier(the constructor parameter included).Services.EncodeCreateProperty→EncodeCreateObject: the encoder was misnamed - it encodes a CreateObject-Request (BACnet has no CreateProperty service). Same signature; theBacnetClientrequest methods are unaffected.
Added
- Multi-targeting:
net48;netstandard2.0;net8.0;net10.0for the core,net48;net8.0;net10.0forBACnet.EthernetandBACnet.Serial(their native dependencies have no netstandard2.0 target). - New packages:
BACnet.Ethernet,BACnet.Serial,BACnet.Logging.CommonLogging. - Central Package Management, MinVer tag-driven versioning, Source Link + symbol (
.snupkg) packages. - Every package ships its XML documentation file, so consumers get IntelliSense tooltips for the doc-commented API, and
dotnet packruns the SDK's package validation across all four targets. BacnetIpUdpProtocolTransportandBacnetIpV6UdpProtocolTransportaccept amaxApduconstructor parameter to lower the advertised and sent APDU size (e.g.MAX_APDU1024keeps every frame, including segmented responses, under a 1500-byte MTU instead of relying on IP fragmentation).BacnetIpUdpProtocolTransport.ReceiveBufferSizesets the UDP receive buffer (SO_RCVBUF) and may be changed at any time, including afterStart(). It now defaults to 1 MB rather than the OS default, so a burst of incoming messages is far less likely to be dropped by the socket (on Linux the effective size is still capped bynet.core.rmem_max).- CI: multi-OS build matrix; tag-triggered publish to both nuget.org (Trusted Publishing) and GitHub Packages.
- Runnable sample projects moved in-repo under
Examples/and built in CI. - ASHRAE 135 Annex F golden-vector tests: 83 encode/decode assertions covering 27 of Annex F's 37 example encodings, asserted byte-for-byte. Not covered yet: AcknowledgeAlarm (F.1.1), GetEnrollmentSummary (F.1.7), the COVNotificationMultiple family (F.1.12-14), WriteGroup (F.3.11-13) and TextMessage (F.4.5-6).
BacnetPropertyReference'sarrayIndexconstructor parameter now defaults toASN1.BACNET_ARRAY_ALL, which omits the optional index from the request so the whole property is read or written; there is also an overload taking aBacnetPropertyIdsinstead of a rawuint. Passing 0 selects the array length, which is what made hand-built references to scalar properties fail.Services.EncodeCreateObjectoverload taking aBacnetObjectTypes(CreateObject by object type, the device assigns the instance number) andServices.EncodeDeleteObject.- PrivateTransfer send/receive support in
BacnetClient(#154):PrivateTransferRequest,SendUnconfirmedPrivateTransfer, theOnPrivateTransferevent, and thePrivateTransferResponse/PrivateTransferErrorResponsereplies (ASHRAE 135 clauses 16.2/16.3). WritePropertyRequest/BeginWritePropertyRequestaccept an optionalarrayIndexto write a single array element (matchingReadPropertyRequest), e.g. one slot of aPriority_Arrayor one day of aWeekly_Schedule.- Full Schedule/Calendar (scheduling) serialization (#26, #131):
BacnetTimeValue,BacnetDailySchedule,BacnetSpecialEventand the reworkedBacnetCalendarEntry/BacnetWeekNDaygiveWeekly_Schedule,Exception_ScheduleandDate_Listsymmetric encode/decode - values read from a device can be modified and written back as-is (ASHRAE 135-2016 clauses 12.9 / 12.24 / 21). - Asynchronous, non-blocking client API (#46): every confirmed service has an awaitable
…Asynccounterpart (ReadPropertyAsync,WritePropertyAsync,SubscribeCOVAsync, …) that no longer parks a thread per outstanding request, so many requests can be in flight on one client at once, each reply matched to its request by invoke-id. Failures throw (aTimeoutExceptiononce retries are exhausted, otherwise the device error); most methods accept an optionalCancellationToken, and the file/range/private-transfer variants return typed results (BacnetReadFileResult,BacnetReadRangeResult,BacnetPrivateTransferResult).
Changed
- The core package is now pure-managed with no native dependencies (closes the pcap → log4net chain, #112).
- SharpPcap bumped 4.x → 6.x in
BACnet.Ethernet(drops the vulnerable transitive log4net). - The BACnet/IP transport no longer hex-formats every received packet to build a log message that was usually discarded, removing an allocation per datagram on the receive path (#152).
Fixed
- A busy BACnet/IP client no longer overflows the stack: when
EndReceivecompleted synchronously (typical under sustained load), the receive handler re-armed the socket withBeginReceivefrom inside its ownfinallyblock and recursed into itself. The re-arm is queued to the thread pool so the stack unwinds between receives (#150). EndReadPropertyRequestno longer deadlocks when the device answers with an Error-APDU: it readres.Errorbefore waiting for completion and could dispose the async result while the receive thread was still signalling it. It now waits for completion, then reads the error, then disposes (#153).EndSubscribeCOVRequesthad the same read-before-wait, so device rejections (e.g. unknown-object) were swallowed and came back as a null exception instead of a failure (#147, #148).- WhoIs/I-Am broadcast works on Linux: the exclusive-port socket is bound explicitly with
ExclusiveAddressUse = false+SO_REUSEADDRrather than through theUdpClient(IPEndPoint)constructor, which binds before those options can be applied (#157). Services.DecodeCreateObjectnow decodes the CreateObject "by object type" request form (objectSpecifier choice[0], where the device assigns the instance number) as well as the "by object identifier" form ([1]). Only[1]was decoded before, so a request produced by theEncodeCreateObject(BacnetObjectTypes, ...)overload could not be read back by a receiver.- Segmented responses no longer crash with an
IndexOutOfRangeExceptionwhen the APDU limit exceeds the transport payload buffer (the defaultmaxPayload: 1472vs the 1476-byte B/IP APDU): the segment encoder clamps its window to the physical buffer andEncodeBufferreportsNotEnoughBufferinstead of writing out of bounds. - Segmented responses now respect the requester's max-APDU-length-accepted (ASHRAE 135 §5.2.1.2). The value is captured automatically when
GetSegmentBufferis called inside a request event handler, or can be passed explicitly via the newGetSegmentBuffer(maxSegments, requesterMaxAdpu)overload. Iam()can now answer a Who-Is that arrived through a BACnet router: when the receiver address carries aRoutedSource, the I-Am is NPDU-addressed to the original source network and sent back via the router, so the requester receives it as ASHRAE 135 §16.10.4 requires (previously such replies were mis-addressed and never reached the requester).- Segmented ComplexACKs no longer set the reserved
SERVERbit in the PDU type octet (ASHRAE 135 §20.1.5 reserves bits 1-0 as zero; strict peers could discard such frames). This aligns the wire format with YABE and bacnet-stack. - OS detection in the UDP transport now uses
RuntimeInformation.IsOSPlatform, fixingDontFragmenton macOS (#91) and making the Windows-onlySIO_UDP_CONNRESETguard analyzer-clean. - Response correlation matches by invoke-id per ASHRAE 135 §20.1.2.6 (#141, #149).
- Event notifications stamped with a
timeorsequenceNumberBACnetTimeStamp are now decoded, soOnEventNotifyfires for them (#32, #67): the decoders assumed thedateTimechoice only, making notifications from devices without clocks (which commonly stamp with sequence numbers) invisible. The same fix applies toDecodeAlarmAcknowledge(an ack echoes the event's timestamp choice) and the GetEventInformation timestamps; newASN1.bacapp_decode_timestamphandles the full CHOICE andBacnetGenericTime.Tag/Sequenceare now populated on decode. - Partially-wildcarded Date and Time values no longer throw during decode (#103): any octet may individually be X'FF' (unspecified) and Date carries special values (odd/even month, last day — ASHRAE 135 §20.2.12/§20.2.13); previously the exception was swallowed upstream, e.g. silently dropping event notifications stamped with a wildcarded time. Such values are also lossless now: a decoded
BacnetValuecarries the new per-octetBacnetTime(or the existingBacnetDate) whenever the octets cannot be represented faithfully as aDateTime, a Date+Time property pair with wildcards merges into the newBacnetDateTimestruct, and timestamps keep their original time octets inBacnetGenericTime.PartialTimenext to the best-effort clampedTime— so echoing an event's partially-wildcarded timestamp back (e.g. in an AcknowledgeAlarm) reproduces the wire bytes. Fully-specified values keep coming back asDateTime.Event_Time_Stampselements now decode asBacnetGenericTime(preserving the BACnetTimeStamp choice) instead of a bareDateTimethat crashed on re-encode. Log-record stamps and service-internal times (TimeSynchronization, ReadRange by-time), where the standard requires specific values, still clamp. PROP_EFFECTIVE_PERIODdecodes as one typedBacnetDateRangevalue instead of two bareDateTimes, so the open (wildcarded) boundaries of a Schedule's Effective_Period survive a read/write round-trip. Writing either shape — the typed range or two application-tagged dates — stays supported.- ReadRange by-time and by-sequence responses decode correctly: the ack's trailing first-sequence-number was included in the returned item-data range (the extraction assumed the by-position layout), so decoding the last "record" of a time-based trend-log read failed.
- A TIME value of exactly midnight no longer encodes as the "any time" wildcard:
DateTime(1,1,1)— which every decoded midnight is — used to double as the wildcard sentinel, so reading a 00:00 time (or timestamp) and writing it back corrupted it toFF FF FF FF. The unspecified time now has a dedicated marker,ASN1.BACNET_TIME_WILDCARD: decoders return it for a fully-wildcarded time and encoders turn it back intoFF FF FF FF, so midnight and the wildcard each round-trip losslessly (see MIGRATION.md — a fully-wildcarded time used to decode toDateTime.MinValue). Combined date+time decodes (BACnetDateTime, timestamps, log records) keep degrading an unspecified time component to 00:00, as those values cannot carry it. - All unconfirmed sends now address peers behind a BACnet router correctly (NPDU destination = the peer's network/MAC, frame to the fronting router — the same addressing the
Iam()fix established): directedWhoIs/WhoHas,SendUnconfirmedEventNotification,SendUnconfirmedPrivateTransferandSynchronizeTime.IHave()gained an optionalreceiverparameter (appended aftersourceto stay source-compatible) so it can answer a Who-Has that arrived through a router (135 §16.9). ErrorResponsesends the Error PDU with the plain §20.1.7 encoding again: since 3.x the error class/code pair was wrapped in spurious context tags, so foreign stacks mis-decoded every error this library returned (the tolerant decoder hid it from same-stack round-trips) (#199). Context wrapping is now explicit at the call sites whose ASN.1 requires it (private-transfer error-type[0], trend-log failure log-datum[8]).BacnetBitString.ConvertFromIntcounted significant bits asceil(log2(value)), which under-counted every exact power of two (4 gave 2 bits instead of 3) and gave 0 bits for the value 1, so those bit strings went on the wire a bit short. It isfloor(log2(value)) + 1now, and callers that know the standard-defined width can pass it explicitly (#8).ReadRangeResponseencodes BACnetResultFlags as the fixed 3-bit BIT STRING the standard defines (ASHRAE 135 §20.2.10 requires all defined bits present): the width used to be derived from the enum value, so all-false flags collapsed to an empty, non-conformant bit string (#171, PR #15).encode_bacnet_signedused a strict>lower bound, soint.MinValuetook the 8-byte signed64 path whiledecode_signedonly handles 1-4 bytes - the value silently decoded back to 0. The whole int32 range round-trips now.Time_Of_Device_Restartdecodes as a BACnetTimeStamp (ASHRAE 135 §12.11.45) through the same path asEvent_Time_Stamps, instead of as a bare application value (#142, svn@525).- BVLC broadcast-distribution and foreign-device table entries decode addresses as unsigned: an IP whose last octet was ≥ 128 (e.g. 192.168.0.137) produced a negative
int, whichnew IPAddress(long)rejects, so reading such a BDT/FDT threw (#123). BACnet.Serialreports a clear error, with the fix, when theSystem.IO.Portsnative library is missing from a publish rather than failing obscurely on open (#201, see MIGRATION.md).- Multi-object
WritePropertyMultipledecoding (#158), DATE/TIME/DATETIME culture-invariant serialization (#159), REAL/DOUBLE/UNSIGNED_INT property serialization (#143), and several encoder fixes surfaced by the Annex F vectors (wildcard time, private-transfer ack). GetAddressDefaultInterfacenow throws a helpful error instead of returning null when the local interface is ambiguous (#100).
Full changelog: 3.0.2...v4.0.0