Migrating from ThingsBoard to Connhex: a comprehensive guide

This guide provides a roadmap for migrating your IoT solution from ThingsBoard to Connhex.

While both platforms serve IoT needs, they have different philosophies. ThingsBoard is an all-in-one platform with a rich UI for many configurations, whereas Connhex is a suite of specialized, API-first services designed for flexibility and integration.

General migration philosophy​

To successfully migrate from ThingsBoard to Connhex, you'll need to keep in mind their different approaches:

• ThingsBoard: often provides an all-in-one experience with integrated UI for configuration and management.
• Connhex: emphasizes a decoupled, API-driven approach. You'll interact with distinct services (Resources, IAM, Core, Rules Engine, OTA, etc.) and build your end-user UIs on top of these APIs.

Main concepts mapping​

Detailed migration considerations​

1. Data Model (Entities & Attributes)​

• ThingsBoard: structured entities (Device, Asset, Customer, Tenant) with predefined relationships and attribute scopes (Server, Shared, Client).
• Connhex: uses generic Resources defined by flexible JSON Schemas. Relationships between resources are also defined and managed.
• Migration:
  1. Define JSON Schemas in Connhex Resources for each of your ThingsBoard entity types (e.g., a "Thermostat" device schema, a "Building" asset schema).
  2. Migrate ThingsBoard attributes:
     • Server-side attributes become part of the resource's data in Connhex.
     • Shared attributes can be part of the device's initial configuration delivered by Connhex Remote Init or managed as updatable resource attributes.
     • Client-side attributes are data points reported by the device and stored as part of its resource data.
  3. Recreate entity hierarchies (e.g., Tenant > Customer > Asset > Device) by defining relationships between your Connhex Resources. Make sure you leverage Connhex IAM for authorization and permissions.
• Keep in mind: the shift from fixed entity types to flexible JSON Schema-defined resources requires a design phase, especially when mapping complex relationships.

2. Telemetry data​

• ThingsBoard: ingests telemetry as key-value pairs.
• Connhex: Connhex Core ingests messages. The Connhex Message Policy (CMP) is highly recommended for new device integrations, categorizing data into infos (static device info), params (configurable parameters), and data (time-series telemetry). This allows for optimized storage and retrieval.
• Migration:
  1. Make sure the current device firmware sends data in a format compatible with Connhex Core (JSON or SenML).
  2. If possible, adopt CMP for long-term benefits. For existing devices, you might initially send all telemetry as data and refine later, or use Connhex Mapper if firmware changes are difficult.
• Keep in mind: there are multiple options here. Choose what best suits your needs based on how difficult modifying firmware can be: understanding and implementing CMP is harder, but leads to substantial performance gains in the medium term. Configuring the Connhex Mapper is often immediate, but you'll be missing out on optimizations.

3. RPC (Remote Procedure Calls)​

• ThingsBoard: has dedicated client-side and server-side RPC mechanisms, including persistent RPCs.
• Connhex: does not have a direct "RPC service." Functionality is achieved through standard device communication protocols (MQTT, HTTP) managed by Connhex Core and potentially Connhex Edge (for the control channel).
• Migration:
  • Server-to-Device (ThingsBoard Server-Side RPC):
    1. Define MQTT topics or HTTP endpoints for commands.
    2. Devices subscribe to these topics/listen on endpoints.
    3. Your application (or Connhex Rules Engine) publishes command messages.
    4. For two-way RPCs, the device publishes a response to a predefined reply topic/endpoint.
  • Device-to-Server (ThingsBoard Client-Side RPC):
    1. Device publishes a message to a specific MQTT topic/HTTP endpoint, for example using the Edge Rules Engine addon.
    2. This message can trigger Connhex Rules Engine or a custom application backend built on Connhex APIs, which processes the request and can send a response back to the device.
• Keep in mind: persistent RPC logic (queuing commands for offline devices) is only managed if your devices are using Connhex Edge, otherwise needs to be integrated into your firmware. Request-response correlation might need including a message_id field.

4. Alarms​

• ThingsBoard: alarms include types, severities, status, and propagation. They are often configured in Device Profiles or the Rule Engine.
• Connhex: alarm logic is primarily built using Connhex Rules Engine, which provides threshold/delta conditions, time windowing and duration logic.
• Migration:
  1. Recreate alarm conditions (thresholds, state changes) as Conditions within Connhex Rules Engine.
  2. The Rules Engine will take care of triggering Connhex Notifications.
