MobiusFlow® connects, controls and communicates with 1000s of sensors and control devices to provide actionable insights and automated responses. Developed and successfully deployed with many projects over the past 17 years by engineers with first-hand experience in project management and installation such as CBRE, Ingram Micro, TD Synnex and IBM.

Whether you are looking for a full walkthrough or just dipping in to get more information about a single topic, our documentation site is the perfect companion to the training courses on our main site.

3️⃣ MobiusFlow Version 3

We have rebuilt MobiusFlow from the ground up. MobiusFlow V3 has a bunch of new features and enhancements improving both performance and adding improvements to data handling, searching and customisation.

This section is dedicated to guides and technical knowhow related to version 3.

📖 User Guides

The user guides are instructional walkthroughs. Follow these guides from start to finish or jump to a section to learn how to perform specific tasks.

⚙️ Technical Docs

Looking for more detailed technical information? These articles dive deeper into the more technical aspects of MobiusFlow®, from Architecture to API details, ports, protocols, configuring services creating flows, and more.

MobiusFlow® is a middleware software application

MobiusFlow® connects, controls and communicates with 1000s of sensors and control devices to provide actionable insights and automated responses. Developed and successfully deployed with many projects over the past 17 years by engineers with first-hand experience in project management and installation such as CBRE, Ingram Micro, TD Synnex and IBM.

Preprocessors are run every time a new value is written to a resource. They are used to modify the value before it is written e.g. change from °C to °F, or update another resource e.g. update a message counter

If you forget your connector's Config Mode Password or want to fully reset all settings to the factory default follow the procedure below

What You Will Need?

1. A SIM card removal tool, large paper clip or pin to push the configuration mode button

Factory Reset

Using a pin hold in the configuration mode button (inside the small hole to the right of the USB connector) on the front panel for 10 seconds

While you are holding the button in the green LED will start to flash rapidly and after 10 seconds the connector will reboot. Once you see the power on LED sequence release the configuration mode button

MobiusFlow V3 has been built from the ground up. We have listened to your feedback and added a host of new features to make MobiusFlow even more powerful and easier to use.

Tagging, we added it, custom object profiles, there too, and to make you even more productive we have added the ability for you to write your own data pre-processors and codecs. We are excite about these new features and are sure you will be too!

Engine and Toolbox

Both the MobiusFlow Engine (the heart of MobiusFlow) and MobiusFlow Toolbox have been completely rewritten to be more efficient and easier to use.

Custom Object Profiles

Object profiles define the shape and properties of MobiusFlow objects. Before version 3 object profiles were built into each release and could not be easily created or modified by users.

Version 3 has redefined how object profiles work. Object profiles can now be freely created by users in a simple editor. In fact each new instance of MobiusFlow has no object profiles defined. Instead we have taken all of the object profiles from version 2 (and a bunch of new ones) and created object profile templates.

Object profiles can be created from scratch, from templates, or from any profile that you have already created and then customised to your application. This gives users full flexibility without adding complexity as new objects can also be added directly from templates and MobiusFlow will automatically create the profile for you.

Exporting and Importing Profiles

Object profiles (along with their preprocessors, codecs and UI layouts) can be exported and imported allowing you to create your own library of profiles to be used on other projects.

Preprocessors, Codecs and UI Layouts

Preprocessors

Have you ever needed to modify data before it is written to a resource? Have you wanted to change from °C to °F on the fly as new data arrives? Was totalising energy readings from meters difficult?

Not any more as preprocessor functions will do that for you!

Each object profile can have a preprocessor function written in Typescript or Javascript which allow you to do just that, you can even write it directly in a built in IDE in MobiusFlow Toolbox.

Codecs

Codecs make adding new decoders for raw sensor data a breeze. Instead of waiting for us to add new decoders for sensors like EnOcean, LoRaWAN, or Ingy, you can create an object profile and define the codec to decode the raw sensor telegram. As with preprocessors, these codecs can be written in Typescript or Javascript using the built in IDE.

UI Layouts

Capturing default values such as sensor IDs when configuring objects is simplified by adding your own configuration UI in a simple JSON format.

Value Persistence

The data stored in MobiusFlow objects can now be persisted between restarts of a service. No longer will temperate values drop to zero, people counts be lost, and energy readings disappear when services are restarted! Persistence can be configured on a service by service basis and values are included in backups

Tags

Powerful tagging features have been added to both objects and resources. Tags can be defined on object profiles so that they are automatically added to each instance of an object, and added to individual object instances.

You can use simple tags or add values to tags. Tags are included as metadata when reading values or receiving change-of-value events via the new API.

The MobiusFlow software has been developed as an MQTT object bus which normalises all device data into standardised MobiusFlow objects which allow interoperability between all devices either real or virtual in the field or Cloud.

MobiusFlow enables actuators, sensors & controllers to connect, control and communicate with each other and to the Cloud so that IoT solutions using scalable monitoring, visualisation and predictive analytics can provide valuable insights into your business and act upon them automatically.

• A complete control and communications platform

• Microservice based architecture

• Secure, open protocol based on MQTT

• Scalable to 1000s of devices

• Platform and language independent

• Does not depend on a network connection for local control

• Provides full discovery of nodes, objects and resources in all directions

• Pub / Sub change of value notifications

• All sensor and actuator data is normalised from any source such as OPC UA/ BACnet/ DALI/ EnOcean/ LoRaWAN / Analog / Digital etc.

MobiusFlow has been designed from the ground up as a micro service based design with a simple but common set of API commands. All communication between micro services is performed using the MQTT protocol, ensuring that micro services can be written in any programming language and will run on any device capable of TCP/IP network communications. The only requirement for any MobiusFlow system is that it contains at least one Node. This Node consists of a MobiusFlow Hub which initiates and facilitates communication between micro services in a secure way. Micro services can run on the same device as the Hub, or on another device such as a temperature sensor, connected to the Hub via a connection capable of transmitting via TCP/IP (provision has been made for future expansion, by adding translation services, to allow micro services to communicate with the Hub over any transmission medium capable to transmitting binary data).

Each Node is typically a stand-alone island which does not require any connection to any other device in order to perform local control. Nodes can be connected together via secure MobiusFlow Routers allowing the creation of a network of interconnected Nodes. When used in this configuration, Nodes can share data with each other and influence the control algorithms running on any connected Node.

Vanilla MQTT has some limitations in its usefulness as a peer to peer messaging and control protocol. It is based around the Publish / Subscribe pattern which is ideal where multiple devices are sending data to a single end point for logging etc. MQTT can be used where devices or services need to have a two way peer to peer flow of communication but the different services need to be aware of each other at design time. MobiusFlow defines a protocol layer above MQTT which enables discovery of devices and services at runtime and then allows two way peer to peer communication to take place, ensuring that new devices and services can be added at any time without having any design time knowledge of the other devices and services in a system.

MobiusFlow Toolbox is a browser-based engineering tool enabling users to easily configure and monitor an instance of MobiusFlow

Overview

As each application differs you will need to chose which services are required for your application.

To add a service, first click on Services in the main menu and then click on the Show Library button to show the list of available services, find the service you want to add, and click on the Add button for that service.

The service will get added to the configuration with the next available Service ID (SID)

You can click on the Hide Library button to hide the service library when you are done.

💥 Interactive Demo

Overview

To delete a service, first click on Services in the main menu and then find the correct service card.

In the service card toolbar click on the Delete button. A confirmation dialog will appear. Enter the text shown (you can click on the copy icon to save typing) and click Confirm.

💥 Interactive Demo

Overview

To create a copy of a service along with all of its settings and objects you can click on the Clone button on the service card of the service you want to copy. The new service will be given the next available . You can change the SID in the service's settings if required.

💥 Interactive Demo

System Services are required my MobiusFlow to function correctly. Examples include the Engine API and Historian services.

MobiusFlow Engine API

The MobiusFlow Engine API service is a RESTful API used by MobiusFlow Toolbox, Flows, and user applications to both configure an instance of MobiusFlow and read and write data to MobiusFlow objects.

It is not possible to configure or stop this service from MobiusFlow Toolbox as this would prevent Toolbox from communicating with the MobiusFlow Engine.

More details about this API can be found .

MobiusFlow Historian

MobiusFlow Historian is a time-series database for storing data generated and collected by MobiusFlow. This time-series data can then be used my MobiusFlow View to create dashboards or by external applications for data analytics and artificial intelligence.

The MobiusFlow Historian service pushes data whenever it changes to a MobiusFlow Historian database. More information can be found .

Object Profiles Page

To open the Object Profiles page click on Object Profiles in the main menu.

The object profiles table shows a list of all of the profiles that exist on this instance of MobiusFlow. Any profiles that have not been used to create objects, and therefore can be deleted are shown with a greyed out PID and icon.

Above the table is a toolbar with options to

• Create a new profile

• Filter the list by profile group

• Search for a profile - this filters by PID and profile name

• Import and export profiles

• Set the density of the grid

Clicking on a profile in the table opens the Profile Settings Sidebar. The width of the sidebar can be changed by dragging on the vertical splitter.

The full MobiusFlow Manager training course can be .

Configuring MobiusFlow for use with Connectors uses the MobiusFlow Connectors service. A full guide on how to use this service can be found .

The configuration page is used to create and configure the MobiusFlow configuration for a Mobius node (see MobiusFlow Architecture). The page is split into five main sections:

1. The main menu

2. The services palette

3. The objects palette

4. The configuration tree

5. The service and object configuration section

The main menu

The main menu is displayed on all pages. It allows switching between Configuration, Diagnostics, Node-RED Flows and Administration. The Administration option is only shown for users who have admin privileges.

The services palette

The services palette shows the list of Mobius services that can be added to the configuration. To add a service to your configuration drag it from the services palette and drop it on to the configuration tree.

The objects palette

The objects palette shows the list of Mobius objects that can be added to the configuration. To add an object to your configuration drag it from the objects palette and drop it on to a service in the configuration tree.

The configuration tree

The configuration tree shows the services and objects currently added to the configuration. Clicking on the triangles on the left of the tree either expands or contracts a branch of the tree. The currently selected item is shown as highlighted in orange.

To delete a service or object, hover over the item and click on the dustbin icon which appears to the right of the item.

Deleting a service deletes all associated objects

The service and object configuration section

