[Article] An Introduction to WSO2 IoT Architecture

  • By Geeth Munasinghe
  • |
  • 28 Jul, 2017

WSO2 IoT - An Overview

WSO2 IoT Server is a comprehensive open source IoT solution that enables enterprises to manage their mobile and Internet of Things (IoT) devices. All its capabilities are exposed through industry standard Swagger annotated REST APIs. It allows device manufacturers to create their own device types and enroll and manage them securely. It is designed in a way to protect both devices as well as its data. It also provides analytics capabilities to gather sensor data, visualize them real time, identify patterns and convert these to responsive action. You can also extend its capabilities to securely manage mobile devices. Figure 1 below illustrates WSO2’s IoT architecture.

Figure 1

WSO2 IoT has evolved significantly to what it is today. It first started out as a complete platform to manage mobile devices and later evolved to a more complex system by incorporating capabilities to manage mobile devices as well as all types of IoT devices. The initial release came with the ability to manage Android and iOS, and Windows mobile device management and application management was added later.

Deep Dive into WSO2’s IoT Architecture

Figure 2 below shows an in-depth architecture of WSO2’s IoT offerings. The key difference between the two architecture diagrams is that both Apps and Devices are represented in the ‘Interaction’ layer.

Figure 2

As indicated in Figure 2, the overall architecture can be broken into the following 4 layers. We take a closer look at each of these layers below.

  1. Connected Device Management Core
  2. API Layer
  3. Security and Integration Layer
  4. Interaction Layer

Connected Device Management Core (CDM)

This is the core of the IoT server. It manages and controls all the functionality WSO2 IoT offers. This acts as the brain of the WSO2 IoT platform. It is designed with many extensions points, hence most of its functionalities can be extended and customized. However, the CDM core has evolved into a much more capable and mature platform and any device type can be easily integrated.

Figure 3

As shown in Figure 3 the CDM core consists of the following components:

  1. Device Management
  2. Device Type Management
  3. Policy Management
  4. Operation Management
  5. Application Management
  6. Configuration Management
  7. Certificate Management
  8. User Management
  9. Push Notification Management
  10. Plugin Management
  11. Compliance Monitoring

Device Management

This part is responsible for enrolling/disenrolling devices with the server, managing device information, such as location, installed applications, device statistics, and runtime information, such as device memory and its usage. Creating/removing device groups and assigning devices to groups also come under this component.

Device Type Management

The device type management component has the capability to add/remove new device types and was added in the WSO2 IoT Server 3.1.0 release. This enables you to describe device features, and generate device operations and device details.

Policy Management and Compliance Monitoring

Policies ensure the devices that belong to a user comply with the corporate rules and regulations. A policy will maximize control of the devices and reduce the risk on corporate data. If a device does not comply with a given policy, the server will be notified of any corrective action, such as re-enforcing the same policy. The policy may include restrictions, such as camera disablement, and configurations, such as VPN or Wi-Fi.

Operation Management

WSO2 IoT Server controls devices via operations. Any message, configuration, restriction, policy or command is sent to a device as an operation. These operations are either pushed to devices through notification mechanisms or the devices are polled at a configured time. Once the device executes the respective operation the result is also sent to the server and is stored in the database.

Application Management

Application management is a major part of mobile device management (MDM). WSO2 IoT provides ways and means to add applications and upload apk/ipa files through the app publisher console. Moreover, users who have enrolled their devices with WSO2 IoT Server can install applications from the app store. The app publisher and store have capabilities to add public apps from the Google Store or the Apple App Store. You can Install the web clips on the devices connected to WSO2 IoT Server. In addition, enterprise enrollment where an administrator installs an application on multiple devices can also be done via the app store.

Configuration Management

Configuration management is used to add pre-requisites and licensing agreements that are required to start enrolling a device. Before enrolling iOS devices, you need to configure the prerequisites, such as plist file and APNS certificates. You need to add the licence agreement that the users need to accept before completing the iOS device enrollment process.

Certificate Management

The certificate managementcomponent has the implementation of the Simple Certificate Enrollment Protocol (SCEP) protocol, which supports device enrollments via mutual SSL configurations. With SCEP, you need to provide an SSL certificate for device authentication and authorization to happen. During the enrollment process, the device generates a certificate and shares it with the server as a Certificate Signing Request (CSR).

User Management

User management comes bundled with WSO2 IoT and facilitates the management and control of user accounts and roles at different levels.

WSO2 IoT’s user store is configured to operate in any of the following modes:

  1. User store operates in read/write mode - In Read/Write mode, WSO2 IoT reads/writes into the user store
  2. User store operates in read-only mode - In Read Only mode, WSO2 IoT guarantees that it does not modify any data in the user store. WSO2 IoT maintains roles and permissions in the database, but it can read users/roles from the configured user store

The use of WSO2 IoT has the following features:

  1. The concept of single user store that’s either external or internal
  2. Ability to operate in read-only/read-write mode on your company's LDAP user stores
  3. Ability to work with Active Directory Directory Services (AD DS) and Active Directory Lightweight Directory Services (AD LDS) in read/write mode
  4. Roles can contain users from external user stores
  5. Improved configuration capability for external user stores
  6. Capability to read roles from LDAP/Active Directory user stores
  7. Implements management permission of the WSO2 IoT console

