Introduction

The image below summarizes the various APIs offered by Wirepas for the complete system covered in this document.

Wirepas Software and APIs architecture

This document provides a high-level overview of the Wirepas software structure and its available APIs. It details the software components and APIs across layers, from embedded software to backend, and lists the tools offered by Wirepas.

What you’ll learn

• The core structure of Wirepas software, from embedded software to the backend
• Function of each software component
• Available libraries and APIs, and where to find them
• Available tools to support your development

What you’ll need

A basic understanding of Wirepas Mesh concepts and terminology available from the Wirepas Mesh Concept document [1]

Wirepas software

Wirepas offers a complete set of software components and APIs to design an optimized and scalable IoT product. It starts from the Wirepas Mesh software (sitting inside the nodes), Gateway to backend API, NMS backend REST APIs and associated tools. From each of those layers, Wirepas offers an API and associated tools.

Below is a picture of a typical Wirepas Mesh system where the key components are:

• Nodes and gateways: the actual devices embedding Wirepas Mesh
• Gateway to backend interface: connects the Wirepas Mesh to backend
• Backend components: Wirepas NMS and end-user applications

In this documents we will describe the system which can be organized into three parts:

1. Wirepas Nodes API & Tools: Covers all embedded software running in radio nodes
2. Wirepas Gateways and Gateway-to-Backend API & Tools: Covers the Gateways software and Gateway-to-Backend APIs
3. Wirepas Backend Components API and UI: Wirepas NMS with its Web UI, powerful REST APIs and many other feature sets

Wirepas Nodes API & Tools

The first part of the system contains the Wirepas Mesh network itself. The network consists of all the Wirepas nodes including the nodes that connected to the gateways. The nodes connected to the gateways are called Sink nodes.

Each radio device contains the following software components:

• Wirepas Mesh stack: the actual Wirepas Mesh protocol with associated sub-components like the bootloader.
• An application that can be either a Wirepas reference application or the actual product application.

Two products architectures are supported:

1. Single-MCU architecture: Both the Wirepas Mesh stack and the application run in the Radio Integrated Circuit (IC). Both application and stack are scheduled on the MCU using Wirepas application scheduler.
2. Dual-MCU architecture: The Wirepas Mesh stack and the Dual-MCU application run in the Radio IC while the Application itself runs in another MCU. The Application communicates to the Radio subsystem using a UART or USB serial link. The Dual MCU application is typically also running inside the gateways (this will be covered later within this document).

From a system point of view, the overall software architecture is the same in both the Single and Dual MCU architectures as they both contain the Wirepas Mesh stack plus the Application.

Single-MCU Architecture

The Wirepas Mesh stack is provided as a binary and includes all the components related to:

• The Hardware Abstraction Layer (HAL)
• The Wirepas Mesh MAC and Routing layers
• The Wirepas Scheduler
• The Support and Application functions: API, OTAP, Public Joining …

The Application sits on top of the Mesh stack, has access to the peripherals using its own HAL, and is scheduled by the WM Scheduler

A bootloader is provided together with the Wirepas Mesh stack. The bootloader is responsible for bootstrapping and update management during the Over the Air Update process (OTAP). More information about the bootloader is available in the following documents [2]

The flash memory is organized in different areas as per the picture below:

The mapping of the different areas is defined by Wirepas. The Customer application seats after the Wirepas Mesh stack. The available memory for the application depends on two things:

• The size of the Flash memory in the Radio IC
• The memory that is reserved for the scratchpad image. The Scratchpad memory area is reserved to store update (OTAP) images

More information about the supported Radio IC’s can be found in the Wirepas Mesh stack Release note corresponding to the stack used [5].

APIs description and Tools

Single-MCU API & SDK

The Single-MCU API is defined as the API between the Wirepas Stack and the application.

The Single-MCU API consists of libraries, each dedicated for a specific use, such as data handling or time services. The API is kept backward compatible. This enables an old application to operate with a newer stack firmware.

The Single-MCU API is fully open source and is documented as part of the SDK that is available in GitHub [3].

Wirepas Software Development Kit (SDK)

The SDK enables the developer to build applications that run on the same MCU as the Wirepas stack. The SDK is provided as an open-source component. Wirepas provides a single SDK for all MCU and boards supported by Wirepas where the developer can easily add a new board corresponding to their product.

The SDK contains:

• Support for multiple boards (primarily Silicon vendors reference boards)
• Wirepas Reference applications, which are heavily tested by Wirepas among them: Dual-MCU Application described in next chapter and Positioning Application for asset tracking
• Unitary or more complete examples like how to send and receive messages and how to use Bluetooth beacons
• Build environment relying on “make” project using GNU compiler
• Scripts to build the various images including update images (.otap scratchpad file)

The SDK has minimal dependencies to adapt to multiple development environments. It can be used on different OSs and can be integrated with multiple IDE.

Dual-MCU API and Tools

The Dual-MCU API is developed by Wirepas to control a Wirepas node from an external MCU over a UART or USB. Wirepas provides a reference application called the Dual-MCU Application which implements the Dual-MCU API. The application is used as the reference application for Sinks in Gateways and also as the radio part in Dual-MCU product architecture.

The API is fully documented in [4] and offers:

• Master/Slave protocol
• Reliable communication with CRC
• Supports multiple bitrates

The Dual-MCU API implements a subset of the Single-MCU API.

Wirepas also provides the C-Mesh API library which is an implementation example of the Dual-MCU API in the Application MCU. The C-Mesh API is a wrapper on top of Dual-MCU API, coded in C language.

The C-Mesh API library can be ported to any OS or even to a bare-metal implementation. A reference implementation on top of the Linux operating system is provided as an open-source component. The reference implementation is used by the Wirepas gateway driver, which will be described later.

Remote API

