Skip to content

Instantly share code, notes, and snippets.

@bbartling
Last active September 17, 2026 16:32
Show Gist options
  • Select an option

  • Save bbartling/bb08c2f81fa4e6189d608fac1f7fef73 to your computer and use it in GitHub Desktop.

Select an option

Save bbartling/bb08c2f81fa4e6189d608fac1f7fef73 to your computer and use it in GitHub Desktop.

BACpypes3 Shell Field Troubleshooting Cheat Sheet

Beginner-friendly BACnet/IP troubleshooting from a Linux machine.

Designed for the situation where you temporarily shut down your normal BACnet/IoT application, start BACpypes3 directly on the BAS network, and determine whether BACnet devices, routers, BBMDs, and points can actually be reached.

Example of the BACpypes3 shell:

$ python -m bacpypes3 --address 192.168.204.11/24 --route-aware
> whois *:* 1000 3456799
123102 2001:2@192.168.204.59
5007 2000:7@192.168.204.200
> 

It returned two BACnet devices within the requested device-instance range: device 123102 on BACnet network 2001 at MAC 2 through router 192.168.204.59, and device 5007 on network 2000 at MAC 7 through router 192.168.204.200.


Find the Linux network interface

Start by seeing the available network interfaces and IP addresses.

ip -br addr

Example:

lo               UNKNOWN        127.0.0.1/8
eno1             UP             192.168.204.50/24
wlan0            UP             192.168.1.22/24

If the BAS is on:

192.168.204.0/24

then:

eno1 = 192.168.204.50/24

is probably the interface you want.

More detail:

ip addr show eno1

Check the routing table:

ip route

Useful test:

ip route get 192.168.204.13

This shows which Linux interface Linux intends to use to reach the BACnet device.


MAKE SURE UDP 47808 IS FREE

BACnet/IP normally uses UDP:

47808 decimal
BAC0 hexadecimal

Before starting BACpypes3, see whether another application already owns it.

Recommended

sudo ss -lunp | grep ':47808'

Example:

UNCONN 0 0 0.0.0.0:47808 0.0.0.0:* users:(("python3",pid=1842,fd=7))

PID 1842 is using the BACnet port.

Other useful commands:

sudo lsof -nP -iUDP:47808

or:

sudo fuser -v 47808/udp

Find more information about the PID:

ps -fp 1842

or:

sudo cat /proc/1842/cmdline | tr '\0' ' '

Stop the existing BACnet process

Try a normal shutdown first:

sudo kill 1842

Check again:

sudo ss -lunp | grep ':47808'

If it absolutely refuses to stop:

sudo kill -9 1842

kill -9 should be the last resort.

Watch for processes that automatically restart

If the process comes right back, it may be controlled by systemd:

systemctl --type=service --state=running

or Docker:

docker ps

For example:

docker stop my-bacnet-iot-service

Then verify again:

sudo ss -lunp | grep ':47808'

You want no output before starting your temporary BACpypes3 instance.


Start the BACpypes3 shell

Debian Linux setup - I am on Linux Mint desktop should work fine on Rasbian or Ubuntu

# Update package lists once and install python-is-python3
sudo apt update
sudo apt install python-is-python3 -y

# Install venv and pip (combined into one command to save time)
sudo apt install python3.12-venv python3-pip -y

# Virtual environment setup
python3 -m venv env
source env/bin/activate

# Install packages with pip
pip install bacpypes3 ifaddr

Then start the BACpypes3 shell, for example:

python -m bacpypes3 --address 192.168.204.50/24 --route-aware

When you're done this is how to deactivate the Python virtual environment:

deactivate

BACpypes3 supports selecting the local BACnet/IP address with --address.

Example BAS interface:

python -m bacpypes3 --address 192.168.204.50/24

--route-aware tells BACpypes3 to preserve and use the specific BACnet router associated with routed addresses, such as 2000:7@192.168.204.200. Without it, BACpypes3 generally relies on normal BACnet routing discovery/cache behavior instead of explicitly honoring the @router-ip path.

python -m bacpypes3 \
  --address 192.168.204.50/24 \
  --route-aware

You should then get the interactive BACpypes3 prompt:

>

BACpypes3 also supports environment configuration, including:

export BACPYPES_DEVICE_ADDRESS=192.168.204.50/24

The shell's argument parser supports:

--address
--network
--route-aware
--foreign
--ttl
--bbmd

among other options.


BASIC DEVICE DISCOVERY

Discover everything visible

> whois

Typical result:

1000 192.168.204.13
1001 192.168.204.14
3456799 192.168.204.20

Format:

DEVICE_INSTANCE ADDRESS

WhoIs on Range:

whois *:* 1000 3456799