Push Notification Management

By default, WSO2 IoT Server has implemented push notification providers for MQTT, XMPP, FCM, and APNS. As WSO2 IoT Server is designed to introduce a new push notification mechanism without any hassle, any user can write their own push notification libraries as Java extensions and install them on WSO2 IoT Server.

Push notifications come into play when messages (operations) need to be sent to devices. As mentioned above, there are three ways operations are sent to devices.

  1. Polling
  2. Push notification with the message (operation)
  3. Push notification with the wake-up call

At present, WSO2 IoT Server supports the following push notification mechanisms:

  1. APNS
  2. GCM/FCM
  3. WNS
  4. MQTT
  5. XMPP
  6. HTTP


The device will trigger a network call to a configured endpoint at a pre-set frequency. This network call will be received by WSO2 IoT Server and the pending operations list is sent by the server to the device. Once the device receives those operations it will execute them and store the result until the next network call is triggered. Once it is triggered, the device will send the result of the previous operation list in the same network call to get the next set of pending operations. This is similar to a reverse HTTP call. An out-of-the-box Android agent works in this manner.

Push Notification with the Message (Operation)

This mechanism sends the whole message (operation) to the device as soon as an operation is initiated. WSO2 IoT Server pushes the operation to a message broker and the broker, in turn, sends the message to the device. Once the device executes the operation, the device sends the response back to the message broker and it will send the response to WSO2 IoT Server. The Android sense device type works in this manner out of the box.

Push Notification with the Wake-up Call

This push notification mechanism is used when the respective message broker has constraints about the size of the message (operation) payload. When an operation is initiated, WSO2 IoT Server sends a wake-up message to the respective message broker and it will then deliver this message the device. Then the device will initiate a network call over HTTP to the WSO2 IoT Server to retrieve the pending operations. Once the device receives the pending operations, it will store the execution result until next wake-up call happens. When that wake-up call happens, the device will send the previous operation result in the same network call to retrieve the next pending operations. APNS, GCM/FCM works in this manner. When an operation is initiated, WSO2 IoT Server calls APNS (if the device is iOS) to send the wake-up call to the device. Once the iOS device receives the wake-up, it will call the pre-configured endpoint of the IoT server to receive next pending operations.

Plugin Management

WSO2 IoT Server is designed as a pluggable architecture. When introducing new device types this pluggable architecture is useful. It’s not mandatory to add a plugin though when the user needs to add a custom device type if the device is simple. Most IoT devices are supported without any external plugins being introduced to the IoT server. But if you have a device that requires more complex operations, writing a JAVA plugin might be the most suitable approach.

There are 3 ways new device types can be introduced to WSO2 IoT Server:

  1. Using the device type service and APIs
  2. Via device type descriptor
  3. By writing a Java extension with given interfaces

API Layer

This is the core level at which device management functions and where most of the device communications protocols are exposed as REST APIs in WSO2 IoT Server. All these APIs are equipped with industry standard Swagger annotations, hence stub or client generation can be done easily. Device type related APIs are used because each device type communicates and controls in different ways. For example, Android uses a different message format to control the device compared with what iOS uses. iOS has its own protocol to communicate with the device and its own message formats that can be understood by the iOS device. The WSO2 IoT Server operation core is implemented in a way that it does not need to know what type of message is being sent to the device, the format of the message, and the delivery mechanism. This explains the device type related APIs that can translate and interpret the operation in a way that devices can understand. WSO2 IoT Server provides simple device message protocols, such as JSON, XML, DM SyncML (also known as Open Mobile Alliance Device Management or OMA DM XML) and profile protocol for iOS device management.

Figure 4

Figure 4 shows the most common REST APIs in WSO2 IoT Server and it provides a host of services as listed below. It should be noted that the capabilities are not restricted to the ones listed below and include a much wider spectrum; the list below includes the most commonly-used capabilities.

  1. Device management API
    1. Operation management
    2. Device groups CRUD operations
    3. Assigning devices to groups
    4. Policy management
    5. User management
    6. Device management
    7. Device information update and retrieval
    8. User management
  2. App Publisher API
    1. Adding/publishing an application
    2. Configure workflows for application publishing
  3. App Store API
    1. Install applications to own devices
    2. Install applications to enterprise devices
    3. Uninstall applications
  4. Android API
    1. Enroll Android devices
    2. Adding operations
  5. iOS API
    1. Enroll iOS devices
    2. Add operations
  6. Windows API
    1. Enroll Windows devices
    2. Add operations

Security and Integration Layer

IoT Security and integration play a very critical role in any IoT solution. WSO2 IoT Server is designed to give security the highest priority. When WSO2 IoT Server is used in an enterprise it stores user data, device data. Devices store very confidential information about the business, hence protecting and securing IoT server access controls and associated devices is a key requirement. Furthermore, integrating the IoT server with other applications and user interfaces, and exposing its capabilities to the outside world securely is crucial. Therefore, integration also plays a key role when implementing the IoT server.

