Skip to content

Architecture & Development

Jump to bottom
Giuliano Molon edited this page Sep 27, 2026 · 1 revision

BHAM is built with a focus on speed, low resource consumption, and ease of deployment. The architecture strictly separates the asynchronous scanning engine from the user interface, communicating entirely via REST APIs and real-time WebSockets.

Technology Stack

  • Backend: Python
  • Framework: FastAPI (ASGI) for high-performance HTTP endpoints and WebSocket management.
  • Concurrency: asyncio is used extensively in the scanning modules to prevent blocking operations during strict network and serial timeouts.
  • Frontend: Pure HTML5, CSS3, and Vanilla JavaScript. We intentionally avoid heavy frontend frameworks to keep the compiled binary size small and ensure the UI loads instantly, even on low-end industrial field tablets.
  • CI/CD: GitHub Actions handles automated testing, executable compilation, .deb packaging, and WinGet manifest distribution.

Repository Structure

If you wish to explore the code or submit a Pull Request, here is a quick map of the repository structure:

  • /api/ - FastAPI routing (routes.py) and real-time event handlers (websockets.py).
  • /core/ - System-level utilities: hardware discovery (finding active serial COM ports and network adapters), logging, and session management.
  • /data/ - Internal state management and JSON map handling for the telemetry translation engine.
  • /frontend/ - The web interface assets, including the UI logic and localization dictionaries.
  • /scanners/ - The core protocol logic. Contains the dedicated asynchronous workers for Modbus, BACnet, KNX, and passive IP/Serial sniffing.
  • /scripts/ & /winget/ - Automation scripts for bash installations, Debian packaging, and Microsoft package manager distribution.

Local Development Setup

To run BHAM locally from source for development or testing purposes:

  1. Clone the repository: git clone https://github.com/Molonverona/BHAM.git
  2. Navigate to the project directory: cd BHAM
  3. Install the required dependencies: pip install -r requirements.txt
  4. Start the development server: python main.py

The backend will start on http://localhost:8000 and automatically serve the frontend web interface.

Contributing

We welcome contributions from the community! Whether you are adding a new JSON telemetry map for a specific HVAC vendor, optimizing the Early Exit algorithm, or translating the frontend UI into a new language, please feel free to open an Issue or submit a Pull Request.

Clone this wiki locally