The Remote API contains a subset of the Dual-MCU API and offers a mechanism to configure Wirepas Mesh nodes remotely from the backend without the need for implementing this in the application. The Remote API uses normal Wirepas Mesh data packets to interact with the stack directly from the backend. The Remote API is mainly intended to configure nodes or to get query the status of different nodes.

For example, the Remote API can be used to:

• Configure nodes: set network address and security keys
• Monitor nodes state during the OTAP -update process

Wirepas Gateways, Gateway to Backend API and, Tools

The Wirepas Gateway and associated API makes the link between the local Wirepas Mesh networks and the Wirepas backend. Wirepas provides a reference implementation of the Gateway allowing to control all Wirepas Mesh features from the backend. The Wirepas Gateway connects to a Sink over UART or USB. The Sink node implements the Wirepas Mesh stack and the Dual-MCU Application to communicate with the network.

Wirepas Gateway

The Wirepas Gateway operates on Linux operating system. The gateway contains different components that can be adapted to the end-user needs. The modular approach combining some parts coded in C and some others in Python allows supporting multiple configurations. Below is a block diagram of the Wirepas Gateway.

• The Sink Service is a compiled application coded in C language. The Sink Service is responsible for managing the link between the Sink and the Gateway drivers. It sits on top of the C-Mesh-API library and connects to the Linux host operating system D-Bus.
• D-Bus is a Linux component. It is a Message-oriented middleware mechanism that allows communication between multiple processes running concurrently on the same machine (source Wikipedia)
• The Transport Service implements the Wirepas Gateway to Backend API. The Transport Service is coded in Python. It connects on one side to the D-Bus and on the other side to an MQTT Broker. The Transport Service implements the Wirepas Gateway to Backend API that is described below.

Note: the main benefit of D-Bus is to have a logical bus. It allows having several Sink Services and Transport Services running in parallel in the same machine. The D-Bus allows adapting the application requirements both on the local Wirepas Mesh network and on the Backend side.

The Wirepas Gateway is available both as a native delivery with Sink Service and Python wheel or as a Docker abstraction.

APIs description & Tools

Wirepas Gateway to Backend API

The Wirepas Gateway to Backend API offers a complete API to manage the Data flow with Wirepas Mesh network as well as the configuration and different services offered by Wirepas Mesh (e.g. OTAP)

This API uses the MQTT protocol to connect all gateways to a backend service, which can be a Wirepas NMS backend or a custom backend running locally, remotely, or on-premise.

The API also uses Protocol Buffer to encode the actual payload. Protocol Buffer offers a lot of advantages compared to a more simple encoding like JSON. Among them:

• It is language-neutral
• It has a strict type structure that has to be followed
• It is an extensible structure that can be extended without breaking the compatibility
• It is efficient as it offers a binary encoding
• It is widely adopted

The Wirepas Gateway to Backend API offers 4 main services:

• Gateway Status
• Gateway configuration including Sink
• Send/receive data to/from a Wirepas node(s)
• OTAP to manage Over The Air Updates of Wirepas Mesh networks.

Wirepas Backend Components API and UI

Wirepas NMS

Wirepas Network Management System (NMS) [6] is a Wirepas Mesh network monitoring and management tool that supports customers in operating and maintaining their networks throughout deployment. Wirepas NMS offers web-based monitoring and management views plus integration APIs for Mesh network functionalities. NMS offers a rich set of features in its web UI and RESTful APIs, in addition to collecting and processing diagnostic messages sent by nodes at configurable intervals. More information on NMS is available in its documentation folder [9].

Wirepas NMS includes an MQTT broker and other scalable internal services to ensure data delivery and support millions of Wirepas Mesh deployments.

NOTE: Wirepas NMS does not process application data from the mesh network; thus, user data is not available from the NMS API or UI.

APIs description & Tools

NMS UI

The modern web user interface [7] of NMS offers extensive management and monitoring features for Mesh administrators, operators, and end users. It provides Wirepas Mesh monitoring through contemporary time series views, tables, and an interactive world map. In addition to other Wirepas APIs, the NMS UI functions as an intuitive Wirepas Mesh management and control panel.

NMS Backend APIs

Wirepas NMS Backend APIs provide a comprehensive, REST-based integration layer for monitoring and managing Wirepas Mesh networks programmatically. They expose all key NMS capabilities—metadata, status, topology, alerts, analytics and OTAP-related inventories—via well-structured resource-oriented endpoints secured with OAuth2 client credentials for customer backend integrations and applications.

The APIs follow modern REST best practices with UUID-based resources, rich RSQL query filtering, cursor-based pagination, and clear separation between standard CRUD operations and “action” endpoints for synchronous or asynchronous operations (for example, triggering Mesh actions or refreshes). Integration patterns include metadata synchronization (networks, gateways, nodes, locations), alert polling to external monitoring/ticketing systems, analytics and reliability metrics retrieval, device online status queries, traffic statistics, network topology, and software component inventory.

For full details, see its main documentation [8], which also provides credentials for OpenAPI-based online documentation of recent release at https://wirepas-nms-apidocs.dev-wirepas.com.

NMS UI relies solely on NMS backend RESTful APIs, demonstrating their power.

References

[1] Wirepas Mesh Concept
[2] Wirepas Mesh Bootloader Development Guide
[3] Wirepas Mesh SDK Github
[4] Wirepas Mesh Dual-MCU API Reference Manual
[5] Wirepas Release Notes
[6] Wirepas NMS System Overview
[7] Wirepas NMS - User Guide
[8] Wirepas NMS Backend API Documentation
[9] Wirepas NMS Folder

Revision History

Legal Notice

Use of this document is strictly subject to Wirepas’ Terms of Use and Legal Notice.

Copyright © 2026 Wirepas Oy