Wirepas Software and APIs architecture

This document describes on a high level how the Wirepas software is structured and what are the various APIs available from Wirepas. The document explains the different software components and associated APIs available for the different layers, from embedded software to cloud APIs. It also lists the available tools from Wirepas.

What you’ll learn

• The core structure of Wirepas software from embedded software to the cloud
• What each software component does
• 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) up to backend API like Gateway to Cloud API 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
• Cloud Backend including a gateway-to-cloud interface to connects the Wirepas system to a Cloud server
• Cloud components: End-user application and Monitoring Tools

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-cloud API & Tools: Covers the Gateways software and Gateway-to-cloud APIs
3. Wirepas Backend components API & Tools: All backend and clouds components

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 [8].

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 cloud API and, Tools 

The Wirepas Gateway and associated API makes the link between the local Wirepas Mesh networks and the cloud. Wirepas provides a reference implementation of the Gateway allowing to control all Wirepas Mesh features from the cloud. 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 Cloud 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 Cloud 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 Network side and on the Cloud side.

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

APIs description & Tools

Wirepas Gateway to Cloud API

The Wirepas gateway to Cloud 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 relies on the MQTT protocol to connect all gateways to a backend service which can be either a Wirepas backend or a custom backend running either in the cloud or on an on-premise server.

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 cloud API offers 4 main services:

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

Wirepas Backend components API & Tools

Wirepas also provide additional tools on the cloud/server side. Two of them are highlighted below:

1. Wirepas Network Tool (WNT). WNT is a monitoring tool that can be used to monitor the Wirepas Mesh network. This tool collects and processes diagnostic messages sent by nodes at a configurable time interval. WNT also allows to do node updates (OTAP) and also to configure node parameters using the Remote API. The tool consists of a Server component and a Client that is a Windows application. More information on WNT can be found on the WNT documentation page [5]
2. Wirepas Positioning Engine (WPE). WPE is also a server component that can be used to compute position based on location information sent by nodes in the Wirepas Mesh network. WPE runs together with the WNT services. Positioning information of assets can be retrieved via a dedicated API detailed in the MQTT JSON API section.

The Wirepas Backend is a reference implementation of WNT and WPE backend running on a Linux Server. It implements on one side the Wirepas Gateway to Cloud API over MQTT/protobuf and on the other a set of APIs for WNT Client and Positioning.

Wirepas provides installation scripts for Backend deployment on customer servers. Installation procedures and requirements are available for the Wirepas Services Installer User Guide [7].

Wirepas Backend components API 

Wirepas Network Tool (WNT) Backend API

The WNT API allows to interact with the WNT backend. This is the API used by WNT Client to communicate with the server. This API relies on a combination of WebSocket and HTTP to interact with the backend.

The API is documented in [6] and can be used to connect the end-user IoT platform to it. Wirepas Positioning data is also available from this API.

NOTE: Wirepas Network Tool does not process the actual application data from the mesh network, as a consequence user data is not available from the WNT API.

MQTT JSON API

Part of the WNT API, the MQTT JSON API is dedicated to positioning. With it, it is only possible to receive processed data from the positioning solver. Its description is available in the WNT API documentation.
The solver configuration is also done via the WNT API.

Summary

Here is a summary of the various APIs offered by Wirepas on the complete system which have been covered in this document.

The next table summarize where to find the API & Libraries description and the associated documentation:

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] WNT Documentation
[6] WNT Backend API
[7] Wirepas Services Installer User Guide
[8] Wirepas Release Notes

Revision History