This section is dynamic and updates depending on which item has been selected in the configuration tree. If a service has been selected the service's configuration properties are displayed. Similarly, selecting an object or object resource shows the relevant configuration options.

Always click the Save Changes button to persist changes to a service, object or resource configuration. Any changes to a service, object or resource only become active after the service has been restarted on the diagnostics page.

Page coming soon. Please contact [email protected] to arrange a support call on this topic.

What You Will Need?

1. A device with a web browser such as a laptop, tablet or smart phone, capable of connecting to a 2.4GHz WiFi access point

2. A SIM card removal tool, large paper clip or pin to push the configuration mode button

3. A powered MobiusFlow® connector

4. The connector's Serial Number

Enabling Configuration Mode

The connector's configuration mode can be enabled in two ways:

Using the Configuration button

Using a pin hold in the configuration mode button (inside the small hole to the right of the USB connector) on the front panel for 2 seconds

Release the button and the green LED will flash rapidly

Using your laptop / tablet / smartphone look for a WiFi network with the same name as the connectors serial number

Connect to this network and enter the connector's Config Mode Password. The default is mobiusflow

Open a web browser on your laptop / tablet / smartphone and enter http://192.168.4.1 into the browsers address bar and hit enter

The web browser will show the connector's configuration Home page

Using a Web Browser

Make sure that the connector and your laptop / tablet / smart phone are connected to the same Ethernet network

Open a web browser and browse to <your connector IP address>:8080 e.g. 192.168.1.20:8080

You will need to enter a user name and password. The user name is admin and the password is the same as the connector's Config Mode Password. The default is mobiusflow

After a short delay the web browser will redirect to the connector's configuration Home page

To update a service's settings, first click on Services in the main menu and then find the correct service card.

On the service card toolbar click on the Settings button to open the service settings dialog.

The service settings dialog is shown above. All services have these default settings, but some services may have additional service specific settings. It is beyond the scope of this article to describe any service specific settings, please see the article for that specific service type for more information.

General Settings

SID

The SID or Service ID is a three digit hexadecimal number. It forms part of a MobiusFlow Uniform Resource Identifier.

When a service is added it is given the next available SID, but this can be changed if required. SIDs must be unique within a MobiusFlow instance so you cannot assign a service an existing SID.

Name

The service name can be freely assigned. It has no relevance within a MobiusFlow instance and is just used in MobiusFlow Toolbox to make it easier for you to distinguish between your services.

Enable Service

Services can be Enabled or Disabled. Disabled services do not run at startup and cannot be manually started.

Run at Start

If a service is enabled and it is set to Run at Start the service will be automatically started when the MobiusFlow instance starts. If Run at Start is switched off for a service it will not start automatically but can be started manually by clicking on the service's start button.

Value Persistence

Value persistence ensures that objects keep their values between restarts. Please see the Value Persistence article for more information.

Logging Levels

A service and its underlying connection to the rest of the instance (the spoke) each have their own logging levels. Currently these logs are only visible in the terminal on the computer running the MobiusFlow instance and are not visible in Toolbox. We aim to make this available in a future version for developers.

The default logging levels are set to Info. Please do NOT change these unless instructed by a MobiusFlow engineer during a support incident as excessive logging could cause significant additional CPU load.

Service Specific Settings

Some services have their own service specific settings. The exact settings will depend on the service type. These are shown at the bottom of the service settings dialog. An example for the MQTT Broker service is shown below.

💥 Interactive Demo

Overview

All MobiusFlow Objects must belong to a service. To add, delete, modify, and view a service's objects you can either click on the main body of a service card on the Service's page or click on the service in the main menu.

For more information on managing objects please refer to the Objects page.

💥 Interactive Demo

MobiusFlow Objects represent real or virtual devices such as sensors, rooms, pieces of equipment, and machinery. All objects are based on an Object Profile which describes the shape of the object i.e. what properties (resources) an objects has, the data type of each property (resource), and metadata describing the object and it properties.

For more information on objects and resources read the MobiusFlow Architecture article.

Objects must belong to a service. To add new objects or configure existing objects on a service open the Service's Objects page by clicking on the service in the main menu or clicking on the main body of a service's card on the Services page.

For most use cases, Deploying MobiusFlow in the MobiusFlow Cloud is simplest and most cost effective hosting option.

Customers can create new MobiusFlow instances themselves using the MobiusFlow manager platform. A full guide on how to use this platform can be found here.

When creating a new MobiusFlow instance using manager ensure the Host instance on MobiusFlow Cloud option is checked:

On creation, there are several options that must be populated:

Hostname

This is the URL the new MobiusFlow cloud instance will be hosted on. In the above example, Manager has automatically suggested average-pug-2488. As such, new Cloud instance will be accessible at the URL average-pug-2488.mobiusflow.io.

Build Type

This selects the version of MobiusFlow to use. If use for the MobiusFlow LoRaWAN LNS is required, ensure the MobiusFlow V2 with LoRaWAN Stack option is selected.

Region

This specifies the region of the world the new Cloud instance is to be hosted on. It is recommended to host the instance as near to where it will be used as possible.\

Once a MobiusFlow Cloud hosted instance as online, an Environment is created, in-turn controlling how the instance can communicate with the outside world. A full article on this environment can be found here.

balenaCloud devices can run multiple microservices in separate Docker containers. Deploying MobiusFlow® to your device will create three microservices. You can start, stop and view logs for each service on the balenaCloud device summary page.

mobius

This microservice runs the MobiusFlow® application.

manage

Manages network interfaces. See Configure Networks for more information

mongodb

A full version of MongoDB which you can use to store / retrieve data in flows.

The default settings are

The Home page has the following buttons

Configure Network

Configure the wired or wireless Ethernet network settings

Manage Certificates

Manage all certificates for TLS connections. The default certificates are for MobiusFlow® cloud hosted instances but you can add your own if required

Configure MQTT

Configure the connection to the MQTT broker you chose when configuring MobiusFlow® for connectors

Set Config Mode Password

Change the configuration mode password

About

See information about the connector such as the software version, serial number, andwhich modules are installed

You can also update the firmware on this page

Reboot Device

Reboot the device to exit configuration mode and use the new settings

Setting CA / Server Certificates

When using TLS you will need to set the correct CA / Server certificates. You can have up to three certificates set. If the connector fails to connect using one of the certificates it will cycle through all three, trying each one until it connects

The default certificates are ISRG Root X1 certificates which are used when connecting to MobiusFlow® hosted instances of MobiusFlow®

You can set the certificate by pasting the certificate text into the selected certificate slot

Setting Client Certificate and Keys

If your setup requires the use of Client certificates you can set up to four different certificates and keys. Paset these into the selected certificate and key slots

MobiusFlow® connectors send and receive data via MQTT. You need to configure the MQTT settings to match the configuration you set in the Configuring MobiusFlow® section of this guide.

MQTT Broker Settings

You can choose any MQTT client ID but this must be unique for your MQTT broker. The default is the connector's serial number

Enter the IP Address or URL of the MQTT broker. You do not need to specify MQTT:// or MQTTS:// before the URL

Enter the MQTT Port number. This is normally 1883 or 8883 for TLS enabled connections

If required enter the MQTT broker authorisation Username and Password. These can be left blank if no authentication is required

Enter the same pre-shared key (PSK) as you entered in the Configuring MobiusFlow® section of this guide

Security

If you are using TLS make sure you check the TLS using CA Certificate option. You must also set the correct CA Server Certificate on the Manage Certificates page

You may also choose to use a Client Certificate and Key. Check this option if required and ensure that you have setup your client certificate and key on the Manage Certificates page

Save Settings

Once you have configured all MQTT settings click the Save button

Click the Home button on the settings saved confirmation page to return to the Home page

The Config Mode Password is used to login to the configuration pages of the connector. The default password is mobiusflow

You can change the password on this page

Save Settings

Click the Save button

Click the Home button on the settings saved confirmation page to return to the Home page

The about page shows you information about the connector. You can also update the connector's firmware by clicking on the Update Firmware button

Updating Firmware

Click on the Update Firmware button on the About page

Click on Choose File and select the firmware file you want to upload

Click on the Update button

After a few minutes the connector will reboot and start running the new firmware

The node calls are for reading a MobiusFlow hub as well as resetting the pre-shared keys on a given hub

Backup

The discover calls are used to learn about the present state of a given MobiusFlow instance

Used get and set the full configuration the flows.

Navigation

Navigating around the Toolbox UI is very simple. The key areas are as follows:

• The current user is shown in the top right of the window. You can click on this button to change your password or log out

• The collapsable menu on the left side of the window is a quick way to access your configured Services, Flows, Historian settings, Object Profiles and instance Settings. Clicking on the menu icon in the the top left corner will either collapse or expand the menu. As you add new to your configuration they will shown in the menu under the Services heading

• With the exception of Flows, clicking on an item in the left menu will show the view for that selection in the main view. Clicking on Flows will open the Flows window in a separate browser tab, or navigate to that tab if it is already open

• Configuration of specific items such as services, objects and profiles will be shown in a pane to the right of the main view. This pane is only visible when a configurable item is selected

Supported Browsers

MobiusFlow Toolbox supports the latest versions of most modern web browsers. We recommend the following:

• Google Chrome

• Firefox

• Safari

• Edge

Logging In

Open your web browser and navigate to your MobiusFlow Toolbox instance. This is typically a fully qualified domain name followed by /toolbox

The first time you login you must use the initial administrator credentials supplied to you. You can change the default admin password and create new users once you are logged in.

Services can be started and stopped individually and if enabled, and set to run at start, will start automatically whenever the MobiusFlow instance is started.

Some services have which affect how they operate e.g. the ports used by the MQTT broker service. These settings are typically only loaded on service start so changes to these settings may require a service to be stopped and started before they take effect. If a service is running and any critical settings are changed MobiusFlow Toolbox will notify you that a restart is required.

In addition to service settings changes requiring a restart, changes to object settings will only take affect if a service is restarted or if a hot reload takes place. Any objects that have changes requiring a restart or hot reload are highlighted in the service's page.

Start, Stop, and Hot Reload Controls

The controls used to start, stop, and hot reload services are located on the service's card on the Services page and on the service's objects page. The buttons have the following icons (Start, Stop, Hot Reload).

