buildingSimulator

Python FastAPI BACnet/IP building simulator that generates configurable BAS equipment and BACnet-style points.

The Story Behind buildingSimulator

For years, I looked for a decent, realistic BACnet/IP building simulator. I wanted something I could spin up quickly to test HMIs, analytics platforms, integration scripts, and client libraries without real hardware or vendor-specific tooling.

I never found one that really fit.

Most options were:

• locked to a specific vendor ecosystem
• painfully limited in scope
• outdated
• or dependent on a licensed BAS server just to generate fake points

So one day, I finally said, "f*** it," and built it myself.

buildingSimulator is the result: a fully independent, open-source BACnet/IP building simulator designed to behave like a real Building Automation System.

Think of it like the mirror image of YABE (Yet Another BACnet Explorer): instead of exploring real devices, this becomes the devices.

No vendor lock-in. No license walls. No nonsense.

Whether you are building a new front-end, testing a fault-detection algorithm, training a team, or just need a reliable sandbox to throw data at, this project is built for you.

It is still evolving, but it is already useful in real workflows.

If you have ever been frustrated by the lack of good test data in our industry, you are in the right place.

Welcome to the simulation.

Features

• JSON-configurable building location, occupancy schedule, equipment counts, and zone count
• Simulates AHUs, RTUs, VAVs, FCUs, chillers, boilers, pumps, and meters with persistent, time-evolving behavior
• Includes a built-in browser HMI for runtime control, device visibility, and quick configuration edits
• Supports simulation clock control with adjustable tick rate and time-scale acceleration
• Supports synthetic weather or live outdoor air temperature based on the configured building latitude/longitude
• Provides aggregate and equipment-level power and energy submetering
• Generates BACnet-like object inventories including point objects, schedules, and trend-log objects
• Supports publishing a multi-device inventory through a BACpypes3 integration layer from one IP endpoint
• Trends simulated point values to CSV over time

Quickstart

python -m venv .venv
.venv\Scripts\activate
python -m pip install -r requirements-dev.txt
uvicorn app.main:app --reload

VS Code is configured to prefer .venv\\Scripts\\python.exe for this workspace.

HMI

• http://127.0.0.1:8000/ - built-in operator HMI
• http://127.0.0.1:8000/docs - FastAPI Swagger UI
• http://127.0.0.1:8000/redoc - alternate API reference

The HMI exposes:

• simulation start, stop, and single-tick controls
• runtime tick seconds and time-scale controls
• simulation clock editing
• weather mode selection (simulated or live)
• building name, city, timezone, and zone count edits
• live device point visibility for all simulated equipment

Testing

pytest

The automated suite covers API smoke behavior, simulation clock/runtime updates, schedule edge cases, device dynamics, weather integration hooks, and submetered energy reporting.

GitHub Actions runs the same pytest -q suite on every push and pull request.

CI

The CI workflow installs requirements-dev.txt, validates module syntax with python -m compileall app tests, and runs pytest -q across:

• ubuntu-latest and windows-latest
• Python 3.14

You can also run the workflow manually using workflow_dispatch.

Configuration Notes

• The main configuration surface is GET /config and PUT /config.
• The runtime-only controls are GET /simulation/runtime and PUT /simulation/runtime.
• simulation.time_scale controls how much simulated time advances on each real tick.
• simulation.weather_mode accepts simulated or live.
• simulation.weather_refresh_minutes controls how long live weather is cached.
• The first successful PUT /config creates data/building_config.json.

BACnet Notes

• The HTTP app runs on 127.0.0.1:8000 by default.
• BACnet/IP binds to a detected local IPv4 interface on UDP 47808 by default.
• The simulator currently publishes read-oriented telemetry objects for the generated points.
• BACnet runtime state is visible through GET /simulation/status.

Documentation

• docs/operations.md - operator guide for HMI usage, weather mode, runtime controls, and metering

API

• GET / - built-in HMI
• GET /config - current building configuration
• PUT /config - save and apply new configuration (persisted to data/building_config.json)
• GET /devices - generated simulated devices and object lists
• POST /simulation/start - start continuous simulation loop
• POST /simulation/stop - stop continuous simulation loop
• POST /simulation/tick - run one simulation step immediately
• GET /simulation/runtime - current simulation runtime and plant status
• PUT /simulation/runtime - update runtime controls like tick seconds, time scale, and simulation clock
• GET /simulation/status - simulation and BACnet exposure status

Trend data is written to data/trends.csv by default.