• Keep in mind: alarm logic needs to be adapted to APIs exposed by Connhex Rules Engine.

5. OTA updates​

• ThingsBoard: manages firmware/software in an OTA repository and assigns them to devices/profiles.
• Connhex: Connhex's OTA Firmware Update uses Models (device types supporting OTA) and Releases (firmware versions for a model). Devices authenticate using init_id and init_key.
• Migration:
  1. Define Models in Connhex OTA for your device types.
  2. Upload firmware versions as Releases for these models.
  3. Ensure devices can authenticate with init_id and init_key.
  4. If you're not using Connhex Edge: implement the HEAD (check) and GET (download, with Range header for partials) logic on the device.
  5. If you're not using Connhex Edge: implement checksum verification on the device.
• Keep in mind: device-side logic for fetching updates needs to align with Connhex's OTA flow.

6. Device provisioning & initialization​

• ThingsBoard: uses provision keys/secrets in Device Profiles. Supports claiming.
• Connhex:
  • Connhex Provisioning: creates the Connectable (digital twin), issues certificates via Connhex Certs.
  • Connhex Remote Init: delivers the initial configuration (connection parameters, custom settings) to the device upon its first authenticated connection (using init_id, init_key).
  • Connhex Manufacturing: stores detailed production lifecycle data.
  • Connhex Device Ownership: for associating users to devices.
• Migration:
  1. Integrate your manufacturing/provisioning process with Connhex Provisioning to create connectables and their initial init_id/init_key.
  2. Configure Connhex Remote Init to serve necessary boot configurations.
  3. Device firmware must implement the logic to fetch its configuration from Remote Init using its init_id/init_key.
  4. If you use device claiming, migrate this flow to Connhex Device Ownership.
• Keep in mind: this is a multi-service process in Connhex, which can be completely automated by using the Connhex CLI. The device needs to be aware of init_id and init_key, or use a migration key.

7. User interfaces (UI)​

• ThingsBoard: provides built-in UIs for administration, dashboards and device management.
• Connhex: is API-first. It provides Connhex Control (a back-office UI for administration), Connhex Copilot (an intelligent chat for Connhex administrators) and Grafana integration for internal dashboards. Even if end-user applications must be custom-developed, Connhex includes Client modules (e.g., ngx-admin-ui-sdk for Angular) to speed up frontend development.
• Keep in mind: this is a major difference. If you relied on ThingsBoard's UIs for end-users, you will need to build these from scratch or adapt templates.

Connhex-specific features​

While migrating your solution from ThingsBoard to Connhex, you might find some related features interesting. Here's a partial list of functionalities that, with a small effort, might be beneficial to your solution:

• Connhex IAM: granular identity and access management with realms (for multi-application/business unit segregation) and tenants (for customer/data segregation). This offers a much more flexible permission modeling than ThingsBoard's roles.
• Connhex Mapper: useful for transforming message payloads from legacy devices or integrating devices with non-standard protocols without firmware changes.
• Connhex Exporter: asynchronous, scalable export of data for reporting or archiving, reducing load on primary systems.
• Connhex Manufacturing: dedicated service for tracking detailed manufacturing data, separate from operational IoT data. This can be very powerful for traceability and quality control.
• JSON Schema for Resources: provides strong data validation and a clear definition for all your "entities", enabling better API consistency and tooling.
• Connhex Rules Engine - Events: detailed historicization of rule triggers and condition states, useful for auditing and debugging.
• Connhex Core: includes some advanced data handling strategies, like aggregation and decimation or configurable backups and data retention

If you're looking to understand how Connhex-specific features, like Connhex Pay and Connhex AI, the documentation is usually a good starting point.

Migrating from ThingsBoard to Connhex: where to go from here​

Migrating from ThingsBoard to Connhex is a shift towards a more modular, API-centric architecture.

While usually requiring more custom development, a Connhex-based solution offers greater flexibility and control: to ensure the smoothest experience possible, start with a small subset of devices or a single use case. A great starting point is to:

• define the data modeling layer through JSON Schemas
• decide whether you'll be using the Connhex Mapper or update your devices' firmware

If you're struggling with some aspects of the migration from ThingsBoard to Connhex, feel free to simply reach out. We've already supported many device manufacturers in moving from a ThingsBoard-based pilot to an industrial-grade solution based on Connhex: chances are your questions have already been raised before!