Starting a Service

Services are started by clicking on the Start button.

When a service starts it first creates all of its objects, loads in any (if enabled) and then runs any logic such as raw sensor data decoding. You can only access objects on running services.

Stopping a Service

Services are stopped by clicking on the Stop button.

If a service has persistence enabled the current resource values will be persisted before the service stops.

When a service is stopped all of its objects will be destroyed and will no longer be available for reading or writing.

Hot Reloading a Service

Adding objects or configuration changes to objects on running services will only take affect if a service is restarted or if the service is hot reloaded.

Hot reloading a service does not stop it. Instead all objects that have configuration changes are refreshed and new objects are created without affecting any other objects.

Click on the Hot Reload button to hot reload its objects.

💥 Interactive Demo

Value persistence ensures that objects keep their values between restarts.

In MobiusFlow versions before v3 any restart would cause all resources to be reset to their default values. This would often cause anomalies or loss of data such as all temperature values dropping to zero, meter readings being lost or people counts resetting.

MobiusFlow 3 has solved this problem by adding optional value persistence. This can be configured on a service by service basis in the service settings. To access a service's settings follow the instructions .

When a service starts it first creates all objects with their default values and then applies any persisted values before running.

Enabling / Disabling Persistence

You can enable or disable persistence on each service. Changing the persistence enabled state will affect all objects belonging to that service.

You can enable or disable persistence by clicking on the Enable Persistence switch in the service's settings.

Disabling persistence will also delete any persisted values. If you need to reset the persisted values you can disable and then re-enable persistence.

Setting the Persistence Interval

In order to lower CPU load values are only persisted at regular intervals and not on every value change. You can set this interval (in minutes) in the service's settings. Try to find a reasonable balance between saving the current values and load on the system. The more objects a service has, the greater the CPU load required to persist the values.

Default Settings

Services have persistence enabled with an interval of 5 minutes by default.

💥 Interactive Demo

To create a new profile open the Object Profiles page, make sure that the sidebar is closed, and click on the Create button. This will open the Create Object Profile wizard.

The wizard will have three starting point options. Selecting one of the options will change the steps required to complete the wizard.

Start From a Blank Profile

If you choose to start with a blank profile and click Next, you will jump to the last step which is Finalise Settings

Start From Profile Template or Existing Profile

Choosing to start from a template or existing profile and clicking Next will require you to select either a template or existing profile. These are shown in a table, which can be filtered. Select one of the rows before clicking on Next to view the last Finalise Settings step.

Finalising Settings

Depending on your starting point, the Finalise Settings form will be blank or have some fields pre-populated by the template or existing profile.

Fill in all required fields and optionally add a description and before clicking on Create Profile.

PID

A unique profile ID as a four digit hexadecimal number from 0200 to FFFF.

Group

The group is used by MobiusFlow toolbox to aid in filtering the object profiles. You can select from an existing group or type in a new group name.

Profile Name and User Interface Name

The profile name is used to help identify this profile. It normally starts with a lower case letter and does not contain spaces, but can containg underscores and dashes.

The user interface name is a human readable name normally used by MobiusFlow View to make selecting profiles easier for non-technical users.

💥 Interactive Demo

Open the Object Profiles page and click on the profile you want to modify. The Object Profiles sidebar will open on the left of the window.

At the top of the sidebar is the object profiles settings toolbar. You can use this toolbar to switch between the four sidebar modes and to delete the profile if it is not being used. Use the X to the right of the toolbar to close the sidebar.

Below the toolbar are the Undo and Save buttons. Clicking on the Undo button will revert any changes and clicking on Save will save the changes.

Sidebar Modes

The four sidebar modes are shown in the table below. Click on the links for more information.

Deleting Profiles

Click on the profile you wish to delete. When the sidebar is open click on the Delete button, enter the confirmation text and click Confirm.

💥 Interactive Demo

Tags are a powerful way to organise your objects and resources making it easier to find and group similar pieces of data.

Tags can be a simple key word or phrase (much like a hashtag in social media apps) or a keyword or phrase with an associated value.

Tags can be added to and individual instances. Any tags added to an object profile will be automatically added to all objects created from that profile.

The process of managing tags on object profiles, objects, and their resources is the same. To view the tag editor select an object profile, object, or resource and the relevant sidebar will open showing the tag editor. Once the sidebar is open follow the steps below.

Adding tags

Adding a simple tag

In the Add a tag textbox type in the tag name and press Enter

The new tag will appear in the tag list

Adding a tag with value

In the Add a tag textbox type in the tag name followed by = and then the value e.g floor = 1

Press Enter and the tag will appear in the tag list

Tags with values will show the first five characters of the value but you can hover over the tag to see the full value

Modifying a tag value

To modify the value of a tag or add a value to a simple tag just re-enter the tag name and value

To convert a value tag into a simple tag re-enter the tag name with no value

Deleting a tag

To delete a tag click on the X to the right of the tag in the tags list

💥 Interactive Demo

All access to MobiusFlow Toolbox and the MobiusFlow Engine API requires a valid username and password. Adding, deleting, and modifying users is done on the User Management tab on the Settings page.

The User Management page shows a list of all users with their roles, whether they are active or not, and an Actions button for additional user management.

User Roles

There are three user roles, Viewer, Editor, and Administrator.

Viewers

• View services, objects and live data

• View flows

Editors

• Add, edit, and delete services, objects and live data

• Start and stop services

• Add, edit and delete flows

• Add edit and delete object profiles

• Import and export configuration

Administrators

• Add, edit, and delete services, objects and live data

• Start and stop services

• Add, edit and delete flows

• Add edit and delete object profiles

• Import and export configuration

• View and manage users

• Modify system settings

Adding Users

Click on the Add User button to view the Add User dialog

Enter a Username, select a role, and enter the user's initial password. Users can change their own password later

The new user will appear in the users list

Managing Users

Click on the Action button (three vertical dots) next to a user to open the user management menu

Change Password

Change the password of an existing user. This is useful if a user forgets their password or you want to change the password of a

Change Role

Change the role of an existing user

Active / Deactive User

Users are active by default but can be activated or deactivated. Deactivated users will no longer be able to log in.

Delete User

Permanently delete an existing user. You will need to confirm your action before the user is deleted.

Service Accounts

Access to the requires a valid user with the correct role.

We recommend creating service account users with the Editor or Viewer role for API access. You should consider a separate account for each service that requires access as revoking access to a specific service can be as simple as deactivating that service account.

The Administration page covers user management, backup and restore, licence settings, security as well as setting the node's Hub ID. The page is divided into corresponding tabs accordingly.

User administration

Users can be added, modified and deleted from within the User Management Tab on the Administration page.

Backup/Restore

Backup and restore functionality is accessed via the settings tab on the Administration page. A full article covering backup and restore can be found .

Setting the Hub ID

All Mobius nodes are identified by their hub ID. This is a six character hexadecimal number and should be unique within any group of Mobius nodes. See and for more information about Hub IDs.

Select Network Type

You can choose to use a wired or wireless (2.4GHz WiFi) connection to connect a connector to your MobiusFlow® instance

Select your network type using the Connect Via dropdown. The page layout will change depending on the option selected

When using a wireless connection you need to enter the WiFi network's SSID (name) and password. You can click on the Scan WiFi Networks button to get a list of available WiFi networks

You can set a connection timeout in minutes. If the connector fails to connect to a network within this time it will reboot and try again

Select TCP/IP Mode

You can choose to use a DHCP server to allocate the connector an IP Address or set a static IP Address. If you choose to use a static IP Address a few more options will be shown. Set these according to your network

Save Settings

Once you have configured all network settings click the Save button

Click the Home button on the settings saved confirmation page to return to the Home page

The authorization controller is used to login to the API, in addition user management.

When a login call is completed, the API will return a bearer token which should be used in the auth header of all future calls. This token is set to expire 10 minutes after its generation.

A refresh token is also included in the login response, and this is used in the body of the refresh call to get new tokens with refreshed expiry times. Ensure a refresh call is made prior to any given bearer token's expiry to avoid having to login again.

The object calls are used to read, add, remove and manipulate MobiusFlow objects and resources.

The MobiusFlow Engine API is used interface with MobiusFlow via http and https. The API allows clients to perform all functions within MobiusFlow, from managing user accounts, to getting and setting data, as well as manipulating the MobiusFlow configuration by adding, removing and editing MobiusFlow objects, services and flows.

Additionally, the API allows clients to subscribe to specific real-time events within happening within a given MobiusFlow instance (see subscription controller). In this use case, the API will upgrade the client to use the Websocket protocol (ws / wss).

Controllers

All API endpoints are described in the following subsections. The subsections are divided into the functional groups (controllers); Authorization, Discover, Node, Service, Object, Profiles, Command, Flows and Subscription.

Protocols, Endpoints and Ports

If connecting to a local instance of MobiusFlow, the http protocol can be used. If connecting to an instance of MobiusFlow via the internet, https should be used. The API is always exposed on port 8443.

All endpoints lead with:

{{protocol}}://{{hostname}}:8443/api/v1

Where the protocol and hostname parameters are replaced with the true protocol and hostname. For example, in the case of connecting to a local instance of MobiusFlow, the leading path would look like:

http://localhost:8443/api/v1

Further Documentation & Postman Collection

Swagger documentation describing the API in full, can be found here. This documentation includes example bodies and responses for every endpoint. Finally, a postman collection containing parameterised examples of all client calls can be downloaded below.

Object Profiles describe the shape of Objects i.e. what properties (resources) an objects has, the data type of each property (resource), and metadata describing the object and it properties.

For more information on objects and resources read the MobiusFlow Architecture article.

Before creating objects you must first define an object profile. Profiles can be created from scratch, or based on a predefined template or existing object profile.

Profile IDs (PIDs)

All object profiles must have a unique profile ID or PID. This is a four digit hexadecimal number and can be any value from 0200 to FFFF as long as a profile with that PID does not already exist. The PID will form part of an object's URI identifying the object's type, and can be used when subscribing to object or resource COVs to filter by object type.

See MobiusFlow Uniform Resource Identifiers for more information.

Resources

All live data in MobiusFlow is stored in object resources. Each resource stores a single simple value of a specific type. These types include

When writing a value to a resource it should always be of the correct type although values will be coerced to the correct type if possible.

