Device Manager

Overview

The Device Manager is the application you use to discover, create, and manage the protocol integrations that bring real-time device data into ControlBird. It sits on top of a hierarchical schema of Protocol Controllers, Endpoints, and Mappers: the entities that bind a device's raw data (Modbus registers, MQTT topics, OPC UA nodes) to fields on entities in your Store. Supported protocols include Modbus, MQTT, OPC UA, BACnet, DNP3, EtherNet/IP, HTTP, CoAP, NATS, and SMTP, each backed by a service extension in the catalog.

The Device Manager offers two paths to the same result. The guided integration path uses prebuilt templates and a wizard to auto-generate the controller, endpoint, and mapper entities for you. The custom device path lets you create those entities by hand for protocols or devices that have no prebuilt template. Use a guided integration whenever a template exists (Ecobee, Tasmota, an MQTT broker, a Modbus TCP service, and so on); reach for a custom device when you need full manual control over points and addressing.

Key Concepts

Two paradigms underpin the Device Manager. A protocol defines the wire mechanics through three entity layers; an integration is a prebuilt configuration that auto-generates those protocol entities for you.

Each protocol adds its own configuration options on top of these concepts. A Modbus integration, for example, exposes protocol-specific mapper settings such as register type, address, and byte order. See the Modbus guide for the full Modbus-specific reference.

The Workspace

The Device Manager UI is a split pane: a tree on the left showing protocol controllers, integrations, and discovered devices, and a detail pane on the right showing information and actions for the selected item. A status bar at the bottom counts devices, endpoints, and live points across the platform.

The tree is organized as: Discovery (pinned first, with found devices and scanner controls), followed by protocol groups and the ControlBird Cluster group (if applicable) sorted alphabetically by name, then Unassigned Devices (pinned last, for devices that cannot be placed under a protocol).

Common actions and where to find them

The Integration Wizard

The Integration Wizard walks you through a five-step flow to add a prebuilt integration. Each step renders dynamically from the integration's configuration form, then runs its discovery and provision steps.

1. Select Integration: choose an integration from the catalog.
2. Connection: fill in the connection configuration form.
3. Discovery: discover available devices and select which ones to provision.
4. Configure: map device attributes to your entity tree.
5. Provision: create the controller, endpoint, and mapper entities for the selected devices.

Common Patterns

• Guided first, custom as fallback. When a template exists for your device, use Add Integration; it generates the controller, endpoint, and mapper entities for you. Use Create Custom only when no template applies.
• Subscribe vs. Poll. Set a mapper's ReadMode to Subscribe for event-driven protocols that emit change notifications, and Poll with a suitable PollIntervalMs for protocols that require periodic reads.
• Rediscover to resync. When an integration's source changes (a device is added or renamed), right-click a connection in the tree and use Rediscover rather than editing generated points by hand.
• Bulk import/export for migration. Use keyboard shortcuts Ctrl+I (Import) and Ctrl+E (Export) to move device definitions between environments or to back them up.
• Network discovery to find devices. In the Device Manager tree, expand the Discovery group and select a scanner or the Discovered devices section to run a scan. Use mDNS, SSDP, Bluetooth LE, or TCP port scanning to locate devices on the local network, then provision the results into controllers and mappers.

Troubleshooting & Limitations

• Integration devices are read-only. Devices marked as integration devices cannot have points added, edited, or deleted directly. To change them, re-run discovery or rediscovery to sync with the integration source.
• Choose one editing path per device. Custom devices allow manual point creation; integrations generate points automatically via provision programs. Mixing the two on one device conflicts, so pick one path.
• Connection mode must match the protocol. A controller's connection mode defaults to a single active connection with automatic failover. Changing it affects failover behavior; some protocols (e.g. MQTT) need to allow multiple concurrent connections.
• Don't mix read modes on one endpoint. Subscribe expects the device to emit change notifications and Poll falls back to periodic reads; mixing modes on the same endpoint can lead to duplicate data.
• Bulk operations respect the current view. Bulk delete and export apply to the currently visible result set (after search/filter), not all devices, so apply filters carefully.
• Custom devices lack auto-populated metadata. Manufacturer, model, device type, and image are inferred from integration discovery; manually created devices use defaults.
• Add guardrails for writes. Use Alarm Behaviors or Rule Chains to enforce business-logic constraints on writes to device points.
• Network discovery is advisory only. Discovered devices (from mDNS, SSDP, Bluetooth LE, and TCP scanning) must be manually provisioned into controllers and mappers before they take effect.