Frequently Asked Questions
General
General
Overview
Getting Started
Installation
Installation
Steps To Success
Creating Building & Deployment
Installing Edge Node
Installing Edge Node on Hyper-V
Troubleshooting Installation & Working with IT
Data Collection
Data Collection
What is BACnet?
BACnet Discovery
What is Modbus?
Connect Your Modbus Devices
Troubleshooting Discovery
Understanding Real-Time Data Collection
Dealing with Offline Data
Multi-Subnet BACnet Network
Data Modeling with AI
Data Modeling with AI
What is an Ontology?
Onboard's Data Model
Getting Started with Staging
Onboard AI
Equipment Tab
Points Tab
Locations Tab
Publish-Unpublish Workflow
Feature Guides
Feature Guides
Exporting Data (CSV, JSON)
Buildings Explorer
Creating Custom Labels
Account & Preferences
Account & Preferences
User Roles & Access
Creating a User Account
Deactivating a User Account
Unit Preferences
Security
Security
Security Brief

Troubleshooting Installation & Working with IT

If this is your first time installing Onboard's Edge Node, this guide is for you. Network environments and IT policies can sometimes introduce challenges. This guide outlines the most common troubleshooting steps and how to work effectively with your IT team to get things up and running.

If you have successfully installed the Edge Node and powered on the VM, but the deployment status in the Onboard App remains Offline, work through the checks below.

🔥 Verify Firewall & Network Permissions

Ensure outbound traffic is permitted from the Edge Node VM on the following ports:

  • TCP 443: Required for secure HTTPS communication with Onboard's cloud.
  • UDP 1501: Required for Onboard's encrypted WireGuard® VPN connection (troubleshooting only).

💡 When running in Bridged mode, the Edge VM should appear on the building network as a distinct device with its own IP address. If your IT team enforces outbound whitelisting, provide them the Edge VM's IP address to confirm traffic is permitted to Onboard's servers.

🌐 Certificate Errors During the Connectivity Test

The VM powers on but stays stuck testing connectivity to api.onboarddata.io. The Edge Node resolves api.onboarddata.io using the DNS server handed to it by the network's DHCP lease. If that resolver returns an incorrect address, the VM connects to the wrong endpoint, which does not present a valid Onboard certificate, so the connection fails.

In this scenario, the Onboard Collector can be configured with a DNS override so it uses a specific nameserver instead of the DHCP-provided resolver. When generating a Collector, provide the DNS nameserver (e.g. 8.8.8.8) and a new Collector file will be created with the override applied.

⚠️ A DNS override requires that the site's firewall permits outbound DNS to the chosen resolver. Confirm this with your IT team if the issue persists.

🌐 Confirm the VM's Network Adapter Mode

  1. Open your virtualization manager (e.g., VMware).
  2. Locate the Onboard VM and open its Network Adapter Settings.
  3. If the adapter is set to NAT mode, switch it to Bridged mode.
    • NAT mode isolates the VM behind the host machine, preventing it from appearing as a distinct device on the LAN.
    • Bridged mode allows the VM to obtain an IP address on the same subnet as your building's BACnet or Modbus devices, which is required for device discovery and data collection.
  4. Restart the VM to apply the change.

🔐 Confirm Whitelisting with IT

If your IT department enforces strict firewall rules or MAC-based network access controls:

  • Retrieve the VM's MAC address from your virtualization manager.
  • Share it with your IT team to whitelist the Edge Node VM for network access.
  • If DHCP is in use, confirm the Edge VM is receiving a valid IP address on the correct subnet.

🖧 Dual NIC Configuration

In some environments, the OT network (where BACnet/Modbus devices reside) and the IT network (which provides internet access) are physically separated. A single NIC in Bridged mode cannot reach both networks simultaneously.

In this case, the Edge Node VM can be configured with two network adapters:

  • NIC 1: Bridged to the OT network for BACnet discovery and data collection. This NIC must be on the same subnet as your BACnet or Modbus devices.
  • NIC 2: Bridged or NAT on the IT network for outbound internet connectivity to Onboard's cloud over TCP port 443.

⚠️ Confirm with your IT team which physical adapter on the host maps to each network before configuring. Incorrect adapter assignment is the most common cause of issues in Dual NIC setups.

⚠️ Still Not Connecting?

If all checks are complete and the deployment remains offline:

🤝 Working With IT

A few best practices for a smooth collaboration with your IT or OT team:

  • Share requirements early. Provide your IT team the Steps to a Successful Installation and Network & Connectivity Requirements guides ahead of time so they can prepare firewall rules and network access before installation day.
  • Reassure them on security. Onboard does not require any inbound firewall access. All communication is outbound. SSH access to the Edge Node is only available through an encrypted WireGuard® VPN tunnel, and only when explicitly enabled during Collector setup.