In addition to setting the data type for a resource you can also define some settings for each resource. These settings will depend on the type e.g. a string resource will have a setting for the maximum length and a number resource will have settings for the maximum and minimum value that can be stored.

Codecs, Preprocessors, and UI Layouts

For each object profile you can also define a Codec, Preprocessor, and UI Layout.

What is balenaCloud?

BalenaCloud is a small device fleet management platform which simplifies the process of managing and maintaining 1000s of edge devices. It allows secure remote access and monitoring of each device and installing and updating product firmware of an entire fleet with a few simple clicks. See balenaCloud for more information.

What Device Types are Supported?

MobiusFlow

We currently have software images for thee different device types for balenaCloud. These are:

MobiusFlow RPI Connector

The MobiusFlow RPI Connector works with the following Raspberry Pi types:

• Raspberry Pi 4

• Raspberry Pi 5

If you are ready to get started, jump into the Creating a Fleet section to begin creating your first fully managed MobiusFlow® device on balenaCloud.

After signing up to balenaCloud follow their instructions to create a fleet and add your first device. We have simplified the process so you will only need to perform some of the actions they list. The steps below outline the process but for more information see the balena.io documentation.

What You Will Need?

1. A balenaCloud account with Microservices access (this requires a paid account)

Creating a New Fleet

Navigate to your balenaCloud dashboard and login in

Navigate to the Fleets page

Click on the Create Fleet button

Enter a fleet name

Choose device type Raspberry Pi 4 (using 64bit OS)

Select fleet type Microservices

Click on the Create new fleet button

You have created your first balenaCloud fleet! Now go to Adding Your First Device to add a device to this fleet

Part Numbers

It is possible to have up to two radios for wireless sensors in a single connector. This is useful when you have combination of sensors using different protocols.

The current options are EnOcean and Workplace Occupancy using either 868MHz for the EMEA region of 915MHz for the USA and Canada.

Download Connector Firmware

v3.1.1

v3.2.0

The MobiusFlow software has been developed as an MQTT object bus which normalises all device data into standardised MobiusFlow objects which allow interoperability between all devices either real or virtual in the field or Cloud.

MobiusFlow enables actuators, sensors & controllers to connect, control and communicate with each other and to the Cloud so that IoT solutions using scalable monitoring, visualisation and predictive analytics can provide valuable insights into your business and act upon them automatically.

• A complete control and communications platform

• Microservice based architecture

• Secure, open protocol based on MQTT

• Scalable to 1000s of devices

• Platform and language independent

• Does not depend on a network connection for local control

• Provides full discovery of nodes, objects and resources in all directions

• Pub / Sub change of value notifications

• All sensor and actuator data is normalised from any source such as OPC UA/ BACnet/ DALI/ EnOcean/ LoRaWAN / Analog / Digital etc.

MobiusFlow has been designed from the ground up as a micro service based design with a simple but common set of API commands. All communication between micro services is performed using the MQTT protocol, ensuring that micro services can be written in any programming language and will run on any device capable of TCP/IP network communications. The only requirement for any MobiusFlow system is that it contains at least one Node. This Node consists of a MobiusFlow Hub which initiates and facilitates communication between micro services in a secure way. Micro services can run on the same device as the Hub, or on another device such as a temperature sensor, connected to the Hub via a connection capable of transmitting via TCP/IP (provision has been made for future expansion, by adding translation services, to allow micro services to communicate with the Hub over any transmission medium capable to transmitting binary data).

Each Node is typically a stand-alone island which does not require any connection to any other device in order to perform local control. Nodes can be connected together via secure MobiusFlow Routers allowing the creation of a network of interconnected Nodes. When used in this configuration, Nodes can share data with each other and influence the control algorithms running on any connected Node.

Vanilla MQTT has some limitations in its usefulness as a peer to peer messaging and control protocol. It is based around the Publish / Subscribe pattern which is ideal where multiple devices are sending data to a single end point for logging etc. MQTT can be used where devices or services need to have a two way peer to peer flow of communication but the different services need to be aware of each other at design time. MobiusFlow defines a protocol layer above MQTT which enables discovery of devices and services at runtime and then allows two way peer to peer communication to take place, ensuring that new devices and services can be added at any time without having any design time knowledge of the other devices and services in a system.

The service calls are used to read, add, remove and manipulate MobiusFlow services.

You can use the backup and restore feature to backup the full configuration of a MobiusFlow instance, and to restore the configuration of a MobiusFlow instance to a previously saved backup.

Overview

In summary, all configuration data of a MobiusFlow instance can be stored within a single .zip file. This means the current configuration of any MobiusFlow instance can be backed up by simply downloading this backup file and saving it in a safe location of your choice. Similarly, the configuration of any MobiusFlow instance can restored by uploading one of your previously saved backup files.

All backup and restore functionality is accessed through the 'Backup/Restore' menu located on the 'Administration' Tab.

Backup

On the 'Backup/Restore' menu, you can create a backup by clicking 'Backup'.

Once the backup file has been created, click 'Download Zip' to download it.

Alternatively, the you can click 'Request new backup' to return to the previous menu and generate an updated backup file.

Be sure to save your backup file in a safe location! There is nothing worse than not being able to find a much needed backup file.

Restore

The restore feature is particularly useful if you want to copy a MobiusFlow configuration onto to other MobiusFlow instances, however it also useful if you've managed to break everything.

The 'Backup/Restore' menu is also used for restoring. You can restore by first clicking 'Upload Zip' and then browsing to the .zip backup file you previously saved in a safe place.

Once uploaded, the menu will show the backup information as well as allowing you to click 'Restore'.

Accept the a confirmation dialog to proceed.

You will be notified that the restoration process has started and then MobiusFlow will then reboot, completing the restore process.

Congratulations for completing your restore!

MobiusFlow Services are the starting point for any configuration. They are typically device drivers for a specific protocol or provide protocol interfaces such as an MQTT broker.

The main services page shows an overview and status of each service that has been added to the configuration. You can interact with services in a number of ways, including configuring a service, starting and stopping a service, or adding and configuring objects belonging to a service.

The main services page shows an overview of all services that have been added to an instance. Each service is represented by a card which provides status information and allows you to interact with the service.

As new services are added cards will appear on this this page. The service list is also visible in the main menu below the Services menu item.

Service Library

The service library is a list of all possible services that can be added to MobiusFlow. You can show and hide the library by clicking on the button in the top left of the page.

For more information on adding services please read the article.

Service Cards

Service cards show a lot of information about a service and allow you to interact with a service.

Service ID (SID)

The service ID is a three digit hexadecimal number and is shown in the middle of the coloured service status circle in the top left corner of the card.

Service Name

The service name is shown at the top of the main body of the card. The name can be set in the service settings and defaults to the service type.

Service Status

The service status is shown in two places on the card.

Quick Status Indicator

The coloured circle in the top left corner gives a quick indication of the health of a service. The indicator colours are as follows:

Detailed Status Information

In addition to the quick status indicator, detailed status information is shown in the main body of the card beneath the service name. If a service is in error, the error is shown here.

Last Seen

At the bottom left of the main body of the card is a timestamp showing the last time a service interacted with the MobiusFlow instance.

Service Type

The service type is shown in the top right corner of the main body of the card.

In addition the internal Service Profile ID (SPID) which also indicates the service type is shown in the bottom right of the main body of the card

Service Toolbar

With the exception of system services, each service card has a toolbar in the top right. Hovering over the card will highlight the toolbar. The six buttons from left to right are:

Accessing Service Objects

Accessing the belonging to a service can be done in two ways. You can click on the main body of a service card or click on the service in the main menu.

Service diagnostics and control

The service diagnostics and control page shows all of the configured services, their current status and controls to start and stop services.

Run state column

The Run State column (2) shows the current run state of the services in a traffic light. The colours are defined as follows:

• Grey - Not running, never started

• Red - Not running, manually stopped

• Amber - Starting or attempting to start

• Green - Running

Actions column

The Actions column (3) has start / stop buttons for each service. Services can be manually started or stopped by clicking on the action buttons.

These action buttons do not modify the value of the Run on Start checkbox on the page.

Service status column

The service status column (4) shows the current status of all running services. In addition to a text message, the statuses are colour coded as follows:

• Amber - starting or status unknown

• Red - service is running but in fault (see text message for details)

• Green - service is running and not in fault

The values shown in the Service Status column are tied to the service status object associated with the service. These status objects are automatically created and updated by the services as object profile ID 0001 with instance 0001. You can read the status of these objects but should not write to them.

View objects column

The View Objects column (5) are hot-links to the Objects Diagnostics page, but filtered to only show objects belonging the the relevant service.

Object and resource diagnostics

The Objects diagnostics page can be shown by clicking on the Objects button on the left of the screen (section 1 in image below) or by clicking on the View Objects hot-link described above. To view all objects belonging to all services use the Objects button (section 1 in image below).

Clicking on the plus sign (3) next to an object expands it to show all of its resources and their current values (2).

Modifying a resource value

It is possible to manually modify a resource's value by writing to, or clearing a value in its priority array (see ). Click on a resource to display its full priority array. Click on a priority to modify its value or clear it.

Resource value modifications are temporary and could be overwritten by a service or Node-RED flow, and do not persist between service restarts or node reboots.

What You Will Need?

1. A balenaCloud account with Microservices access (this requires a paid account)

2. A balenaCloud Raspberry Pi 4 Fleet (see )

3. A Raspberry Pi 4 with minimum 1Gb RAM and 8Gb storage (eMMC or microSD card. The following instructions are for an SD card)

4. A power supply for your Raspberry Pi 4

5. An Ethernet network cable

6. An internet router with a free Ethernet port (or an Ethernet port on your LAN with internet access)

7. An SD card adaptor for your laptop or PC

8. balenaEtcher installed on your laptop or PC. You can download balenaEtcher

Adding a Device

Navigate to your and login in

Navigate to the Fleets page

Click on the fleet you want to add a device to

Click on the Add device button

Leave all of the default settings. You can add a WiFi network (client or AP) later.

Select the Download balenaOS option in the drop down button. The balenaOS will start to download

Burning the balenaOS onto the SD Card

Place your microSD card into your SD card adaptor and connect it to your laptop or PC

Open balenaEtcher