Examples

# Discover BACnet routers and their downstream network numbers
wirtn
# Discover devices across ALL reachable BACnet networks
whois *:* 1000 3456799
# Search only BACnet network 2001 through router 192.168.204.59
whois 2001:*@192.168.204.59 1000 3456799
# Search only BACnet network 2000 through router 192.168.204.200
whois 2000:*@192.168.204.200 1000 3456799
# Search specifically for device 123102 on network 2001
whois 2001:*@192.168.204.59 123102 123102
# Search specifically for device 5007 on network 2000
whois 2000:*@192.168.204.200 5007 5007

Based on your discovery:

123102 2001:2@192.168.204.59
5007   2000:7@192.168.204.200

you can then read the devices directly:

# Device 123102 name
read 2001:2@192.168.204.59 device,123102 object-name
# Device 123102 vendor
read 2001:2@192.168.204.59 device,123102 vendor-name
# Device 5007 name
read 2000:7@192.168.204.200 device,5007 object-name
# Device 5007 vendor
read 2000:7@192.168.204.200 device,5007 vendor-name

And then point reads:

# Read AI-1 from device 5007
read 2000:7@192.168.204.200 analog-input,1 present-value
# AI-1 name
read 2000:7@192.168.204.200 analog-input,1 object-name
# AI-1 units
read 2000:7@192.168.204.200 analog-input,1 units
# AI-1 status
read 2000:7@192.168.204.200 analog-input,1 status-flags
# AI-1 out-of-service
read 2000:7@192.168.204.200 analog-input,1 out-of-service

The three most useful ones for your current setup are probably:

wirtn
whois 2000:*@192.168.204.200 1000 3456799
read 2000:7@192.168.204.200 device,5007 object-name

ROUTED BACNET ADDRESS FORMAT

BACpypes3's address parser supports BACnet network numbers as well as an explicit route using:

@

General concept:

DNET:MAC@ROUTER

For example, suppose:

BACnet router IP = 192.168.204.2
Remote BACnet network = 2001
Remote MS/TP MAC = 5

With BACpypes3 running --route-aware, the routed BACnet address can be represented as:

2001:5@192.168.204.2

Then conceptually:

> read 2001:5@192.168.204.2 analog-input,1 present-value

This says:

send to BACnet network 2001,
station MAC 5,
through router 192.168.204.2

That syntax is specifically supported by BACpypes3's address parser when route awareness is enabled.

Remote BACnet/IP station

BACpypes3 can also encode a remote-network BACnet/IP address.

Conceptually:

2001:192.168.50.20@192.168.204.2

Do not confuse:

BACnet network number

with:

IP subnet number

They are different addressing layers.


FIND THE NETWORK BEFORE READING THE REMOTE DEVICE

A good troubleshooting sequence is:

> wirtn

Find:

router = 192.168.204.2
DNET = 2001

Then:

> wirtn 192.168.204.2 2001

Then attempt device discovery toward that network.

Once you know the destination MAC/device address, try the routed read.

For example:

> read 2001:5@192.168.204.2 analog-input,1 present-value

FIND A BBMD

Important BACnet concept:

There is no universal:

Who-Is-BBMD

service.

Usually you either:

  1. already know one BBMD,
  2. identify one from BAS documentation/configuration,
  3. inspect BDT/FDT data,
  4. follow BDT entries from one known BBMD.

Once you have a candidate BBMD IP, BACpypes3 can interrogate it directly.


READ A BBMD BROADCAST DISTRIBUTION TABLE

Suppose:

BBMD = 192.168.204.5

Run:

> rbdt 192.168.204.5

rbdt means:

Read Broadcast Distribution Table

The BDT tells you the other BBMD endpoints participating in BACnet broadcast distribution.

This is extremely useful for diagnosing:

  • Who-Is working on one subnet but not another
  • missing BBMD peers
  • wrong broadcast masks
  • stale BBMD configuration
  • duplicate/wrong BBMD entries

READ A BBMD FOREIGN DEVICE TABLE

Run:

> rfdt 192.168.204.5

rfdt means:

Read Foreign Device Table

BACpypes3 reports foreign-device addresses along with their:

TTL
remaining registration time

This is great when troubleshooting a BACnet application that is supposed to be registered with a remote BBMD.

Example conceptual output:

10.50.1.20:47808 60s, 42s remain
10.50.1.21:47808 60s, 18s remain

If your IoT application's IP is supposed to be registered but isn't listed, you have found a useful clue.


RUN BACpypes3 AS A FOREIGN DEVICE

