Introduction¶
This guide describes how to migrate a Wirepas Mesh network deployment from the Wirepas Network Tool (WNT) to the Wirepas Network Management System (NMS). NMS is the next-generation platform for monitoring and managing Wirepas Mesh networks, replacing WNT as the backend, API, and user-interface tooling for network operations and maintenance.
The guide is written for customers and integrators who already operate a WNT 4.4 deployment and are moving to NMS 1.3.x. It focuses on the migration process itself — The workflow, key decisions, and points requiring attention. It does not reproduce the installation, configuration, administration, or API material already covered in the existing NMS and WNT documentation; instead, it points to those documents at each relevant step. Please keep them at hand while following this guide. The applicable documents are listed in the References section.
Note
WNT and the Wirepas Positioning Engine reach end of support on 31 August 2026. Wirepas strongly recommends planning and completing the migration to NMS before that date. See the WNT & Positioning Engine End-of-Support Notification.
Before You Begin¶
Compared with WNT’s single-server architecture, NMS is a cloud-native system built on scalable microservices, standard security protocols (TLS, OAuth2, OpenID Connect), an integrated Keycloak-based identity and access management layer, and a rich set of REST APIs. For a full description of the product, its components, and its architecture, see the Wirepas NMS System Overview.
For the Wirepas Mesh devices themselves the transition is largely transparent: gateways are reconfigured to route monitoring and management traffic to the NMS MQTT broker instead of, or alongside, the WNT backend. No node firmware change is required for the migration as such, provided the deployed firmware and gateway versions meet the NMS compatibility requirements.
Compatibility¶
Before migrating, confirm that the deployed firmware and gateways meet the NMS 1.3.x compatibility requirements. The authoritative and up-to-date list is maintained in the Wirepas NMS 1.3.x Release Notes/Compatibility Summary
Constraints to Be Aware Of¶
NMS introduces a number of operational constraints that differ from WNT and that may affect how existing deployments are organised. Review these before planning the migration; full details are in the NMS 1.3.x Release Notes/Compatibility Notes.
Plan Your Migration¶
Two migration approaches are available. They are not mutually exclusive — a deployment can be migrated network by network or gateway group by gateway group, applying the most suitable approach to each.
Approach |
Summary |
When to use |
|---|---|---|
Parallel (zero downtime) |
Gateways route traffic to NMS and WNT at the same time using dual transport services, so monitoring continues uninterrupted while NMS is validated. |
When any interruption to monitoring is unacceptable and gateways support dual transport. Recommended for production environments. |
Phased (planned downtime) |
WNT is stopped and gateways are switched over to NMS within a maintenance window. Simpler to execute, but WNT monitoring is unavailable during the cutover. |
When a maintenance window is acceptable and a simpler one-step cutover is preferred. |
The execution steps for each approach are described in the Execute the Migration section. Whichever approach is chosen, both the NMS and WNT preparation sections below apply.
Prepare NMS¶
Install and validate NMS before connecting any production devices. This lets the team become familiar with the new platform and confirm that required functionality works as expected ahead of the cutover.
Note
Do not perform any NMS feature that requires downlink — such as OTAP or device ping — until all gateways have been migrated. Stop any running OTAP operation before starting the migration.
Dimension and Install¶
NMS can be deployed on Kubernetes (recommended, and the appropriate choice for large networks) or on Docker Swarm. Infrastructure requirements depend on network size and data traffic and differ from WNT; size the deployment using the Wirepas NMS Dimensioning Guide, then follow the Wirepas NMS Kubernetes Installation Guide or the Wirepas NMS Docker Swarm Installation Guide as appropriate.
Configure¶
NMS should be configured for the mesh size, data traffic, and Wirepas Mesh network type (for example Low Energy, Low Latency, or NRLS). The installation guides describe the critical settings and include example configuration templates in the installation package. For ongoing administration and configuration, refer to the Wirepas NMS System Administration and Maintenance User Guide.
Set Up Users¶
NMS manages users through Keycloak, providing role-based access control that is more granular than WNT’s administrator/operator model. WNT user accounts cannot be imported into NMS and must be recreated. Plan the user and role mapping in advance and create the accounts following the System Administration and Maintenance User Guide and the Wirepas NMS User Guide.
Get Familiar with the UI and APIs¶
NMS provides a new web user interface and a modern set of REST APIs. Before going to production, exercise the views and operations the team relies on, and test any API integrations that previously used WNT. See the Wirepas NMS User Guide and the Wirepas NMS Backend API Documentation.
Prepare WNT¶
Back up the existing WNT instance before switching to NMS. Taking a snapshot of the instance is preferred where possible. WNT stores time-series data in InfluxDB and other metadata in PostgreSQL; a PostgreSQL backup is sufficient to roll back to WNT. For backup procedures, refer to the Wirepas Services Installer for WNT4.4 User Guide.
Note
Do not perform any WNT feature that requires downlink — such as OTAP — during the migration. Stop any OTAP operation that is currently running before proceeding.
Information to Gather from WNT¶
Collect the following from the existing WNT 4.4 deployment before starting. This information is needed for NMS dimensioning, metadata migration, and gateway reconfiguration. Refer to the Wirepas Network Tool v4 Client User Guide and the WNT4 Backend API for how to obtain it.
Network information: network ID(s) and friendly names, node count per network and in total, diagnostics interval, and application data profile.
Gateway information: gateway IDs, the current MQTT broker hostname/port and the MQTT username the gateways use, and the gateway software version.
Users and integrations: the list of WNT users with their roles, and any external systems integrated through WNT’s MQTT/JSON API.
Locations: node position data and any floor-plan images used in WNT. NMS does not support indoor mapping and cannot render custom maps; keep them as backups.
Migrate Metadata¶
Data migration from WNT to NMS concerns metadata — networks, gateways, nodes and their names, descriptions, and locations. Historical diagnostics are not migrated: NMS builds its own analytics and statistics from scratch once gateways start connecting.
Data |
Migrated |
Notes |
|---|---|---|
Network, gateway, and node definitions |
YES |
Network IDs, gateway IDs, and node addresses. |
Descriptive metadata (names, descriptions, GPS coordinates) |
MANUAL |
Migrated via the NMS REST APIs or the NMS Integration Tool. |
Network parameters (diagnostics interval, app config) |
MANUAL |
Reconfigured in NMS after migration. |
User accounts |
NO |
Recreated in NMS Keycloak (see Set Up Users). |
Historical diagnostics and OTAP history |
NO |
NMS builds fresh analytics and re-queries firmware versions after connection. |
The recommended method for bulk metadata migration is the NMS Integration Tool. It imports networks, gateways, nodes, and location data via the NMS REST APIs and offers several example options with documentation in the repository. The same outcome can be achieved directly through the APIs described in the Wirepas NMS Backend API Documentation.
After importing, verify that networks, gateways, and nodes appear correctly in the NMS web UI.
Note
This step requires both WNT (connected gateways are unnecessary; only WNT Postgres must be reachable) and NMS to be active. Required data can be fetched from WNT Postgres. After complete migration — that is, all networks and gateways are connected and automatically created in NMS — metadata can be populated in NMS.
Execute the Migration¶
After installing and configuring NMS, reconfigure the gateways to connect to the NMS MQTT broker. The gateway connectivity parameters (broker hostname, MQTT username, and credentials) and the procedure to retrieve NMS gateway MQTT credentials are detailed in the Wirepas NMS Kubernetes Installation Guide.
By default, gateways connect to the NMS MQTT broker using simple username and password authentication, as with WNT. NMS
introduces the mqttgatewayuser username with dedicated ACLs for gateway access. For advanced connectivity options,
refer to the installation configuration files.
Note
Ensure no active OTAP process exists in WNT or NMS before starting the migration.
Parallel Migration (Zero Downtime)¶
If the gateways support dual transport, configure an additional transport service pointing to the NMS MQTT broker while the existing transport to WNT remains in place. Roll the change out gradually: start with a small subset of gateways (around 5–10 %), confirm in the NMS UI that those gateways and their nodes appear online and are sending data, then roll out to the remaining gateways. For gateway transport service configuration, refer to the relevant gateway documentation on the Wirepas Developer Portal depending on your gateway type.
Phased Migration (Planned Downtime)¶
Confirm that NMS is fully operational, then schedule and announce a maintenance window. During the window, stop the WNT backend services, update the gateway transport configuration to point to NMS in place of WNT, and deploy the change to all gateways. Verify in NMS that gateways come online within one to two diagnostics intervals and that network data is flowing.
Validate and Stabilise¶
After the cutover, confirm that NMS is operating correctly:
Expected gateways show as online in the NMS UI.
Expected nodes appear and show as online within one to two diagnostics intervals.
Monitoring dashboards and KPIs load.
The topology view renders for each network.
Each newly created Keycloak user can log in with the expected permissions.
Note
NMS needs time to populate after gateways connect. Reliability analytics are based on a 24-hour rolling window, traffic statistics are aggregated periodically, and topology and firmware inventory build up as nodes report in. Allow 24–48 hours for the views to fully reflect the network state; some analytics may show “no data” until enough data has been collected. All functionality works correctly during this period. The NMS User Guide describes each view in detail.
Roll Back If Needed¶
If the migration encounters a critical issue, you can revert the deployment to WNT.
With parallel migration, WNT was never stopped: remove the NMS transport service from the gateway configuration, leaving the WNT transport in place, and confirm that WNT is receiving data from all gateways.
With phased migration, restore the previous WNT gateway transport configuration on all gateways, restart the WNT backend services, and confirm that the gateways reconnect to WNT and data flow is restored.
Note
Do not decommission the WNT server immediately after a successful migration. Keep it available as a fallback until the team is fully confident in NMS operation. Investigate any NMS issues with Wirepas support before re-attempting the migration.
References¶
Revision History¶
Date |
Version |
Notes |
|---|---|---|
16/06/2026 |
v1.0 |
Initial version |
Confidentiality: confidential - Should not be shared without Wirepas approval
Legal Notice¶
Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.
Copyright © 2026 Wirepas Oy