Select Flash from file and choose the balenaOS image you downloaded above

Select your SD card as the target

Click on the Flash button

balenaEtcher will burn the balenaOS to your SD card and make it a bootable image. Wait for this to complete and for the image to be verified

Remove the SD card from the SD card adaptor and insert it into your Raspberry Pi 4's SD card slot

Plug the Ethernet cable into your Raspberry Pi 4's Ethernet port and your network

Power up your Raspberry Pi 4

Confirming Your Device is Connected to balenaCloud

After a few minutes your new device will appear in the balenaCloud dashboard. Navigate to your balenaCloud dashboard, select your fleet and view the fleet's Summary page.

You device will be added to the list at the bottom of the page. It will be given a random name which you can change on the device's summary page

You have successfully added a new device to your balenaCloud fleet. To deploy MobiusFlow® to this device go to

What You Will Need?

1. A balenaCloud account with Microservices access (this requires a paid account)

2. A compatible balenaCloud fleet (Up Board, Intel NUC or Raspberry Pi 4)

Deploying from balenaHub

Navigate to your and login in

Navigate to to select which version of MobiusFlow® to deploy

Navigate to the Apps page

Search for MobiusFlow

Select the correct device type

Click on the Deploy button

Balena will switch to your balenaCloud dashboard

You can create a new fleet here or deploy to an existing fleet. If creating a new fleet refer to the section for details on what settings are required

If you already have a new fleet or want to upgrade the MobiusFlow® version on existing devices, select Use an existing fleet instead

Select the fleet from the drop down and click on the Deploy to fleet button

After a few seconds you will see the new release being built for your fleet

This will take a minute or two. Once the build is complete you will see the release on the dashboard. All devices, which have not been pinned to a specific release, in your fleet will automatically start to update to the new release.

You can also view the release history in the Releases page of your fleet.

Click on a device Summary to see which release it is running. You can also pin device to specific releases on this screen

All MobiusFlow® instances require a valid licence to run. Licences define the maximum number of MobiusFlow® objects that you can add to an instance. For more information about MobiusFlow® licences refer to the page.

What You Will Need?

1. A valid MobiusFlow® licence (licences can only be used on one device)

Adding Your Licence to a BalenaCloud Device

Licences are added to balenaCloud devices by setting a device variable. All required device variables are created automatically when you deploy MobiusFlow® to a fleet. For more information see .

Navigate to your and login in

Navigate to the correct fleet and device

Select the Device Variables page. You will see a list of all of the device's variables with override buttons next to each variable

Click the override button next to the MOBIUS_LICENCE variable

In the popup delete the text <replace with your licence code> and enter your licence code

Leave all other settings as their default values and click the Add button

Your licence code will be shown in the Device Variables list (see for more information on all of the device variables shown in this list)

MobiusFlow® will restart to install the licence

Updating or Replacing a Licence

Under some circumstances it may be necessary to enter a new licence code. In order to make the new licence code work follow the procedure above to enter a new code

You will also need to tell MobiusFlow® to renew its licence by setting the Device Variable MOBIUS_LICENCE_RENEW to true

Click the override button next to the MOBIUS_LICENCE_RENEW variable

In the popup change the value from false to true

Leave all other settings as their default values and click the Add button

Wait for MobiusFlow® to restart, confirm that the new licence is working and reset the Device Variable MOBIUS_LICENCE_RENEW to false

Click the override button next to the MOBIUS_LICENCE_RENEW variable

In the popup change the value from true to false

Leave all other settings as their default values and click the Add button

Hardware Requirements

Raspberry Pi

A Raspberry Pi is required. Currently supported Raspberry Pi models include:

• Raspberry Pi 4

• Raspberry Pi 5

An SD card for each Raspberry Pi is required to store the connector image. We recommend a minimum storage of 8GB.

Transceiver Hardware

Most protocol types require specific hardware to translate that protocol to the Raspberry Pi.

EnOcean

The following transceiver types are supported. Only 1 is required per Pi:

Etching SD Image

BalenaCloud

MobiusFlow Raspberry Pi connectors run Balena OS. Athlough not required, if your organisation registers with BalenaCloud, Balena OS grants a direct VPN link to the connector, allowing configuration changes to be made over the internet.

When using more than 5 devices, BalenaCloud becomes a piad service. As such, we offer versions of the Balena images which do not support remote access and therefore do not require a subscription to BalneaCloud.

Without Remote Access

The following, no remote access images can be downloaded:

With Remote Acccess

The following is an overview of the steps involved to use BalenaCloud with MobiusFlow RPI connectors:

1. Create BalenaCloud Account

2. Create BalenaCloud Fleet

3. Attach BalenaCloud Fleet to the corresponding MobiusFlow Connector Balena Application

4. Add a new device to the fleet and download the subsequent Balena image

5. Etch the image

We have a full guide on how to use the BalenaCloud with MobiusFlow itself . Please note

Etching

We recommend using the to etch the images onto an SD Card. The tool is self-explanatory, but full full documentation of how to use the tool can be found .

BalenaCloud charges hosting fees when more than 5 devices are associated to the account. If remote access to the Connector confiruation is not required, the device can be deleted from the BalenCloud fleet. The Connector software running on the device will remain, and the device will operate as normal.

MobiusFlow has been containerised and is run via docker.

Mobius v1.X.X

Below is an example docker-compose.yml file you could use when running MobiusFlow. In this example, an online version of MobiusFlow 1.19.1 is used. Note that, as well as the MobiusFlow service (labelled simply 'mobius'), the file also containers a reference to an nginx and mongodb containers.

The nginx container is used for port mapping, and mongodb container used as a database. Neither of these are required to run MobiusFlow.

version: "3.8"

volumes:
  mobius-data:
  mobius-licence:
  mongodb:

networks:
  frontend:
  backend:

services:
  mobius:
    platform: linux/amd64
    build: ./dist
    image: local/mobiusflow-docker:1.19.1_1.19.1
    container_name: mobiusflow
    privileged: false
    restart: always
    environment:
      - MOBIUS_HUB_RESET_PSKS=true
      - MOBIUS_ENABLE_CONFIG_UI=true
      - MOBIUS_HUB_ID=000001
      - MOBIUS_LOCAL_TIMEOUT=10000
      - MOBIUS_LOG_SERVICE_STATUS=
      - MOBIUS_LICENCE=38782095-410e7ab5-c3c36a84-dd39683f-c5a8062b-78f846c2-52588c49-fc8eecf4
      # - MOBIUS_LICENCE_KEY=
      # - MOBIUS_LICENCE_TOKEN=
      # - MOBIUS_LICENCE_RESET=
      - MOBIUS_ENGINE_API_PORT=8443
      - MOBIUS_ENGINE_API_AUTH_PROVIDER=local
    volumes:
      - mobius-data:/data
      - mobius-licence:/.licence
    networks:
      - backend
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "10"
  nginx:
    image: ghcr.io/mobiusflow/nginx-cloud:1.1.0
    container_name: nginx
    privileged: false
    restart: always
    environment:
      - NGINX_UI_CONTAINER=mobius
    ports:
      # these ports are for use with the nginx TLS terminator use in mobius-cloud-install
      - 8080:8080
      - 8443:8443
      - 1883:1883
      - 30814:30815
      - 30817:30817
    networks:
      - frontend
      - backend
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "10"
  mongodb:
    image: bitnami/mongodb:latest
    container_name: mongodb
    restart: always
    environment:
      - MONGODB_ROOT_PASSWORD=r5DybE57qug3WaHebeUy2bAvvVhKXUWHD
      - MONGODB_USERNAME=mobius
      - MONGODB_PASSWORD=RmzsXQYReLHaCS5wWGjAPjtJ7VnTw4qL
      - MONGODB_DATABASE=mobius
    volumes:
      - mongodb:/bitnami/mongodb
    networks:
      - backend
    logging:
      driver: none

This file can also be downloaded here:

Licensing

It is important to include the correct licensing information within the environment variables of your docker-compose.yml file.

See the main article on licensing for a full explanation of what is required for online and offline licensing as well updating a given licence.

Mobius system

A typical MobiusFlow system consists of a single or multiple MobiusFlow nodes connected together via a TCP/IP network. Each node is capable of operating independently of the rest of the system, but nodes can interact with each other to form a complex system. All node interaction takes place through one or more brokers via a node’s router.In a multi-node system, the location of the broker is not important. It can reside on the same device as one of the nodes or on an independent device.

Each node is classed as, and exhibits the behavior of, an edge computing device. In this context edge devices are not only field devices but could also be on the edge of a server or cloud server providing the server with connectivity to all of the true edge or field devices.

Mobius nodes

A Mobius node consists of a central Mobius hub, one or more Mobius services and optionally one or more Mobius routers.

Services contain the service logic and an object data store. Connections to sensors, actuators and other communication interfaces such as Modbus or BACnet can be added depending on the service’s purpose and controlled through the service's logic.

The object data store models the physical or virtual connections and provides a standardised method for services and other nodes to communicate and share data with each other through Mobius objects.

All of the communications between services through the hub or nodes through routers and brokers is based on the MQTT protocol. The MobiusFlow protocol has been defined on top of this MQTT protocol providing a well-defined API enabling different physical devices and protocols to communicate with each other in a consistent way.

Mobius nodes follow the microservice architecture pattern, where each service is a stand-alone process capable of communication with other microservices creating a large application from small manageable pieces.

Routers are used to cross node boundaries. They provide a secure mechanism for nodes to share data using the MobiusFlow protocol.

Logical structure of a node

The logical structure of a node is detailed below. This diagram shows the hierarchical relationship between all of the parts which make up a node and how objects contain resources, services contain objects and hubs connect to services and routers.

The Mobius URI structure allows addressing any part of a node at any depth.

Hubs

A Mobius hub is the foundation of a node. At its heart, a Mobius hub is just an MQTT broker which manages and links Mobius services and Mobius routers. Hubs are responsible for ensuring that all services and routers are valid members of a node by verifying their pre-shared authentication key on connection.

Each hub within a Mobius system is given a unique ID. This is a six digit hex number which forms the first part of the Mobius URI hierarchy. When referencing a hub, for example during a discovery process, this unique ID must be used (see MobiusFlow Uniform Resource Identifiers).