BACpypes3 itself supports foreign-device registration. BACpypes3 foreign-device registration is useful when the BAS, IoT edge device, or analytics client is on a different IP subnet/VLAN from the BACnet devices, so normal BACnet broadcasts like Who-Is cannot cross the router by themselves. Registering with a BBMD lets that remote client participate in BACnet broadcast traffic across subnets instead of relying on a local Who-Is alone. It is typically required when there is no BACnet router path between the networks and the remote client still needs broadcast-based BACnet discovery or services.

Example:

python -m bacpypes3 \
  --address 10.10.10.50/24 \
  --foreign 192.168.204.5 \
  --ttl 60 \
  --route-aware

Where:

10.10.10.50   = this Linux computer
192.168.204.5 = BBMD
60            = registration TTL

Then:

> whois

can use the BBMD infrastructure for BACnet broadcasts.


ACE BBMD MANAGER

For more serious BBMD troubleshooting, ACE IoT Solutions' ace-bbmd-manager is particularly useful.

Install:

pip install ace-bbmd-manager

Set your BACnet interface:

export BBMD_LOCAL_ADDRESS=192.168.204.50

If you know one BBMD:

bbmd-manager walk 192.168.204.5

This follows BDT entries and attempts to discover the larger BBMD topology.

You can explicitly set the local address:

bbmd-manager -l 192.168.204.50 walk 192.168.204.5

Read one BBMD:

bbmd-manager -l 192.168.204.50 read 192.168.204.5

Display discovered topology:

bbmd-manager status

Show the BBMD relationships:

bbmd-manager links

Verbose:

bbmd-manager -l 192.168.204.50 -v walk 192.168.204.5

BACnet protocol debugging:

bbmd-manager -l 192.168.204.50 -d walk 192.168.204.5

For troubleshooting, I would initially stick to:

walk
read
status
links

because they are observational.

Commands such as:

add-link
delete-link
delete-bbmd
replace
rewind

modify BBMD configuration and should not be used casually on a customer's live BAS.


ACE ACL BBMD

ACE's ace-acl-bbmd is itself a BACnet BBMD based on BACpypes3.

One particularly useful troubleshooting feature is its metrics.

If its Prometheus endpoint is enabled:

http://BBMD-IP:9090/metrics

you can inspect things such as:

BACnet packets
Who-Is / I-Am traffic
ReadProperty traffic
denied packets
foreign devices
BBMD forwarding traffic
top talkers

That can help answer:

Did the BBMD actually receive my Who-Is?
Did ACL filtering block it?
Did it forward it?
Did the remote network answer?

This becomes extremely useful when packet flow is ambiguous.


WIRESHARK / TCPDUMP

When BACpypes3 says:

No response

the next question is:

Did anything actually leave the Linux box?

Watch BACnet traffic:

sudo tcpdump -ni eno1 udp port 47808

More verbose:

sudo tcpdump -vvv -ni eno1 udp port 47808

Capture for Wireshark:

sudo tcpdump -ni eno1 udp port 47808 -w bacnet-debug.pcap

Then open:

bacnet-debug.pcap

in Wireshark.

Wireshark display filter:

bacnet

or:

udp.port == 47808

This distinction is incredibly useful:

BACpypes3 transmitted request, no response

versus:

request never left Linux

versus:

response arrived but application didn't process it

Packet Capture (PCAP)

sudo tcpdump -ni eno1 udp port 47808

Practical capture patterns so you can constrain the PCAP by time, file size, or rotation count, then analyze the result in Python.

For BACnet/IP, UDP 47808 is the usual port, and BACnet/IP BVLL packets use a BVLC header with a type, function, and length field; malformed traffic can often be detected by invalid BVLC type/function values, impossible lengths, or truncated packets.

# Live BACnet/IP traffic only
sudo tcpdump -ni eno1 udp port 47808
# Capture BACnet traffic to a PCAP
sudo tcpdump -ni eno1 udp port 47808 -w bacnet.pcap
# Capture for exactly 5 minutes
sudo timeout 300 tcpdump -ni eno1 udp port 47808 -w bacnet-5min.pcap
# Capture for 1 hour
sudo timeout 3600 tcpdump -ni eno1 udp port 47808 -w bacnet-1hour.pcap
# Stop each PCAP at ~100 MB and rotate to another file
sudo tcpdump -ni eno1 udp port 47808 \
  -C 100 \
  -w bacnet.pcap

That will produce files such as:

bacnet.pcap
bacnet.pcap1
bacnet.pcap2
...

For a bounded rotating capture, for example 10 files at ~100 MB each:

sudo tcpdump -ni eno1 udp port 47808 \
  -C 100 \
  -W 10 \
  -w bacnet.pcap

For time-based rotation, such as a new PCAP every 15 minutes:

