WSO2 IoT Architecture


WSO2 IoT is a comprehensive platform to manage your 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 it designed in a way to protect both device and it’s data. It also provides big data capability to gather sensor data, visualize them real time and batch analytics. You can extend its capabilities to securely manage mobile devices.

Following diagram shows an overview of the complete architecture.


WSO2 IoT, first started as a complete platform to manage mobile devices and later evolved into a more complex system by introducing to capabilities to manage mobile devices and any other IoT device. First it was released with the ability to manage Android and iOS. Later Windows mobile device management and Application management was added.


The below diagram shows the in depth architecture of WSO2 IoT. Difference between above diagram and this is that in first diagram both “APPS” layer and “DEVICES” layer are represented by the “INTERACTION LAYER”.

As shown in the diagram, it can be broken into four layers.

  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. But CDM (Connected Device Management) core has evolved into a much capable and mature platform, therefore any device type can be added without a hassle.

As shown in the above diagram 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 application, device static, and runtime information, such as device memory and its usages. Creating/removing device groups and assigning devices to groups also come under this component.

Device Type Management

This component has the capability to add/remove new device types. This was added newly to WSO2 IoT Server 3.1.0. You can describe the device features, and generate the device operations and the device details.

Policy Management and Compliance Monitoring

Policies make sure that the devices that belong to a user comply with the corporate rules and regulations. A policy will maximise the 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 this corrective actions, such as re-enforcing the same policy, will be taken. The policy may include restrictions such as camera disable, configurations, such as VPN or Wi-Fi.

Operation Management

WSO2 IoT Server controls the 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 it’s stored in the database.

Application Management

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

Configuration Management

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

Certificate Management

This component 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 the 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 the WSO2 IoT and facilitates the management and control of user accounts and roles at different levels.

The user store of WSO2 IoT 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 which is 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 WSO2IoT console.

Push Notification Management

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

Push notifications come into play when messages (operations) needs to be sent 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

Currently 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 reverse HTTP call. 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 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 comes in handy. It is not a must to add a plugin when the user needs to add a custom device type if the device is simple. Most of the 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 then writing a JAVA plugin is the most suitable approach.

There are 3 ways new device types can be introduced the WSO2 IoT Server.

  1. Using the Device Type Service and APIs
  2. Device type descriptor
  3. Writing a java extension with given interfaces.

API Layer

Core level device management functions and 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 than 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 WOS2 IoT Server operation core is implemented in a way that it does not need to know what type of message is being sent to device, the format of the message and the delivery mechanism. This explained the device type related APIs that can translate and interpret the operation in a way that devices can understand. Currently WSO2 IoT Server provides simple device message protocols, such as JSON,XML, DM SyncML (also known as Open Mobile Alliance Device Management (OMA DM) XML) and profile protocol for iOS device management.

The above diagram shows the most common REST APIs in WSO2 IoT Server and they provide the services listed below. These APIs provide much more capabilities, but I only listed out the most commonly used capabilities

  1. Device management API
  2. App Publisher API
  3. App Store API
  4. Android API
  5. iOS API
  6. Windows API

Security and Integration Layer

Security and integration play very critical role in any IoT server. 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, and devices store very confidential information about the business and nature of the enterprise. Hence protecting and securing IoT server access controls and associated devices are a main part of the business.

Furthermore, integrating IoT server with other applications, user interfaces and exposing its capability to the outside world securely is a must. Therefore, integration also plays a critical role in wso2 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 happens when initiating an operation. Firstly it check if the user is authorized to access the provided APIs. Secondly it check if the user is authorized to access or perform an operation on 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 operation on the device.

Integration happens via two components. First one is the API gateway and second one is the message broker. API Gateway handle HTTP requests and responses the same way the message broker handles MQTT messages between the devices and server. As the IoT Server supports plugings, you can plug an XMPP server or a COAP server to communicate with the devices via new access controls if needed.

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

Interaction Layer

This layer can be broken into two segments depending on their interaction with the server. As depicted in the image shown below, both of these segments are represented in the same layer. But 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.

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 of the 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 straightforward. Securely exposed APIs can be accessed from any device, hence the system applications can be extended. Not only are the APIs secured, it also provides different authentication mechanism such as SSO, SAML, XACML when connected with the WSO2 Identity Server.

At the moment 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 ( this is an optional)


Analytics is a crucial part of device management. WSO2 IoT platform has gone over and beyond to provide both realtime and batch analytics. Machine learning is also one of prominent capabilities in WSO2 IoT Server. WSO2 IoT platform offers smart analytics which 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.

Realtime Analytics

WSO2 IoT server provides capability to process more than million events per seconds. This will help analyse the device data in real time and take decision on demand. Predictive analytics supports taking 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 the other applications to support the company eco system.

Edge Analytics

You can run the event processing capability on the device itself using WSO2 IoT Server. The the complex event processing library, “Siddhi”, can packed with any device agent.

Devices and SDKs

WSO2 IoT Server provides SDK support to build and connect your device with the WSO2 IoT platform. As all of functionalities are 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 separated 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 the below diagram.

WSO2 IoT Server sends messages to the broker. APNS, FCM, GCM, and WNS work as a virtual brokers. MQTT and XMPP are actual brokers that exchanges 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 devices through them. Once the wake-up call is received by the devices, it calls the IoT server to retrieve the actual payload.

Please note that API Gateway is part of the WSO2 IoT Platform.

Apps to server message flow

External/System applications connect to IoT server through the API gateway. Please note that API Gateway is part of the WSO2 IoT Platform.