IO Manager

Overview

The IO 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 IO 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 (Zigbee2MQTT, ESPHome, 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 IO 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.

Tags

Every data point in ControlBird is a tag: one value, read or written through one mapper. A tag's ID is its mapper's name, and it is unique in your tenant regardless of letter case. Quote a tag ID in an alarm, a report, or a conversation and it names exactly one point.

• An ID is at most 255 characters, in one to 16 segments separated by dots, for example Plant.Boiler1.Pressure.
• An ID cannot contain /, and no segment may be empty or padded with spaces.
• The segment _System is reserved for the plumbing an integration needs.

Dots group tags. Plant.Boiler1.Pressure and Plant.Boiler1.Temperature appear together under Plant → Boiler1; the groups come from the IDs and are never stored separately.

The Four Sections

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: review the suggested tag ID for every point and edit any of them.
5. Provision: create the connection, endpoint, and one mapper per point, each named by its confirmed tag ID.

The wizard proposes an ID that is valid and free in your tenant for each point, so you can accept the suggestions as they are. An ID that is invalid or already taken is refused before anything is created.

Tag Details

Select a tag to see its live value, its connection, direction, source and target, and any alarms, history tables and rule chains attached to it. Each alarm row has a Push toggle for push notifications, and the mapper's last error and email delivery figures appear when it reports them.

• Write value… sends a new value to a tag whose direction writes.
• Delete removes a tag you created that owns its own value. Tags an integration provisioned, and tags that point at an entity elsewhere in your tree, are not deleted here.

Renaming and Publishing

Rename changes a tag's ID. The new ID must follow the rules above and must not match another tag, ignoring case, or nothing is written. Renaming a device or a connection never rewrites the IDs of its tags.

Publish to a server is the Publish… button on a tag's detail. It exposes the tag through one of your server connections (for example an OPC UA or Modbus server); tags that are already server tags have no such button. The suggested ID for the published point is the server connection's controller name, a dot, and the source tag's ID. Edit it before you confirm if you want a different name.

Integrations also create plumbing mappers that you do not configure by hand. They are named <instance>._System.<Purpose> and sit under their own _System group.

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), use Rediscover on the connection in the Connections section rather than editing generated points by hand.
• Bulk import/export for migration. Right-click a connection in Connections and use Import Points… and Export Points… (Ctrl+I and Ctrl+E there) to move tag definitions between environments or to back them up.
• Network discovery to find devices. In the IO Manager, open the Discovery section and select a scanner 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 tags are read-only. Apart from renaming, tags an integration provisioned cannot be 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 connections allow manual tag creation; integrations generate tags automatically via provision programs. Mixing the two on one connection 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.
• Custom connections lack auto-populated metadata. Manufacturer, model, device type, and image are inferred from integration discovery; manually created ones 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.
• Duplicate tag IDs are flagged. The IO Manager refuses a duplicate ID when you create, import or rename a tag. A duplicate written some other way, such as through the Database Browser or a restore, is flagged in the Tags section rather than blocked; rename one of the two.