When service or router connects to a hub, and has been validated, the hub provides it with a copy of the Mobius object profiles and pre-shared keys files, ensuring that all services and routers connected to the hub are able to communicate and understand one another.

Services

Mobius services are the engines which drive MobiusFlow. Each service is essentially a microservice performing a specific task and possibly acting as an interface to a piece of hardware or a 3rd party service such as Microsoft's Azure platform or the IBM Cloud.

All services MUST implement the full MobiusFlow protocol to enable them to connect to hub and communicate with other services. In addition to implementing the MobiusFlow protocol, services can create Mobius objects to store and share data and can also contain service specific logic to perform the task that they are designed for. When creating services, try an keep them focused on one task and create additional services to perform other tasks. This ensures that services are reusable and Mobius systems can be configured to only contain the logic that they require.

Each service within a Mobius node is given a unique ID. This is a three digit hex number which forms the second part of the Mobius URI hierarchy. When referencing a service, for example during a discovery process, this unique ID must be used.

Routers

Mobius routers control all MobiusFlow communication into and out of a node. This ensures that nodes are secure and allows nodes to discover each other within a MobiusFlow system.

Routers are split into two parts, one side of the router communicates internally with its associated hub and all of the services within a node, while the other side of the router communicates externally through a 'no-mans' broker to other routers on other nodes. All external communication is done using MQTT over the WebSocket protocol. This could be done over a secure or non-secure connection (ws:// or wss://).

Routers are capable of routing messages between services belonging to different nodes, essentially allowing a service on one node to read, write and subscribe to change-of-value events on objects in another node.

Mobius objects

The key to the MobiusFlow system is Mobius objects. These objects typically model real-world objects and provide a mechanism for sharing data and storing state in a consistent way. Each object has a unique identifier or Mobius URI which can be discovered and used by any part of the MobiusFlow system.

Mobius objects are predefined in an object profiles file which is passed to a services by the hub when a service connects.

Each object within a Mobius node is given a unique ID. This ID consists of two parts and is made up of the object profile ID (PID) which describes the object's type, and the object's instance number (INS). The PID is a four digit hex number which forms the third part of the Mobius URI hierarchy and the INS is a four digit hex number which forms the fourth part of the Mobius URI hierarchy. When referencing an object, for example during a discovery process, this unique ID must be used.

Object resources

Mobius objects contain one or more resources. It is these resources which are used to define objects that mimic or represent real-world objects. An example of a single object is a room temperature sensor. This object may have resources which define the sensor’s name, location, asset reference, engineering units, set point and actual measured value.

Each resource is capable of storing a single value which can currently be of type Boolean, Number, String, DateTime or TimeSpan. Resources also store meta-data about the value. The actual meta-data depends on the value type chosen. Resources can be read only or read/write. Read only resources have their values set when they are created.

Each resource within an object is given a unique ID. This is a two digit hex number which forms the fifth and final part of the Mobius URI hierarchy. When referencing a resource, for example during a read, this unique ID must be used.

Present value and the priority array

Resources store their values in a priority array. This priority array works in a similar manner to a BACnet priority array. The array has 16 possible locations with location 1 being the highest priority and location 16 being the lowest priority.

When reading the value of a resource the actual value is returned in the PV(present value) property. The PV is always equal to the value of the highest active (non null) priority in the resource's priority array.

{null,null,null,null,null,null,null,null,null,null,null,null,null,null,12,null} -> PV = 12 (priority 15)
{null,null,null,null,null,null,null,null,56,null,null,null,null,null,12,null} -> PV = 56 (priority 9)
{null,null,78.5,null,null,null,null,null,56,null,null,null,null,null,12,null} -> PV = 78.5 (priority 3)

balenaCloud devices are configured using Device Variables. When deploying MobiusFlow® to a balenaCloud fleet a number of Device Variables are created with default values. These are defined at the fleet level but can be overridden at the device level. More information about working with balenaCloud Device Variables can be found here.

MobiusFlow Device Variables

The image below shows the Device Variables created when MobiusFlow® is deployed to balenaCloud.

Expand the items below for detailed information on each Device Variable

Within a MobiusFlow system all hubs, services, objects and resources are identified by a unique address known as a Uniform Resource Identifier or URI. These URIs are hierarchical so given the URI for a Mobius resource it is possible to identify which object the resource belongs to, what the object type is, which service the object belongs to and which Mobius node the service is running on.

Mobius URI Definition

An object’s URI (or name) is defined in 4 parts, namely the hub ID (HID), service ID (SID), object profile ID (PID) and instance number (INS). A fifth part is added when accessing a specific resource, the resource ID (RID).

Each part of an object’s URI is a uppercase string of a defined length (as shown in the table below). The URI’s parts are separated with a forward slash (/).

A full URI is typically defined as HID/SID/PID/INS/RID.

It is possible to address any part of the system by only using the required parts of the URI. e.g. to address a service only the first two parts of the URI are used HID/SID and to address an object only the first four parts are used HID/SID/PID/INS.

An example of an object URI for an object of instance 1, profile 3A, created by service 1F connected to hub 1 is:

000001/01F/003A/0001

and if addressing resource 40 on that object the full URI would be:

000001/01F/003A/0001/40

Mobius URI Wildcards

Under certain conditions, such as subscribing to a resource’s change of value event, it is possible to use wildcards in the URI. These wildcards are described in the table below and follow the MQTT standard.

Power Options

You have three options to power the connector

Network Options

You can connect to your network via wired Ethernet or 2.4GHz WiFi

Front Panel

The image and table below describe the connections and LED indicators on the front panel of the connector.

Product Label

The product label is on the bottom of the connector. It shows the , software version and serial number of the product.

Mobius system

A typical MobiusFlow system consists of a single or multiple MobiusFlow nodes connected together via a TCP/IP network. Each node is capable of operating independently of the rest of the system, but nodes can interact with each other to form a complex system. All node interaction takes place through one or more brokers via a node’s router.In a multi-node system, the location of the broker is not important. It can reside on the same device as one of the nodes or on an independent device.

Each node is classed as, and exhibits the behavior of, an device. In this context edge devices are not only field devices but could also be on the edge of a server or cloud server providing the server with connectivity to all of the true edge or field devices.

Mobius nodes

A Mobius node consists of a central Mobius hub, one or more Mobius services and optionally one or more Mobius routers.

Services contain the service logic and an object data store. Connections to sensors, actuators and other communication interfaces such as Modbus or BACnet can be added depending on the service’s purpose and controlled through the service's logic.

The object data store models the physical or virtual connections and provides a standardised method for services and other nodes to communicate and share data with each other through Mobius objects.

All of the communications between services through the hub or nodes through routers and brokers is based on the protocol. The MobiusFlow protocol has been defined on top of this MQTT protocol providing a well-defined API enabling different physical devices and protocols to communicate with each other in a consistent way.

Mobius nodes follow the architecture pattern, where each service is a stand-alone process capable of communication with other microservices creating a large application from small manageable pieces.

Routers are used to cross node boundaries. They provide a secure mechanism for nodes to share data using the MobiusFlow protocol.

Logical structure of a node

The logical structure of a node is detailed below. This diagram shows the hierarchical relationship between all of the parts which make up a node and how objects contain resources, services contain objects and hubs connect to services and routers.

The Mobius URI structure allows addressing any part of a node at any depth.

Hubs

A Mobius hub is the foundation of a node. At its heart, a Mobius hub is just an MQTT broker which manages and links Mobius services and Mobius routers. Hubs are responsible for ensuring that all services and routers are valid members of a node by verifying their pre-shared authentication key on connection.

Each hub within a Mobius system is given a unique ID. This is a six digit hex number which forms the first part of the Mobius URI hierarchy. When referencing a hub, for example during a discovery process, this unique ID must be used (see ).

When service or router connects to a hub, and has been validated, the hub provides it with a copy of the Mobius object profiles and pre-shared keys files, ensuring that all services and routers connected to the hub are able to communicate and understand one another.

Services

Mobius services are the engines which drive MobiusFlow. Each service is essentially a microservice performing a specific task and possibly acting as an interface to a piece of hardware or a 3rd party service such as Microsoft's Azure platform or the IBM Cloud.

All services MUST implement the full MobiusFlow protocol to enable them to connect to hub and communicate with other services. In addition to implementing the MobiusFlow protocol, services can create Mobius objects to store and share data and can also contain service specific logic to perform the task that they are designed for. When creating services, try an keep them focused on one task and create additional services to perform other tasks. This ensures that services are reusable and Mobius systems can be configured to only contain the logic that they require.

Each service within a Mobius node is given a unique ID. This is a three digit hex number which forms the second part of the Mobius URI hierarchy. When referencing a service, for example during a discovery process, this unique ID must be used (see ).

Routers

Mobius routers control all MobiusFlow communication into and out of a node. This ensures that nodes are secure and allows nodes to discover each other within a MobiusFlow system.

Routers are split into two parts, one side of the router communicates internally with its associated hub and all of the services within a node, while the other side of the router communicates externally through a 'no-mans' broker to other routers on other nodes. All external communication is done using MQTT over the protocol. This could be done over a secure or non-secure connection (ws:// or wss://).

Routers are capable of routing messages between services belonging to different nodes, essentially allowing a service on one node to read, write and subscribe to change-of-value events on objects in another node.

Mobius objects

The key to the MobiusFlow system is Mobius objects. These objects typically model real-world objects and provide a mechanism for sharing data and storing state in a consistent way. Each object has a unique identifier or which can be discovered and used by any part of the MobiusFlow system.

Mobius objects are predefined in an object profiles file which is passed to a services by the hub when a service connects.

Each object within a Mobius node is given a unique ID. This ID consists of two parts and is made up of the object profile ID (PID) which describes the object's type, and the object's instance number (INS). The PID is a four digit hex number which forms the third part of the Mobius URI hierarchy and the INS is a four digit hex number which forms the fourth part of the Mobius URI hierarchy. When referencing an object, for example during a discovery process, this unique ID must be used (see ).

Object resources

Mobius objects contain one or more resources. It is these resources which are used to define objects that mimic or represent real-world objects. An example of a single object is a room temperature sensor. This object may have resources which define the sensor’s name, location, asset reference, engineering units, set point and actual measured value.

Each resource is capable of storing a single value which can currently be of type Boolean, Number, String, DateTime or TimeSpan. Resources also store meta-data about the value. The actual meta-data depends on the value type chosen. Resources can be read only or read/write. Read only resources have their values set when they are created.

Each resource within an object is given a unique ID. This is a two digit hex number which forms the fifth and final part of the Mobius URI hierarchy. When referencing a resource, for example during a read, this unique ID must be used (see ).

Present value and the priority array

Resources store their values in a priority array. This priority array works in a similar manner to a priority array. The array has 16 possible locations with location 1 being the highest priority and location 16 being the lowest priority.

When reading the value of a resource the actual value is returned in the PV(present value) property. The PV is always equal to the value of the highest active (non null) priority in the resource's priority array.

Within a MobiusFlow system all hubs, services, objects and resources are identified by a unique address known as a Uniform Resource Identifier or URI. These URIs are hierarchical so given the URI for a Mobius resource it is possible to identify which object the resource belongs to, what the object type is, which service the object belongs to and which Mobius node the service is running on.

Mobius URI Definition

An object’s URI (or name) is defined in 4 parts, namely the hub ID (HID), service ID (SID), object profile ID (PID) and instance number (INS). A fifth part is added when accessing a specific resource, the resource ID (RID).

Each part of an object’s URI is a uppercase string of a defined length (as shown in the table below). The URI’s parts are separated with a forward slash (/).

A full URI is typically defined as HID/SID/PID/INS/RID.

It is possible to address any part of the system by only using the required parts of the URI. e.g. to address a service only the first two parts of the URI are used HID/SID and to address an object only the first four parts are used HID/SID/PID/INS.

An example of an object URI for an object of instance 1, profile 3A, created by service 1F connected to hub 1 is:

000001/01F/003A/0001

and if addressing resource 40 on that object the full URI would be:

000001/01F/003A/0001/40

Mobius URI Wildcards

Under certain conditions, such as subscribing to a resource’s change of value event, it is possible to use wildcards in the URI. These wildcards are described in the table below and follow the MQTT standard.

The ports in used by Mobius Gateways. These are for services that can be hosted on the Gateway.

The physical gateways fleet management and remote connectivity service require outbound access to these services

MobiusFlow with LoRaWAN Stack

It is optional to include the LoRaWAN Stack when specifying the hosting type on instance creation. This Stack will grant the ability to use the MobiusFlow LoRaWAN LNS.

If included, an instance of Chirpstack and it associated infrastructure will be hosted in the background. Accessing this is not necessary to use the LNS, however it is accessible if required. Full details can be found within the LNS Service documentation.

Port Mappings (Simple)

The table below shows a simple overview illustrating how the ports are mapped. This is a simple overview suitable for most users.

Port Mappings (Advance)

Docker & Docker Routing

Different parts of the MobiusFlow solution run in different docker containers. These communicate via docker routing. Docker routing allows container names to be resolved in the Host OS, for example, to refer to the Mobius Engine API from the Host OS or a container that is not the mobius container, one could use mobius:8442 (container name followed by Host OS Port).

This means that, if communication between containers is required, the Host OS port and container is required. As such, these are included in the advanced port mappings table below.

Full Mappings

The table below gives a full description of the port mappings a MobiusFlow Cloud hosted environment is subject to.

Accessing Configuration Page

Via Balena Fleet

If the Connector is hosted via BalenaCloud and has an internet connection, the configuration can be accessed anywhere via the BalenaCloud Public Device URL.

MobiusFlow Hosted

If the connector is hosted by MobiusFlow, please contact support to receive the Public Device URL.

Self Hosted

The BalenaCloud Public Device URL can be found by Navigating to the connector device on the BalenaCloud fleet.

Via Raspberry Pi Access Point

By default, the MobiusFlow connector will broadcast a WiFi access point, the name of which matches the connector's serial number (in the form of MF_XXXXX). Connect to this access point on a computer or mobile device. Then the configuration window is accessible by browsing to 10.42.0.1.

Via Local Network

If the connector is connected to a local network via Ethernet or WiFi (with a known IP address) and you're able to also connect to this network using a computer or mobile device, then simple browse to the local IP of the connector.

Login & Home

Login

When browsed to the configuration window of the connector, a login screen is presented.

The default password of all new MobiusFlow connectors is:

mobiusflow

Note that, if the connector is not new, this login password may have been changed.

Home Page

When on the the home page, the current status of the connector is shown. This includes:

The main menu also allows navigation to the connectors configuration pages. These includes those for Network Configuration, MQTT Configuration, Certification Configuration, and the Change Password page (allows the connector configuration password to be changed).

Configure Network

It is critical that the MobiusFlow connector's network situation is such that it can access the target MobiusFlow instance over the network. This may be over the internet or simply over a local network.

In either situation, the connector must be connected to the network and the configure network page allows for this.

Connection Type

The connection type allows choosing between a Wired or WiFi connection.

If using a Wired connection, ensure the Raspberry Pi is plugged in via Ethernet.

If using WiFi mode, the WiFi SSID and corresponding password must be populated.

TCP/IP Settings

The TCP/IP settings allow switching between DHCP and Static IP allocation. Unless there are specific reasons to set the connector on a static IP address, using DHCP is recommended.

If using the connector in Static mode, the Subnet Mask, Default Gateway and DNS 1 can be set. If it is not clear what to use here, use the default settings as shown below.

Note that, the default gateway is not required however if the connector required access to the internet, the local IP address of the internet providing gateway (Network router / modem) must be populated here. This is often in the form XXX.XXX.XXX.1 or XXX.XXX.XXX.0 .

WiFi Access Point

Setting the connector up to be a WiFi access point is useful for two reasons.

Firstly, it allows you to connect to it, allowing for easy wireless access to its configuration page. Secondly, if this connector has internet access via ethernet, it can act as an internet enabled hotspot to connect WiFi device to, in-turn giving them internet access.

If the WiFi access point is enabled, a WiFi SSID and Password must be set. It is recommended the default SSID is used (This matches the the connectors Serial Number)

Saving Changes

To save the changes click the save button. If there are an issues with the configuration, such as an invalid input in one of the fields, the form will show this and the changes will not be saved. If the settings were saved correctly, a pop up will show this after the save button has been clicked.

Configure MQTT

Overview

Connectors use MQTT to communicate with MobiusFlow. As such, the Configure MQTT page allows the connector to be pointed at a specific MQTT broker. In almost all cases, the broker will be running the MobiusFlow instance itself.

Before setting up the connector's MQTT configuration, ensure you first set up the MobiusFlow instance ready for this connection. A guide on how to do this can be found here.

Configuration Window

The configuration window shows the key 6 properties which must configured to allow an authorised connection to the MQTT broker.

Explanation of Properties

Saving Changes

To save the changes click the save button. If there are an issue with the configuration, such as an invalid input in one of the fields, the form will show this and the changes will not be saved. If the settings were saved correctly, a pop up will show this after the save button has been clicked.

Realising Changes

Once the changes have been made locally, to implement the changes within the connector, click the Reconfigure and Reboot button.

This will cause the connector to reboot. As such, the configuration window's connection to the connector will be lost. This may automatically be restored once the connector reboots, but this may not be the case if the connector's configuration has changed such that it is no longer accessible over the network.

Introduction

MobiusFlow is a software platform designed for control and monitoring of sensors and actuators in simple (single instance) or complex (multiple instances working together) systems (see for more info). It has a microservice based architecture where each microservice can contain both application logic and object state. Object types are predefined and contain any number of resources which represent the values associated to an object’s attributes (e.g. a temperature sensor may contain resources for Name, Location, Temperature etc.). A MobiusFlow node (a single instance of the software) contains a central hub and one or more microservices. All microservices contain an MQTT client and communicate with each other via the hub which is an MQTT broker. The broker is responsible for authenticating the services when they connect. The TCP/IP port used for internal MQTT comms is normally firewalled off to prevent any external traffic and all messages passed between microservices are encoded using to ensure message integrity. If communication is required between Mobius nodes, a Mobius router is added to the configuration. This is a special microservice which handles external traffic between Mobius nodes. All traffic passed through a router is encoded with JWTs using pre-shared keys (PSKs) specifically for this purpose ensuring that no internal PSKs leave a Mobius node. External traffic is also MQTT based and can be secured with TLS if required. One of the most important part of MobiusFlow is the “ Mobius protocol” over MQTT. This is a predefined set of MQTT topics based around the Mobius object URIs which allows “two way point to point” messaging via MQTT. This means that Mobius nodes and microservices can discover other nodes, services, objects and resources and microservices can read and write resource values on objects belonging to any other microservice on any node within a Mobius system. In addition to reading a writing, a microservice can subscribe to object or resource level change of value (COV) messages. The MobiusFlow protocol is similar to the LWM2M protocol but over MQTT.

The is designed to allow efficient communication for IoT Devices whilst providing structure and definable trust boundaries.

There are 2 ways to move messages to and from a one is via the designed for this task, and preserving the integrity of the the message within the node. the other is with a dedicated , this breaches that integrity to a degree but may be desirable and even necessary in some situations.

Node Internal Communication

With Each node consisting of the base of a hub and one or more services, and optionally routers. If for the purpose of this initial discussion assume that the services are only communicating with local hardware, or handling logic, therefore having no mechanism for communicating off of the local hardware. We will discuss how this can be achieved later on.

As the hub is created a pre-shared key (psk) file is generated, these can also be changed using the configuration service. each valid service must have a copy of its psk, to successfully authenticate with the hub. The hub will have the corresponding psk in its psk file. This key is used as a secret key as part of a .

Service Authentication

When a service connects to a hub it uses the . The MQTT username is the service's and 001F/01F and the MQTT password is a JSON object containing the services PID and SID with a timestamp which is then converted into a JWT (JSON Web Token). The time stamp ensures tight time synchronisation is a requirement and provides greater integrity.

If the service signs its JWT with the same psk as is stored in the hub's psk file it will successfully complete the authentication process to the hub. On doing this it will be sent a copy of the hubs psk file, giving the service the ability to the received directly signed messages from authorised services.

After successful authentication the service will have a copy of the psk of all services that are authorised to communicate through the hub. The service will then with no further action from the hub be able to validate the authenticity and integrity of messages that have come from a service on the same node.

Service Communication

Once passing traffic the MQTT message will consist of:

the JSON Web Token will also carry the topic, the message payload itself, and a timestamp this will all be hashed along with the service own key creating a to allow integrity checking:

The time stamp will allow for the message to have a validity life span that can be configured for all services connected to the hub. Internally all messages will be signed in this way and therefore provide a high degree of integrity to the internal communication.

Services may be intentionally created to connect to external interfaces such as a service the connects to remote I/O via TCP/IP or an Azure IoT hub Client, if it is desired to configure a node in this scenario, it is recommended to utilise two interconnected nodes one that handles the external communications and one that handles the more trusted internal communication, the nodes could exist on the same hardware. doing so would allow the creation of multiple trust boundaries

Node External Communication

Although as just discussed it is not impossible to create service that communicate to external interfaces, it is not recommended to use these on the same node as it compromises the integrity of the node. It is preferable to utilise a known route into and out from the node, it is recommended that this route is a .

Routers are split into two parts, one side of the router communicates internally with its associated hub and all of the services within a node, while the other side of the router communicates externally through a 'no-mans' broker to other routers on other nodes. All external communication is done using MQTT over the protocol. This could be done over a secure or non-secure connection (ws:// or ws s://).

The internal side of the router acts in exactly the same way as a service, but will automatically subscribe to all messages from every other service within that node.

The external side of the router will have the ability to sign its messages in the same fashion as the services do for internal communication, it will have two pre shared keys and internal or service psk and an external psk.

Node Peering

To allow router to validate the authenticity and integrity of messages form other routers, the external psks will be required to be manually shared between all the routers that want to take part in this communication. the result is that the external psk file will contain the keys of all authorised routers and therefore nodes.

This communication is done over the WebSocket protocol as it reduces the need to configure firewalls to allow MQTT communication. node peering is best used in an enclosed environment where there is a high degree of confidence in the integrity of the network with which the communication is taking place. This is like to require the input of network and cyber security professionals.

Node Peering will require the provision of a MQTT broker capable of using . this will be a function that will be optionally provided by the mobius router.

Larger Node Deployments

In larger deployments of nodes peering may not be viable because of the administrative overhead, or there may be low confidence in the network integrity. there may also be a require to not only ensure Authenticity and Integrity of messages, but also confidentiality.

to achieve this the nodes should utilise WebSockets over (TLS), this is in fact simply a upgrade in the same way WebSockets are used, on a connection

In this case it will almost always be easier to provide the node with access to the public internet where things like server name resolution and certificate control are well practised and understood.

Due to the large complexity in provisioning the system in this scenario, It is envisaged at this stage that IAconnects will provide the service that provides the functions of the architecture shown above.

The configuration of the network interfaces of a MobiusFlow® balenaCloud device is handled by the manage microservice. All configuration is stored in a JSON file which can be updated by plugging in a properly configured USB memory stick or through the balenaCloud device terminal.

Network Configuration File Structure

[
  {
    "connection": {
      "enabled": true,
      "type": "ethernet",
      "id": "Wired connection 1",
      "interface-name": "enp2s0"
    },
    "ipv4": {
      "method": "auto",
      "address": "",
      "prefix": 24,
      "gateway": "",
      "dns": ""
    }
  },
  {
    "connection": {
      "enabled": true,
      "type": "ethernet",
      "id": "Wired connection 2",
      "interface-name": "enp3s0"
    },
    "ipv4": {
      "method": "manual",
      "address": "192.168.1.100",
      "prefix": 24,
      "gateway": "",
      "dns": ""
    }
  },
  {
    "connection": {
      "enabled": false,
      "type": "wifi",
      "id": "WiFi connection 1",
      "interface-name": "wlp4s0"
    },
    "ipv4": {
      "method": "auto",
      "address": "",
      "prefix": 24,
      "gateway": "",
      "dns": ""
    },
    "wifi": {
      "ssid": ""
    },
    "wifi-security": {
      "psk": "",
      "auth-alg": "open",
      "key-mgmt": "wpa-psk"
    }
  },
  {
    "connection": {
      "enabled": false,
      "type": "hotspot",
      "id": "WiFi hotspot 1",
      "interface-name": "wlp4s0"
    },
    "wifi": {
      "ssid": "",
      "channel": 6
    },
    "wifi-security": {
      "psk": "",
      "key-mgmt": "wpa-psk"
    }
  },
  {
    "connection": {
      "enabled": true,
      "type": "gsm",
      "id": "GSM connection 1",
      "interface-name": "cdc-wdm0"
    },
    "gsm": {
      "apn": "arkessa.com",
      "username": "arkessa",
      "password": "arkessa"
    }
  }
]

[
  {
    "connection": {
      "enabled": true,
      "type": "ethernet",
      "id": "Wired connection 1",
      "interface-name": "eth0"
    },
    "ipv4": {
      "method": "auto",
      "address": "",
      "prefix": 24,
      "gateway": "",
      "dns": ""
    }
  },
  {
    "connection": {
      "enabled": false,
      "type": "wifi",
      "id": "WiFi connection 1",
      "interface-name": "wlan0"
    },
    "ipv4": {
      "method": "auto",
      "address": "",
      "prefix": 24,
      "gateway": "",
      "dns": ""
    },
    "wifi": {
      "ssid": ""
    },
    "wifi-security": {
      "psk": "",
      "auth-alg": "open",
      "key-mgmt": "wpa-psk"
    }
  },
  {
    "connection": {
      "enabled": false,
      "type": "hotspot",
      "id": "WiFi hotspot 1",
      "interface-name": "wlan0"
    },
    "wifi": {
      "ssid": "",
      "channel": 6
    },
    "wifi-security": {
      "psk": "",
      "key-mgmt": "wpa-psk"
    }
  }
]

Editing the Network Configuration

Using the balenaCloud Device Terminal

Navigate to your balenaCloud dashboard and login in

Navigate to the Device Summary page of the device you want to configure

Open a terminal in the manage microservice

Change to the /data/.mobius/manage directory and edit the networks.json file by running the following commands:

cd /data/.mobius/manage
vi networks.json

This will open the network configuration file for editing using the vi editor

Make any required changes and save the file

Exit the terminal and restart the manage microservice by clicking on the restart icon next to the manage service

Using a USB Memory Stick

Using a USB memory stick to update the network interfaces is useful when none of the network interfaces is configured to connect to the internet so it is not possible to use the balenaCloud device terminal. You will obviously need physical access to the device to use this method.

Format the USB memory stick as FAT32

Rename the USB memory to MOBIUSCONF

Create a file on the USB memory stick called networks.json

Open the file on your laptop or PC in your favourite text editor and paste in the correct JSON configuration from the examples above

Make any required changes

Save the file and unplug the USB memory stick from your laptop or PC

Plug the USB memory stick into any of the USB ports on your device

Reboot your device

When the device reboots it will copy the networks.json onto the device and use the new configuration for its network interfaces (this will take a minute or two)

You can then remove the USB memory stick and your device will continue to use the new network configuration.

The Connector collects data from sensors and sends data to actuators via standard wireless sensor protocols such as EnOcean and Workplace Occupancy, and sends this data securely to a MobiusFlow using an MQTT based Protocol.

Once the data has been received by a MobiusFlow instance, it is decoded and the associated MobiusFlow object is updated with the latest sensor readings which can then be processed by the gateway.

A full guide on configuring MobiusFlow for use with Connectors can be found here.

Connector Options

There are several hardware options for the MobiusFlow Connector software:

• Official Connector

• Raspberry Pi

Technologies Referenced

This section outlines the major technologies reference in this training. Learning about this technologies is recommended.

MQTT

MQTT (Message Queuing Telemetry Transport) is a lightweight and efficient publish-subscribe messaging protocol, commonly used in IoT (Internet of Things) applications.

MQTT is widely used for data transport throughout the MobiusFlow software.

JSON

JSON (JavaScript Object Notation) is a lightweight data interchange format that is easy for humans to read and write, and easy for machines to parse and generate.

Learn how JSON works here.

A basic knowledge of JSON is required when using the Flows (logic engine) within MobiusFlow.

EnOcean

EnOcean is a short distance wireless communication protocol used widely within the IoT space. Each EnOcean device has a unique identifier (UID) which is used to identify the sender of all EnOcean wireless telegrams.

During this training, EnOcean will be used as an exemplar IoT technology to demonstrate MobiusFlow from the device level.

MobiusFlow Overview

Structure

A MobiusFlow instance runs a central MobiusFlow Hub. Services, each of which have a function within the overall solution, reside on the hub, and use it as a relay to communicate information.

A MobiusFlow object often represents a virtual equivalent of a real-world device, however can represent non-physical entities such as calculated data.

Some services can have MobiusFlow objects reside on them, often when the service needs to directly interact with those objects in some way. For example, objects representing EnOcean devices will always reside on an EnOcean devices service.

Points / Resources

A MobiusFlow object contains many resources, each being its own individual data stream representing something about that object.

Below shows a screenshot from the MobiusFlow software of the list of resources associated to an EnOcean Temperature / Humidity / C02 sensor.

A point is a chargeable resource. Notice in the above screenshot, the points column is only populated for Temperature, Humidity and CO2.

Also notice how the MobiusFlow software calculates your total point usage and displays this at the bottom right hand corner.

URIs

All parts of the MobiusFlow hierarchy are assigned a unique URI with the following structure:

HID/SID/PID/INS/RID

Example URIs

Service

Full example URI of a service:

000001/020

Representing service 020 on hub 000001.

Object

Full example URI of an object:

000001/020/0028/0001

Representing instance 0001 of object type (profile) 0028 on service 020 on hub 000001.

Resource

Full example URI of a resource:

000001/020/0028/0001/40

Representing resource 40 on instance 0001 of object type (profile) 0028 on service 020 on hub 000001.

Conclusion

Using the URI system, it is therefore possible to reference any component of a given MobiusFlow configuration.

Configuration Example

Example Overview

This aims to show how data taken from EnOcean sensors at a hardware level, is brought into and through the MobiusFlow system, and then presented in the form of a dashboard.

Project Schematic

The following shows a colorless project schematic representing lack of implementation. As the project is implemented, this diagram will be colored in so progress can easily shown.

Explanation of Services

MobiusFlow Configuration

MQTT Broker