WSO2 IoT Server provides the following security protocols to authenticate/authorize users and devices:

  1. OAuth
  2. Basic Auth
  3. Mutual SSL
  4. SCEP
  5. JWT
  6. Scopes

Two levels of authorization take place when initiating an operation. First, it checks if the user is authorized to access the provided APIs. Next, it checks if the user is authorized to access or perform an operation on a given device. If a user is the owner of the device or the device administrator, or the device is shared with the user using a device group, the user can perform the operation on the device.

Figure 5

Integration happens via two components. The first one is the API gateway and the second is the message broker. The API gateway handles HTTP requests and responses the same way the message broker handles MQTT messages between the devices and server. Given that the IoT server supports plug-ins, you can plug an XMPP server or a COAP server to communicate with the devices via new access controls if required.

As all of the admin services are implemented as REST APIs, they are securely exposed for integration through the API gateway. WSO2 IoT Server also exposes the API store functionality as REST APIs. A user can find all the available APIs by just calling the API store endpoints.

Interaction Layer

This layer can be broken into two segments depending on their interaction with the server. As depicted in Figure 6, both of these segments are represented in the same layer. However, as they interact with the server differently, it is better to identify them individually.

  1. Device to server interaction
  2. Apps and external system to server interaction

Figure 6

Device to Server Interaction

This governs how the device connects with the IoT platform. Devices may use different communication protocols to send and receive data and use different messaging formats to communicate. As most device types support over HTTP communications, MQTT and XMPP communication protocols are also introduced in the out-of-the-box IoT server. APNS for iOS, GCM/FCM for Android, and WNS for Windows are added as they are required for mobile device communications. All of the over HTTP calls are securely handled via the API gateway.

Applications/External System to Server Interaction

As WSO2 IoT Server exposes all its functionalities, integration with external systems and applications are pretty straightforward. Securely exposed APIs can be accessed from any device, hence system applications can be extended as well. Not only are the APIs secured, it also provides different authentication mechanisms, such as SSO, SAML, and XACML when connected with WSO2 Identity Server. WSO2 IoT Server consists of four main UI consoles:

  1. Device Management Console
  2. Application Publisher Console
  3. Application Store Console
  4. API Store Console (optional)


Analytics is a crucial part of device management. WSO2’s IoT platform goes over and beyond to provide both real-time and batch analytics. Machine learning is also a prominent capability in WSO2 IoT Server. The WSO2 IoT platform offers smart analytics that can detect anomalies and trigger immediate actions. It offers streaming analytics capabilities, complex event processing, and machine learning to help you understand events, map their impacts, identify patterns, and react within milliseconds in real-time.

Real-time Analytics

WSO2 IoT Server provides the capability to process more than million events per seconds. This will help analyze device data in real time and take decisions on demand. Predictive analytics support taking the correct business decision about future events. Real-time analytics provide assistance to refresh dashboards instantly. This can be used to detect anomalies and take corrective action instantly.

Batch Analytics

WSO2 IoT Server supports batch analysis of the collected data to show an aggregated and summarized view. The summarized data is also stored in the RDBMS database, hence it can be consumed by other applications to support the company’s ecosystem.

Edge Analytics

You can run the event processing capability on the device itself, communicate with WSO2 IoT Server and manage the edge computing functionality required for your IoT applications. The complex event processing library “Siddhi” can be packed with any device agent to greatly enhance the capabilities of your solution and give you the ability to run your real-time or batch queries on the edge device.

Devices and SDKs

WSO2 IoT Server provides SDK support to build and connect your device with the WSO2 IoT platform. As all of the functionality is exposed through APIs, the SDK support makes it easier to create new agent applications that run on the device. All the basic functionalities to connect the device with the server are supported in the SDK itself.

Message Flow

WSO2 IoT Server message flows can be classified into two parts:

  1. Device to server message flow
  2. Apps to server message flow

Device to Server Message Flow

The device to server message flow is shown in Figure 7. WSO2 IoT Server sends messages to the broker and APNS, FCM, GCM, and WNS work as virtual brokers. MQTT and XMPP are actual brokers that exchange messages between the IoT server and devices. APNS, FCM, GCM, and WNS are used to notify and wake-up the devices due to constraints of message sizes. Actual payloads are not sent to the devices through them. Once the wake-up call is received by the devices, it calls the IoT server to retrieve the actual payload. The API gateway is a part of the WSO2 IoT platform.

Figure 7

Apps to Server Message Flow

External/System applications connect to the IoT server via the API gateway. Note that the API Gateway is a part of the WSO2 IoT platform.

Figure 8


WSO2 IoT offers benefits to both users who need better mobile device management capabilities as well as OEM vendors who develop new devices. As it’s free and open source, the complete set of capabilities can be downloaded instantly and deployed on a server with just a few clicks. Among its key advantages are its fully integrated IoT security, industry standard Swagger annotated REST APIs, and real-time, batch, and edge analytics that differentiate the platform from any other IoT offering. In essence, WSO2 IoT Server is a complete platform that covers everything in the IoT landscape.


About Author

  • Geeth Munasinghe
  • Technical Lead
  • WSO2