bacnet-sweep — read-only BACnet/IP discovery from a laptop

There is no install. One file, standard library only — no pip, no bacpypes, no virtual environment, nothing to install beyond the Python already on the machine, 3.8 or newer. It was written and run here on Python 3.12, which is the only version it has actually been executed on; the 3.8 floor comes from reading the file rather than from running it.

It binds UDP 47808, which needs no special privilege — the port is above 1024, so there is nothing to elevate. What actually stops a sweep on a laptop is something else on the same machine already holding that port: Workbench, a running station, another BACnet stack, or a second copy of this. Pass --local-port 47809 and it works, because devices reply to whatever port the request came from. The tool diagnoses exactly that case and names the flag:

Real output, from the tool's own test fixture on 127.0.0.1 — not from a site:

The machine's own firewall still has to allow UDP back in. A sweep that reports nothing at all on a network you know has devices on it is nearly always the firewall, the port, or the wrong broadcast address rather than an empty network — and a silent sweep prints those causes in order of likelihood instead of an empty table.

From the sweep: one row per device that answered, keyed by device instance number, with the address it answered from, the vendor identifier as a number, the largest message the device will accept and whether it supports segmentation. Those last two are a prediction rather than trivia: they are how the sweep can tell you in advance that a device's point list will have to be read the slow way.

Two devices claiming the same instance number are both listed and both flagged, rather than one of them quietly winning. A device answering with instance 4194303 is named as one that was never given an instance number. A device whose I-Am arrived through a BACnet router is listed and marked as not readable from here, which is honest about the thing most likely to waste your afternoon.

The vendor column is a number, not a name: the ASHRAE vendor list is not shipped with the file, and the output says so rather than guessing.

Real output, from the fake BACnet device that ships with the tool's test suite, running on 127.0.0.1. It is not a site and there is no real device anywhere in it:

From the dump: the device's object list, one row per object — object type and instance, object name, present value, engineering units, and a note column carrying whatever the device refused to answer. Five columns, to a terminal table or to CSV on standard output. The CSV is the format that matters, because it is the thing you paste into a point schedule, diff against last year's, or hand to whoever asked whether that meter is on the system.

Where an object list will not fit in one message, it is read element by element instead of being given up on, and the output says that it was. The footer says how many properties were read, how far apart, and that every value is a snapshot at its own instant rather than a synchronised sample — which matters the moment anyone starts reasoning about two numbers together.

Real output, same fixture, same loopback address:

What the fixture did cover: the Who-Is broadcast and the I-Am decode, including max APDU and segmentation support; reading real, unsigned, signed, double, enumerated, character-string, octet-string, bit-string, date, time and object-identifier values; array reads whole, by element, and element 0 as a count; the error, reject and abort replies decoded into words rather than numbers; a device that segments a reply it was told not to segment; a timeout; and a port already in use.

The enumeration tables — object types, properties, units, error and abort codes — were cross-checked against the equivalent tables inside a Niagara installation on this machine: 582 entries agree, none disagrees, and the check found four errors in ours before release. Reading a jar as a cross-check is a cross-check and nothing else; it is not an endorsement, an approval or a relationship of any kind.

Not tested, and therefore not claimed: any make or model of real device; a real broadcast domain, because loopback has none; MS/TP; BBMD or foreign-device registration; change-of-value subscription; reassembling a segmented reply; Windows; macOS; any Python other than the 3.12 it was run on; and anything at scale — the largest sweep tested had two devices and the largest dump eighteen objects.

These are the reasons a sweep can be wrong, and they are on the page rather than in a footnote because a tool that hides them wastes your afternoon.

The abort case is worth seeing, because a tool that reports it as "no objects" is wrong in the most confusing possible way. Real output, fixture, loopback:

A sweep tends to find one of four things. Devices nobody knew were there, or that are missing from the head end. Two devices claiming the same device instance number. Point names that no convention survives — AI_17 forty times across four vendors. Or values that are plainly stale, which is the reading that matters most and the one this tool can only hint at.

The first two are station engineering: discovery, a device and point model that matches the site, poll rates set deliberately rather than left at default, and the naming and tagging done as the points are created rather than retro-fitted. That is station engineering, and poll rates and tuning policies is the note on why the default is usually wrong.

The third is a bulk operation rather than a week of clicking: bulk point renaming and tagging. The fourth, when the equipment turns out to speak something with no Niagara driver behind it, is a custom module or driver.

If the CSV tells you something and you are not sure what, send it. Reading one is half an hour and costs nothing.

What a BACnet discovery sweep actually tells you is the protocol behind this page: why the sweep stops at the subnet, how to read an object list from a device that cannot segment, and what a present value does not tell you. BACnet MS/TP on a JACE is the one to read if the devices you are missing are on a trunk. The other program is mqtt-tap, and both of them are listed here.

Published here so the download is checkable rather than trusted. Both figures are read off the file served at /tools/bacnet-sweep.py when this page is built, so they cannot disagree with it.

To check it, on Linux sha256sum bacnet-sweep.py, on macOS shasum -a 256 bacnet-sweep.py, on Windows certutil -hashfile bacnet-sweep.py SHA256. A different digest means a different file — not necessarily a hostile one, but not this one.