sudo tcpdump -ni eno1 udp port 47808 \
  -G 900 \
  -w 'bacnet-%Y%m%d-%H%M%S.pcap'

A nice field troubleshooting capture would be:

sudo timeout 900 tcpdump -ni eno1 udp port 47808 \
  -s 0 \
  -w bacnet-15min.pcap

That gives you a complete 15-minute capture with full packet lengths instead of snap-length truncation.

For Python analysis, I’d use scapy:

pip install scapy

Then something simple like this can count BACnet/IP traffic, top talkers, BVLC function types, and obvious malformed BVLC packets:

from collections import Counter
from scapy.all import rdpcap, UDP, IP

PCAP = "bacnet-15min.pcap"

packets = rdpcap(PCAP)

src_ips = Counter()
dst_ips = Counter()
bvlc_functions = Counter()

total_udp_47808 = 0
malformed = []

BVLC_FUNCTIONS = {
    0x00: "BVLC-Result",
    0x01: "Write-BDT",
    0x02: "Read-BDT",
    0x03: "Read-BDT-Ack",
    0x04: "Forwarded-NPDU",
    0x05: "Register-Foreign-Device",
    0x06: "Read-FDT",
    0x07: "Read-FDT-Ack",
    0x08: "Delete-FDT-Entry",
    0x09: "Distribute-Broadcast-To-Network",
    0x0A: "Original-Unicast-NPDU",
    0x0B: "Original-Broadcast-NPDU",
}

for i, pkt in enumerate(packets, start=1):

    if UDP not in pkt:
        continue

    udp = pkt[UDP]

    if udp.sport != 47808 and udp.dport != 47808:
        continue

    total_udp_47808 += 1

    if IP in pkt:
        src_ips[pkt[IP].src] += 1
        dst_ips[pkt[IP].dst] += 1

    payload = bytes(udp.payload)

    # Minimum BACnet/IP BVLC header = 4 bytes
    if len(payload) < 4:
        malformed.append((i, "BVLC header shorter than 4 bytes"))
        continue

    bvlc_type = payload[0]
    function = payload[1]
    declared_length = int.from_bytes(payload[2:4], "big")

    # Classic BACnet/IP BVLC type
    if bvlc_type != 0x81:
        malformed.append(
            (i, f"Unexpected BVLC type 0x{bvlc_type:02x}")
        )

    bvlc_functions[BVLC_FUNCTIONS.get(
        function,
        f"Unknown-0x{function:02x}"
    )] += 1

    if declared_length != len(payload):
        malformed.append(
            (
                i,
                f"BVLC length mismatch: "
                f"declared={declared_length}, actual={len(payload)}"
            )
        )

print()
print("=== BACnet/IP Summary ===")
print(f"Total UDP/47808 packets: {total_udp_47808}")

print("\nTop source IPs:")
for ip, count in src_ips.most_common(10):
    print(f"{ip:20} {count}")

print("\nTop destination IPs:")
for ip, count in dst_ips.most_common(10):
    print(f"{ip:20} {count}")

print("\nBVLC functions:")
for function, count in bvlc_functions.most_common():
    print(f"{function:35} {count}")

print("\nMalformed / suspicious packets:")
print(f"Count: {len(malformed)}")

for packet_number, reason in malformed[:50]:
    print(f"Packet {packet_number}: {reason}")

That gives you useful baseline statistics like:

=== BACnet/IP Summary ===
Total UDP/47808 packets: 18423

Top source IPs:
192.168.204.200       8211
192.168.204.59        4834
192.168.204.11        1502

BVLC functions:
Original-Unicast-NPDU               12044
Original-Broadcast-NPDU              2133
Forwarded-NPDU                       3750
Register-Foreign-Device                32

Malformed / suspicious packets:
Count: 4

One important distinction: I would label those results “malformed or suspicious BACnet/IP packets”, not automatically “bad BACnet requests.” The checks above detect structural problems such as a BVLC header shorter than four bytes, an unexpected BVLC type, an unknown BVLC function, or a declared BVLC length that does not match the captured payload; deeper BACnet validation would require parsing the NPDU/APDU and service-specific fields too. The BACnet standard defines the BVLC header length as the length of the entire BVLL message, which makes that length check particularly useful. ([BACnet Committee][1])

For an IoT edge health check, I’d probably capture:

sudo timeout 900 tcpdump -ni eno1 udp port 47808 -s 0 -w bacnet-15min.pcap

then report packets/minute, bytes/minute, top BACnet talkers, broadcast vs unicast traffic, Who-Is/I-Am counts, ReadProperty counts, router messages, BBMD/foreign-device traffic, and malformed/suspicious packets. That would make a pretty useful automated BACnet network-health snapshot.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment